diff options
Diffstat (limited to 'Documentation')
368 files changed, 13273 insertions, 3233 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 1c3771e..a48448d 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -10,7 +10,6 @@ howto-index.txt doc.dep cmds-*.txt mergetools-*.txt -manpage-base-url.xsl SubmittingPatches.txt tmp-doc-diff/ GIT-ASCIIDOCFLAGS diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 4c756be..ab39509 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -1,5 +1,5 @@ -Like other projects, we also have some guidelines to keep to the -code. For Git in general, a few rough rules are: +Like other projects, we also have some guidelines for our code. For +Git in general, a few rough rules are: - Most importantly, we never say "It's in POSIX; we'll happily ignore your needs should your system not conform to it." @@ -24,7 +24,7 @@ code. For Git in general, a few rough rules are: "Once it _is_ in the tree, it's not really worth the patch noise to go and fix it up." - Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + Cf. https://lore.kernel.org/all/20100126160632.3bdbe172.akpm@linux-foundation.org/ - Log messages to explain your changes are as important as the changes themselves. Clearly written code and in-code comments @@ -40,7 +40,7 @@ As for more concrete guidelines, just imitate the existing code contributing to). It is always preferable to match the _local_ convention. New code added to Git suite is expected to match the overall style of existing code. Modifications to existing -code is expected to match the style the surrounding code already +code are expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). But if you must have a list of rules, here are some language @@ -162,8 +162,6 @@ For shell scripts specifically (not exhaustive): - We do not use \{m,n\}; - - We do not use -E; - - We do not use ? or + (which are \{0,1\} and \{1,\} respectively in BRE) but that goes without saying as these are ERE elements not BRE (note that \? and \+ are not even part @@ -190,6 +188,10 @@ For shell scripts specifically (not exhaustive): hopefully nobody starts using "local" before they are reimplemented in C ;-) + - 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. + For C programs: @@ -204,10 +206,19 @@ For C programs: by e.g. "echo DEVELOPER=1 >>config.mak". - We try to support a wide range of C compilers to compile Git with, - including old ones. You should not use features from newer C + including old ones. As of Git v2.35.0 Git requires C99 (we check + "__STDC_VERSION__"). You should not use features from a newer C standard, even if your compiler groks them. - There are a few exceptions to this guideline: + New C99 features have been phased in gradually, if something's new + in C99 but not used yet don't assume that it's safe to use, some + compilers we target have only partial support for it. These are + considered safe to use: + + . since around 2007 with 2b6854c863a, we have been using + initializer elements which are not computable at load time. E.g.: + + const char *args[] = {"constant", variable, NULL}; . since early 2012 with e1327023ea, we have been using an enum definition whose last element is followed by a comma. This, like @@ -223,18 +234,24 @@ For C programs: . since early 2021 with 765dc168882, we have been using variadic macros, mostly for printf-like trace and debug macros. - These used to be forbidden, but we have not heard any breakage - report, and they are assumed to be safe. + . since late 2021 with 44ba10d6, we have had variables declared in + the for loop "for (int i = 0; i < 10; i++)". + + New C99 features that we cannot use yet: + + . %z and %zu as a printf() argument for a size_t (the %z being for + the POSIX-specific ssize_t). Instead you should use + printf("%"PRIuMAX, (uintmax_t)v). These days the MSVC version we + rely on supports %z, but the C library used by MinGW does not. + + . Shorthand like ".a.b = *c" in struct initializations is known to + trip up an older IBM XLC version, use ".a = { .b = *c }" instead. + See the 33665d98 (reftable: make assignments portable to AIX xlc + v12.01, 2022-03-28). - Variables have to be declared at the beginning of the block, before the first statement (i.e. -Wdeclaration-after-statement). - - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)" - is still not allowed in this codebase. We are in the process of - allowing it by waiting to see that 44ba10d6 (revision: use C99 - declaration of variable in for() loop, 2021-11-14) does not get - complaints. Let's revisit this around November 2022. - - NULL pointers shall be written as NULL, not as 0. - When declaring pointers, the star sides with the variable @@ -429,8 +446,41 @@ For C programs: detail. - The first #include in C files, except in platform specific compat/ - implementations, must be either "git-compat-util.h", "cache.h" or - "builtin.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 @@ -469,7 +519,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. @@ -497,7 +547,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. @@ -557,7 +607,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. @@ -591,30 +641,30 @@ 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 avoidance of gendered pronouns. - When it becomes awkward to stick to this style, prefer "you" when - addressing the the hypothetical user, and possibly "we" when + 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 @@ -632,53 +682,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: - [<extra>] - (Zero or one <extra>.) + [_<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`] + + 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`)] 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 @@ -689,37 +804,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 f2e7fc1..3f2383a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -21,13 +21,25 @@ MAN1_TXT += $(filter-out \ MAN1_TXT += git.txt MAN1_TXT += gitk.txt MAN1_TXT += gitweb.txt +MAN1_TXT += scalar.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt +MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-chunk.txt +MAN5_TXT += gitformat-commit-graph.txt +MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-pack.txt +MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt +MAN5_TXT += gitprotocol-capabilities.txt +MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-http.txt +MAN5_TXT += gitprotocol-pack.txt +MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt MAN5_TXT += gitweb.conf.txt @@ -51,6 +63,7 @@ HOWTO_TXT += $(wildcard howto/*.txt) DOC_DEP_TXT += $(wildcard *.txt) DOC_DEP_TXT += $(wildcard config/*.txt) +DOC_DEP_TXT += $(wildcard includes/*.txt) ifdef MAN_FILTER MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) @@ -90,31 +103,26 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit -TECH_DOCS += technical/bundle-format -TECH_DOCS += technical/cruft-packs +TECH_DOCS += technical/bitmap-format +TECH_DOCS += technical/bundle-uri TECH_DOCS += technical/hash-function-transition -TECH_DOCS += technical/http-protocol -TECH_DOCS += technical/index-format TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index -TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics -TECH_DOCS += technical/pack-protocol TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone -TECH_DOCS += technical/protocol-capabilities -TECH_DOCS += technical/protocol-common -TECH_DOCS += technical/protocol-v2 TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable +TECH_DOCS += technical/scalar TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow -TECH_DOCS += technical/signature-format TECH_DOCS += technical/trivial-merge +TECH_DOCS += technical/unit-tests SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index @@ -137,14 +145,16 @@ man5dir = $(mandir)/man5 man7dir = $(mandir)/man7 # DESTDIR = +GIT_DATE := $(shell git show --quiet --pretty='%as') + ASCIIDOC = asciidoc ASCIIDOC_EXTRA = ASCIIDOC_HTML = xhtml11 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_CONF = -f asciidoc.conf ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ - -amanversion=$(GIT_VERSION) \ - -amanmanual='Git Manual' -amansource='Git' + -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \ + -arevdate='$(GIT_DATE)' ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) @@ -182,15 +192,7 @@ endif ifndef MAN_BASE_URL MAN_BASE_URL = file://$(htmldir)/ endif -XMLTO_EXTRA += -m manpage-base-url.xsl - -# If your target system uses GNU groff, it may try to render -# apostrophes as a "pretty" apostrophe using unicode. This breaks -# cut&paste, so you should set GNU_ROFF to force them to be ASCII -# apostrophes. Unfortunately does not work with non-GNU roff. -ifdef GNU_ROFF -XMLTO_EXTRA += -m manpage-quote-apos.xsl -endif +XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)' ifdef USE_ASCIIDOCTOR ASCIIDOC = asciidoctor @@ -289,6 +291,8 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-developerinterfaces.txt \ + cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt @@ -330,7 +334,6 @@ clean: $(RM) technical/*.html technical/api-index.txt $(RM) SubmittingPatches.txt $(RM) $(cmds_txt) $(mergetools_txt) *.made - $(RM) manpage-base-url.xsl $(RM) GIT-ASCIIDOCFLAGS $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS) @@ -339,11 +342,15 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS) $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $< -manpage-base-url.xsl: manpage-base-url.xsl.in - $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ +manpage-prereqs := $(wildcard manpage*.xsl) +manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) - $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< +%.1 : %.xml $(manpage-prereqs) + $(manpage-cmd) +%.5 : %.xml $(manpage-prereqs) + $(manpage-cmd) +%.7 : %.xml $(manpage-prereqs) + $(manpage-cmd) %.xml : %.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $< @@ -467,8 +474,19 @@ $(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt .PHONY: lint-docs-man-section-order lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER) +.PHONY: lint-docs-fsck-msgids +LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok +$(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl +$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt + $(call mkdir_p_parent_template) + $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ + ../fsck.h fsck-msgids.txt $@ + +lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) + ## Lint: list of targets above .PHONY: lint-docs +lint-docs: lint-docs-fsck-msgids lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 1da15d9..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] @@ -160,10 +161,11 @@ in order to keep the declarations alphabetically sorted: int cmd_psuh(int argc, const char **argv, const char *prefix); ---- -Be sure to `#include "builtin.h"` in your `psuh.c`. +Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to +`#include "gettext.h"` to use functions related to printing output text. -Go ahead and add some throwaway printf to that function. This is a decent -starting point as we can now add build rules and register the command. +Go ahead and add some throwaway printf to the `cmd_psuh` function. This is a +decent starting point as we can now add build rules and register the command. NOTE: Your throwaway text, as well as much of the text you will be adding over the course of this tutorial, is user-facing. That means it needs to be @@ -736,7 +738,7 @@ the {lore}[Git mailing list archive]: 2022-02-21 1:43 ` John Cai 2022-02-21 1:50 ` Taylor Blau 2022-02-23 19:50 ` John Cai -2022-02-18 20:00 ` // other replies ellided +2022-02-18 20:00 ` // other replies elided 2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget 2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason 2022-02-18 20:26 ` Junio C Hamano @@ -832,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 @@ -1160,32 +1162,32 @@ all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]", and your range-diff will be prefaced with "Range-diff against v1". -Afer you run this command, `format-patch` will output the patches to the `psuh/` +After you run this command, `format-patch` will output the patches to the `psuh/` directory, alongside the v1 patches. Using a single directory makes it easy to refer to the old v1 patches while proofreading the v2 patches, but you will need to be careful to send out only the v2 patches. We will use a pattern like -"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches). +`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches). Edit your cover letter again. Now is a good time to mention what's different between your last version and now, if it's something significant. You do not need the exact same body in your second cover letter; focus on explaining to reviewers the changes you've made that may not be as visible. -You will also need to go and find the Message-Id of your previous cover letter. +You will also need to go and find the Message-ID of your previous cover letter. You can either note it when you send the first series, from the output of `git send-email`, or you can look it up on the https://lore.kernel.org/git[mailing list]. Find your cover letter in the -archives, click on it, then click "permalink" or "raw" to reveal the Message-Id +archives, click on it, then click "permalink" or "raw" to reveal the Message-ID header. It should match: ---- -Message-Id: <foo.12345.author@example.com> +Message-ID: <foo.12345.author@example.com> ---- -Your Message-Id is `<foo.12345.author@example.com>`. This example will be used -below as well; make sure to replace it with the correct Message-Id for your -**previous cover letter** - that is, if you're sending v2, use the Message-Id -from v1; if you're sending v3, use the Message-Id from v2. +Your Message-ID is `<foo.12345.author@example.com>`. This example will be used +below as well; make sure to replace it with the correct Message-ID for your +**previous cover letter** - that is, if you're sending v2, use the Message-ID +from v1; if you're sending v3, use the Message-ID from v2. While you're looking at the email, you should also note who is CC'd, as it's common practice in the mailing list to keep all CCs on a thread. You can add @@ -1256,6 +1258,38 @@ index 88f126184c..38da593a60 100644 [[now-what]] == My Patch Got Emailed - Now What? +Please give reviewers enough time to process your initial patch before +sending an updated version. That is, resist the temptation to send a new +version immediately, because others may have already started reviewing +your initial version. + +While waiting for review comments, you may find mistakes in your initial +patch, or perhaps realize a different and better way to achieve the goal +of the patch. In this case you may communicate your findings to other +reviewers as follows: + + - If the mistakes you found are minor, send a reply to your patch as if + you were a reviewer and mention that you will fix them in an + updated version. + + - On the other hand, if you think you want to change the course so + drastically that reviews on the initial patch would be a waste of + time (for everyone involved), retract the patch immediately with + a reply like "I am working on a much better approach, so please + ignore this patch and wait for the updated version." + +Now, the above is a good practice if you sent your initial patch +prematurely without polish. But a better approach of course is to avoid +sending your patch prematurely in the first place. + +Please be considerate of the time needed by reviewers to examine each +new version of your patch. Rather than seeing the initial version right +now (followed by several "oops, I like this version better than the +previous one" patches over 2 days), reviewers would strongly prefer if a +single polished version came 2 days later instead, and that version with +fewer mistakes were the only one they would need to review. + + [[reviewing]] === Responding to Reviews diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index 8d9e855..dec8afe 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -41,6 +41,7 @@ Open up a new file `builtin/walken.c` and set up the command handler: */ #include "builtin.h" +#include "trace.h" int cmd_walken(int argc, const char **argv, const char *prefix) { @@ -49,12 +50,13 @@ int cmd_walken(int argc, const char **argv, const char *prefix) } ---- -NOTE: `trace_printf()` differs from `printf()` in that it can be turned on or -off at runtime. For the purposes of this tutorial, we will write `walken` as -though it is intended for use as a "plumbing" command: that is, a command which -is used primarily in scripts, rather than interactively by humans (a "porcelain" -command). So we will send our debug output to `trace_printf()` instead. When -running, enable trace output by setting the environment variable `GIT_TRACE`. +NOTE: `trace_printf()`, defined in `trace.h`, differs from `printf()` in +that it can be turned on or off at runtime. For the purposes of this +tutorial, we will write `walken` as though it is intended for use as +a "plumbing" command: that is, a command which is used primarily in +scripts, rather than interactively by humans (a "porcelain" command). +So we will send our debug output to `trace_printf()` instead. +When running, enable trace output by setting the environment variable `GIT_TRACE`. Add usage text and `-h` handling, like all subcommands should consistently do (our test suite will notice and complain if you fail to do so). @@ -124,7 +126,7 @@ parameters provided by the user over the CLI. `nr` represents the number of `rev_cmdline_entry` present in the array. -`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is +`alloc` is used by the `ALLOC_GROW` macro. Check `alloc.h` - this variable is used to track the allocated size of the list. Per entry, we find: @@ -208,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); } ---- @@ -341,6 +344,10 @@ the walk loop below the `prepare_revision_walk()` call within your `walken_commit_walk()`: ---- +#include "pretty.h" + +... + static void walken_commit_walk(struct rev_info *rev) { struct commit *commit; @@ -383,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); } ---- @@ -517,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 @@ -534,7 +542,7 @@ the arguments to `traverse_commit_list()`. - `void *show_data`: A context buffer which is passed in turn to `show_commit` and `show_object`. -In addition, `traverse_commit_list_filtered()` has an additional paramter: +In addition, `traverse_commit_list_filtered()` has an additional parameter: - `struct oidset *omitted`: A linked-list of object IDs which the provided filter caused to be omitted. @@ -726,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); @@ -746,14 +754,20 @@ 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: ---- +#include "oidset.h" + +... + static void walken_object_walk( ... @@ -766,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: ---- ... @@ -805,6 +820,10 @@ just walks of commits. First, we'll make our handlers chattier - modify go: ---- +#include "hex.h" + +... + static void walken_show_commit(struct commit *cmt, void *buf) { trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid)); @@ -829,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 @@ -857,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.30.5.txt b/Documentation/RelNotes/2.30.5.txt new file mode 100644 index 0000000..5191cab --- /dev/null +++ b/Documentation/RelNotes/2.30.5.txt @@ -0,0 +1,12 @@ +Git v2.30.5 Release Notes +========================= + +This release contains minor fix-ups for the changes that went into +Git 2.30.3 and 2.30.4, addressing CVE-2022-29187. + + * The safety check that verifies a safe ownership of the Git + worktree is now extended to also cover the ownership of the Git + directory (and the `.git` file, if there is any). + +Carlo Marcelo Arenas Belón (1): + setup: tighten ownership checks post CVE-2022-24765 diff --git a/Documentation/RelNotes/2.30.6.txt b/Documentation/RelNotes/2.30.6.txt new file mode 100644 index 0000000..d649071 --- /dev/null +++ b/Documentation/RelNotes/2.30.6.txt @@ -0,0 +1,60 @@ +Git v2.30.6 Release Notes +========================= + +This release addresses the security issues CVE-2022-39253 and +CVE-2022-39260. + +Fixes since v2.30.5 +------------------- + + * CVE-2022-39253: + When relying on the `--local` clone optimization, Git dereferences + symbolic links in the source repository before creating hardlinks + (or copies) of the dereferenced link in the destination repository. + This can lead to surprising behavior where arbitrary files are + present in a repository's `$GIT_DIR` when cloning from a malicious + repository. + + Git will no longer dereference symbolic links via the `--local` + clone mechanism, and will instead refuse to clone repositories that + have symbolic links present in the `$GIT_DIR/objects` directory. + + Additionally, the value of `protocol.file.allow` is changed to be + "user" by default. + + * CVE-2022-39260: + An overly-long command string given to `git shell` can result in + overflow in `split_cmdline()`, leading to arbitrary heap writes and + remote code execution when `git shell` is exposed and the directory + `$HOME/git-shell-commands` exists. + + `git shell` is taught to refuse interactive commands that are + longer than 4MiB in size. `split_cmdline()` is hardened to reject + inputs larger than 2GiB. + +Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis. The +fix was authored by Taylor Blau, with help from Johannes Schindelin. + +Credit for finding CVE-2022-39260 goes to Kevin Backhouse of GitHub. +The fix was authored by Kevin Backhouse, Jeff King, and Taylor Blau. + + +Jeff King (2): + shell: add basic tests + shell: limit size of interactive commands + +Kevin Backhouse (1): + alias.c: reject too-long cmdline strings in split_cmdline() + +Taylor Blau (11): + builtin/clone.c: disallow `--local` clones with symlinks + t/lib-submodule-update.sh: allow local submodules + t/t1NNN: allow local submodules + t/2NNNN: allow local submodules + t/t3NNN: allow local submodules + t/t4NNN: allow local submodules + t/t5NNN: allow local submodules + t/t6NNN: allow local submodules + t/t7NNN: allow local submodules + t/t9NNN: allow local submodules + transport: make `protocol.file.allow` be "user" by default diff --git a/Documentation/RelNotes/2.30.7.txt b/Documentation/RelNotes/2.30.7.txt new file mode 100644 index 0000000..285beed --- /dev/null +++ b/Documentation/RelNotes/2.30.7.txt @@ -0,0 +1,86 @@ +Git v2.30.7 Release Notes +========================= + +This release addresses the security issues CVE-2022-41903 and +CVE-2022-23521. + + +Fixes since v2.30.6 +------------------- + + * CVE-2022-41903: + + git log has the ability to display commits using an arbitrary + format with its --format specifiers. This functionality is also + exposed to git archive via the export-subst gitattribute. + + When processing the padding operators (e.g., %<(, %<|(, %>(, + %>>(, or %><( ), an integer overflow can occur in + pretty.c::format_and_pad_commit() where a size_t is improperly + stored as an int, and then added as an offset to a subsequent + memcpy() call. + + This overflow can be triggered directly by a user running a + command which invokes the commit formatting machinery (e.g., git + log --format=...). It may also be triggered indirectly through + git archive via the export-subst mechanism, which expands format + specifiers inside of files within the repository during a git + archive. + + This integer overflow can result in arbitrary heap writes, which + may result in remote code execution. + +* CVE-2022-23521: + + gitattributes are a mechanism to allow defining attributes for + paths. These attributes can be defined by adding a `.gitattributes` + file to the repository, which contains a set of file patterns and + the attributes that should be set for paths matching this pattern. + + When parsing gitattributes, multiple integer overflows can occur + when there is a huge number of path patterns, a huge number of + attributes for a single pattern, or when the declared attribute + names are huge. + + These overflows can be triggered via a crafted `.gitattributes` file + that may be part of the commit history. Git silently splits lines + longer than 2KB when parsing gitattributes from a file, but not when + parsing them from the index. Consequentially, the failure mode + depends on whether the file exists in the working tree, the index or + both. + + This integer overflow can result in arbitrary heap reads and writes, + which may result in remote code execution. + +Credit for finding CVE-2022-41903 goes to Joern Schneeweisz of GitLab. +An initial fix was authored by Markus Vervier of X41 D-Sec. Credit for +finding CVE-2022-23521 goes to Markus Vervier and Eric Sesterhenn of X41 +D-Sec. This work was sponsored by OSTIF. + +The proposed fixes have been polished and extended to cover additional +findings by Patrick Steinhardt of GitLab, with help from others on the +Git security mailing list. + +Patrick Steinhardt (21): + attr: fix overflow when upserting attribute with overly long name + attr: fix out-of-bounds read with huge attribute names + attr: fix integer overflow when parsing huge attribute names + attr: fix out-of-bounds write when parsing huge number of attributes + attr: fix out-of-bounds read with unreasonable amount of patterns + attr: fix integer overflow with more than INT_MAX macros + attr: harden allocation against integer overflows + attr: fix silently splitting up lines longer than 2048 bytes + attr: ignore attribute lines exceeding 2048 bytes + attr: ignore overly large gitattributes files + pretty: fix out-of-bounds write caused by integer overflow + pretty: fix out-of-bounds read when left-flushing with stealing + pretty: fix out-of-bounds read when parsing invalid padding format + pretty: fix adding linefeed when placeholder is not expanded + pretty: fix integer overflow in wrapping format + utf8: fix truncated string lengths in `utf8_strnwidth()` + utf8: fix returning negative string width + utf8: fix overflow when returning string width + utf8: fix checking for glyph width in `strbuf_utf8_replace()` + utf8: refactor `strbuf_utf8_replace` to not rely on preallocated buffer + pretty: restrict input lengths for padding and wrapping formats + diff --git a/Documentation/RelNotes/2.30.8.txt b/Documentation/RelNotes/2.30.8.txt new file mode 100644 index 0000000..5ed3efb --- /dev/null +++ b/Documentation/RelNotes/2.30.8.txt @@ -0,0 +1,51 @@ +Git v2.30.8 Release Notes +========================= + +This release addresses the security issues CVE-2023-22490 and +CVE-2023-23946. + + +Fixes since v2.30.7 +------------------- + + * CVE-2023-22490: + + Using a specially-crafted repository, Git can be tricked into using + its local clone optimization even when using a non-local transport. + Though Git will abort local clones whose source $GIT_DIR/objects + directory contains symbolic links (c.f., CVE-2022-39253), the objects + directory itself may still be a symbolic link. + + These two may be combined to include arbitrary files based on known + paths on the victim's filesystem within the malicious repository's + working copy, allowing for data exfiltration in a similar manner as + CVE-2022-39253. + + * CVE-2023-23946: + + By feeding a crafted input to "git apply", a path outside the + working tree can be overwritten as the user who is running "git + apply". + + * A mismatched type in `attr.c::read_attr_from_index()` which could + cause Git to errantly reject attributes on Windows and 32-bit Linux + has been corrected. + +Credit for finding CVE-2023-22490 goes to yvvdwf, and the fix was +developed by Taylor Blau, with additional help from others on the +Git security mailing list. + +Credit for finding CVE-2023-23946 goes to Joern Schneeweisz, and the +fix was developed by Patrick Steinhardt. + + +Johannes Schindelin (1): + attr: adjust a mismatched data type + +Patrick Steinhardt (1): + apply: fix writing behind newly created symbolic links + +Taylor Blau (3): + t5619: demonstrate clone_local() with ambiguous transport + clone: delay picking a transport until after get_repo_path() + dir-iterator: prevent top-level symlinks without FOLLOW_SYMLINKS diff --git a/Documentation/RelNotes/2.30.9.txt b/Documentation/RelNotes/2.30.9.txt new file mode 100644 index 0000000..708d626 --- /dev/null +++ b/Documentation/RelNotes/2.30.9.txt @@ -0,0 +1,43 @@ +Git v2.30.9 Release Notes +========================= + +This release addresses the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007. + + +Fixes since v2.30.8 +------------------- + + * CVE-2023-25652: + + By feeding specially crafted input to `git apply --reject`, a + path outside the working tree can be overwritten with partially + controlled contents (corresponding to the rejected hunk(s) from + the given patch). + + * CVE-2023-25815: + + When Git is compiled with runtime prefix support and runs without + translated messages, it still used the gettext machinery to + display messages, which subsequently potentially looked for + translated messages in unexpected places. This allowed for + malicious placement of crafted messages. + + * CVE-2023-29007: + + When renaming or deleting a section from a configuration file, + certain malicious configuration values may be misinterpreted as + the beginning of a new configuration section, leading to arbitrary + configuration injection. + +Credit for finding CVE-2023-25652 goes to Ry0taK, and the fix was +developed by Taylor Blau, Junio C Hamano and Johannes Schindelin, +with the help of Linus Torvalds. + +Credit for finding CVE-2023-25815 goes to Maxime Escourbiac and +Yassine BENGANA of Michelin, and the fix was developed by Johannes +Schindelin. + +Credit for finding CVE-2023-29007 goes to André Baptista and Vítor Pinho +of Ethiack, and the fix was developed by Taylor Blau, and Johannes +Schindelin, with help from Jeff King, and Patrick Steinhardt. diff --git a/Documentation/RelNotes/2.31.4.txt b/Documentation/RelNotes/2.31.4.txt new file mode 100644 index 0000000..97a91fd --- /dev/null +++ b/Documentation/RelNotes/2.31.4.txt @@ -0,0 +1,6 @@ +Git v2.31.4 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.5 to address +the security issue CVE-2022-29187; see the release notes for that +version for details. diff --git a/Documentation/RelNotes/2.31.5.txt b/Documentation/RelNotes/2.31.5.txt new file mode 100644 index 0000000..0d87e6e --- /dev/null +++ b/Documentation/RelNotes/2.31.5.txt @@ -0,0 +1,5 @@ +Git v2.31.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.31.6.txt b/Documentation/RelNotes/2.31.6.txt new file mode 100644 index 0000000..425a518 --- /dev/null +++ b/Documentation/RelNotes/2.31.6.txt @@ -0,0 +1,5 @@ +Git v2.31.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.31.7.txt b/Documentation/RelNotes/2.31.7.txt new file mode 100644 index 0000000..dd44d5b --- /dev/null +++ b/Documentation/RelNotes/2.31.7.txt @@ -0,0 +1,6 @@ +Git v2.31.7 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8 to +address the security issues CVE-2023-22490 and CVE-2023-23946; +see the release notes for that version for details. diff --git a/Documentation/RelNotes/2.31.8.txt b/Documentation/RelNotes/2.31.8.txt new file mode 100644 index 0000000..0aa3080 --- /dev/null +++ b/Documentation/RelNotes/2.31.8.txt @@ -0,0 +1,6 @@ +Git v2.31.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9 to address the +security issues CVE-2023-25652, CVE-2023-25815, and CVE-2023-29007; +see the release notes for that version for details. diff --git a/Documentation/RelNotes/2.32.3.txt b/Documentation/RelNotes/2.32.3.txt new file mode 100644 index 0000000..583fabe --- /dev/null +++ b/Documentation/RelNotes/2.32.3.txt @@ -0,0 +1,6 @@ +Git v2.32.3 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.5 and +v2.31.4 to address the security issue CVE-2022-29187; see the +release notes for these versions for details. diff --git a/Documentation/RelNotes/2.32.4.txt b/Documentation/RelNotes/2.32.4.txt new file mode 100644 index 0000000..76c67b2 --- /dev/null +++ b/Documentation/RelNotes/2.32.4.txt @@ -0,0 +1,5 @@ +Git v2.32.4 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.32.5.txt b/Documentation/RelNotes/2.32.5.txt new file mode 100644 index 0000000..a8cad1a --- /dev/null +++ b/Documentation/RelNotes/2.32.5.txt @@ -0,0 +1,8 @@ +Git v2.32.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. + +In addition, included are additional code for "git fsck" to check +for questionable .gitattributes files. diff --git a/Documentation/RelNotes/2.32.6.txt b/Documentation/RelNotes/2.32.6.txt new file mode 100644 index 0000000..fd65961 --- /dev/null +++ b/Documentation/RelNotes/2.32.6.txt @@ -0,0 +1,6 @@ +Git v2.32.6 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8 and v2.31.7 +to address the security issues CVE-2023-22490 and CVE-2023-23946; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.32.7.txt b/Documentation/RelNotes/2.32.7.txt new file mode 100644 index 0000000..7bb3538 --- /dev/null +++ b/Documentation/RelNotes/2.32.7.txt @@ -0,0 +1,7 @@ +Git v2.32.7 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9 and v2.31.8 to +address the security issues CVE-2023-25652, CVE-2023-25815, and +CVE-2023-29007; see the release notes for these versions for +details. diff --git a/Documentation/RelNotes/2.33.4.txt b/Documentation/RelNotes/2.33.4.txt new file mode 100644 index 0000000..a145cc2 --- /dev/null +++ b/Documentation/RelNotes/2.33.4.txt @@ -0,0 +1,6 @@ +Git v2.33.4 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.5, v2.31.4 +and v2.32.3 to address the security issue CVE-2022-29187; see +the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.33.5.txt b/Documentation/RelNotes/2.33.5.txt new file mode 100644 index 0000000..a636526 --- /dev/null +++ b/Documentation/RelNotes/2.33.5.txt @@ -0,0 +1,5 @@ +Git v2.33.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.33.6.txt b/Documentation/RelNotes/2.33.6.txt new file mode 100644 index 0000000..b63e4e6 --- /dev/null +++ b/Documentation/RelNotes/2.33.6.txt @@ -0,0 +1,5 @@ +Git v2.33.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.33.7.txt b/Documentation/RelNotes/2.33.7.txt new file mode 100644 index 0000000..078a837 --- /dev/null +++ b/Documentation/RelNotes/2.33.7.txt @@ -0,0 +1,7 @@ +Git v2.33.7 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7 +and v2.32.6 to address the security issues CVE-2023-22490 and +CVE-2023-23946; see the release notes for these versions for +details. diff --git a/Documentation/RelNotes/2.33.8.txt b/Documentation/RelNotes/2.33.8.txt new file mode 100644 index 0000000..d8cf4c7 --- /dev/null +++ b/Documentation/RelNotes/2.33.8.txt @@ -0,0 +1,7 @@ +Git v2.33.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8 and +v2.32.7 to address the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007; see the release notes for these +versions for details. diff --git a/Documentation/RelNotes/2.34.4.txt b/Documentation/RelNotes/2.34.4.txt new file mode 100644 index 0000000..2a6b223 --- /dev/null +++ b/Documentation/RelNotes/2.34.4.txt @@ -0,0 +1,6 @@ +Git v2.34.4 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.5, v2.31.4, +v2.32.3 and v2.33.4 to address the security issue CVE-2022-29187; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.34.5.txt b/Documentation/RelNotes/2.34.5.txt new file mode 100644 index 0000000..0e89992 --- /dev/null +++ b/Documentation/RelNotes/2.34.5.txt @@ -0,0 +1,5 @@ +Git v2.34.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.34.6.txt b/Documentation/RelNotes/2.34.6.txt new file mode 100644 index 0000000..b32080d --- /dev/null +++ b/Documentation/RelNotes/2.34.6.txt @@ -0,0 +1,5 @@ +Git v2.34.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.34.7.txt b/Documentation/RelNotes/2.34.7.txt new file mode 100644 index 0000000..88898ad --- /dev/null +++ b/Documentation/RelNotes/2.34.7.txt @@ -0,0 +1,7 @@ +Git v2.34.7 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7, +v2.32.6 and v2.33.7 to address the security issues CVE-2023-22490 +and CVE-2023-23946; see the release notes for these versions +for details. diff --git a/Documentation/RelNotes/2.34.8.txt b/Documentation/RelNotes/2.34.8.txt new file mode 100644 index 0000000..2b5bd7d --- /dev/null +++ b/Documentation/RelNotes/2.34.8.txt @@ -0,0 +1,7 @@ +Git v2.34.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8, +v2.32.7 and v2.33.8 to address the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007; see the release notes for these +versions for details. diff --git a/Documentation/RelNotes/2.35.4.txt b/Documentation/RelNotes/2.35.4.txt new file mode 100644 index 0000000..47abd5a --- /dev/null +++ b/Documentation/RelNotes/2.35.4.txt @@ -0,0 +1,7 @@ +Git v2.35.4 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.5, +v2.31.4, v2.32.3, v2.33.4 and v2.34.4 to address the security +issue CVE-2022-29187; see the release notes for these versions +for details. diff --git a/Documentation/RelNotes/2.35.5.txt b/Documentation/RelNotes/2.35.5.txt new file mode 100644 index 0000000..e19cc48 --- /dev/null +++ b/Documentation/RelNotes/2.35.5.txt @@ -0,0 +1,5 @@ +Git v2.35.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.35.6.txt b/Documentation/RelNotes/2.35.6.txt new file mode 100644 index 0000000..e7ca57b --- /dev/null +++ b/Documentation/RelNotes/2.35.6.txt @@ -0,0 +1,5 @@ +Git v2.35.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.35.7.txt b/Documentation/RelNotes/2.35.7.txt new file mode 100644 index 0000000..42baabf --- /dev/null +++ b/Documentation/RelNotes/2.35.7.txt @@ -0,0 +1,7 @@ +Git v2.35.7 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7, +v2.32.6, v2.33.7 and v2.34.7 to address the security issues +CVE-2023-22490 and CVE-2023-23946; see the release notes for +these versions for details. diff --git a/Documentation/RelNotes/2.35.8.txt b/Documentation/RelNotes/2.35.8.txt new file mode 100644 index 0000000..3c9c094 --- /dev/null +++ b/Documentation/RelNotes/2.35.8.txt @@ -0,0 +1,7 @@ +Git v2.35.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8, +v2.32.7, v2.33.8 and v2.34.8 to address the security issues +CVE-2023-25652, CVE-2023-25815, and CVE-2023-29007; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.36.2.txt b/Documentation/RelNotes/2.36.2.txt index ba5d5ac..958f5b4 100644 --- a/Documentation/RelNotes/2.36.2.txt +++ b/Documentation/RelNotes/2.36.2.txt @@ -1,10 +1,16 @@ Git v2.36.2 Release Notes ========================= -This maintenance release is primarily to merge down updates to the -build and CI procedures from the 'master' front, in order to ensure -that we can cut healthy maintenance releases in the future. It also -contains a handful of small and trivially-correct bugfixes. +This release merges up the fixes that appear in v2.30.5, v2.31.4, +v2.32.3, v2.33.4, v2.34.4 and v2.35.4 to address the security +issue CVE-2022-29187; see the release notes for these versions +for details. + +Apart from that, this maintenance release is primarily to merge down +updates to the build and CI procedures from the 'master' front, in +order to ensure that we can cut healthy maintenance releases in the +future. It also contains a handful of small and trivially-correct +bugfixes. Fixes since v2.36.1 ------------------- diff --git a/Documentation/RelNotes/2.36.3.txt b/Documentation/RelNotes/2.36.3.txt new file mode 100644 index 0000000..56db77b --- /dev/null +++ b/Documentation/RelNotes/2.36.3.txt @@ -0,0 +1,5 @@ +Git v2.36.3 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.36.4.txt b/Documentation/RelNotes/2.36.4.txt new file mode 100644 index 0000000..58fb93a --- /dev/null +++ b/Documentation/RelNotes/2.36.4.txt @@ -0,0 +1,5 @@ +Git v2.36.4 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.36.5.txt b/Documentation/RelNotes/2.36.5.txt new file mode 100644 index 0000000..8a098c7 --- /dev/null +++ b/Documentation/RelNotes/2.36.5.txt @@ -0,0 +1,7 @@ +Git v2.36.5 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7, +v2.32.6, v2.33.7, v2.34.7 and v2.35.7 to address the security +issues CVE-2023-22490 and CVE-2023-23946; see the release notes +for these versions for details. diff --git a/Documentation/RelNotes/2.36.6.txt b/Documentation/RelNotes/2.36.6.txt new file mode 100644 index 0000000..e1edebc --- /dev/null +++ b/Documentation/RelNotes/2.36.6.txt @@ -0,0 +1,7 @@ +Git v2.36.6 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8 and v2.35.8 to address the security issues +CVE-2023-25652, CVS-2023-25815, and CVE-2023-29007; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.37.1.txt b/Documentation/RelNotes/2.37.1.txt new file mode 100644 index 0000000..8460932 --- /dev/null +++ b/Documentation/RelNotes/2.37.1.txt @@ -0,0 +1,17 @@ +Git 2.37.1 Release Notes +======================== + +This release merges up the fixes that appear in v2.30.5, v2.31.4, +v2.32.3, v2.33.4, v2.34.4, v2.35.4, and v2.36.2 to address the +security issue CVE-2022-29187; see the release notes for these +versions for details. + +Fixes since Git 2.37 +-------------------- + + * Rewrite of "git add -i" in C that appeared in Git 2.25 didn't + correctly record a removed file to the index, which is an old + regression but has become widely known because the C version has + become the default in the latest release. + + * Fix for CVS-2022-29187. diff --git a/Documentation/RelNotes/2.37.2.txt b/Documentation/RelNotes/2.37.2.txt new file mode 100644 index 0000000..d82b29e --- /dev/null +++ b/Documentation/RelNotes/2.37.2.txt @@ -0,0 +1,88 @@ +Git 2.37.2 Release Notes +======================== + +This primarily is to backport various fixes accumulated on the 'master' +front since 2.37.1. + +Fixes since v2.37.1 +------------------- + + * "git shortlog -n" relied on the underlying qsort() to be stable, + which shouldn't have. Fixed. + + * Variable quoting fix in the vimdiff driver of "git mergetool". + + * An earlier attempt to plug leaks placed a clean-up label to jump to + at a bogus place, which as been corrected. + + * Fixes a long-standing corner case bug around directory renames in + the merge-ort strategy. + + * Recent update to vimdiff layout code has been made more robust + against different end-user vim settings. + + * In a non-bare repository, the behavior of Git when the + core.worktree configuration variable points at a directory that has + a repository as its subdirectory, regressed in Git 2.27 days. + + * References to commands-to-be-typed-literally in "git rebase" + documentation mark-up have been corrected. + + * Give _() markings to fatal/warning/usage: labels that are shown in + front of these messages. + + * "git mktree --missing" lazily fetched objects that are missing from + the local object store, which was totally unnecessary for the purpose + of creating the tree object(s) from its input. + + * Fixes for tests when the source directory has unusual characters in + its path, e.g. whitespaces, double-quotes, etc. + + * Adjust technical/bitmap-format to be formatted by AsciiDoc, and + add some missing information to the documentation. + + * Certain diff options are currently ignored when combined-diff is + shown; mark them as incompatible with the feature. + + * "git clone" from a repository with some ref whose HEAD is unborn + did not set the HEAD in the resulting repository correctly, which + has been corrected. + + * mkstemp() emulation on Windows has been improved. + + * Add missing documentation for "include" and "includeIf" features in + "git config" file format, which incidentally teaches the command + line completion to include them in its offerings. + + * Avoid "white/black-list" in documentation and code comments. + + * Workaround for a compiler warning against use of die() in + osx-keychain (in contrib/). + + * Workaround for a false positive compiler warning. + + * The resolve-undo information in the index was not protected against + GC, which has been corrected. + + * A corner case bug where lazily fetching objects from a promisor + remote resulted in infinite recursion has been corrected. + + * "git p4" working on UTF-16 files on Windows did not implement + CRLF-to-LF conversion correctly, which has been corrected. + + * "git p4" did not handle non-ASCII client name well, which has been + corrected. + + * "rerere-train" script (in contrib/) used to honor commit.gpgSign + while recreating the throw-away merges. + + * "git checkout" miscounted the paths it updated, which has been + corrected. + + * Fix for a bug that makes write-tree to fail to write out a + non-existent index as a tree, introduced in 2.37. + + * There was a bug in the codepath to upgrade generation information + in commit-graph from v1 to v2 format, which has been corrected. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.37.3.txt b/Documentation/RelNotes/2.37.3.txt new file mode 100644 index 0000000..d66689e --- /dev/null +++ b/Documentation/RelNotes/2.37.3.txt @@ -0,0 +1,46 @@ +Git 2.37.3 Release Notes +======================== + +This primarily is to backport various fixes accumulated on the 'master' +front since 2.37.2. + +Fixes since v2.37.2 +------------------- + + * The build procedure for Windows that uses CMake has been updated to + pick up the shell interpreter from local installation location. + + * Conditionally allow building Python interpreter on Windows + + * Fix to lstat() emulation on Windows. + + * Older gcc with -Wall complains about the universal zero initializer + "struct s = { 0 };" idiom, which makes developers' lives + inconvenient (as -Werror is enabled by DEVELOPER=YesPlease). The + build procedure has been tweaked to help these compilers. + + * Plug memory leaks in the failure code path in the "merge-ort" merge + strategy backend. + + * Avoid repeatedly running getconf to ask libc version in the test + suite, and instead just as it once per script. + + * Platform-specific code that determines if a directory is OK to use + as a repository has been taught to report more details, especially + on Windows. + + * "vimdiff3" regression has been corrected. + + * "git fsck" reads mode from tree objects but canonicalizes the mode + before passing it to the logic to check object sanity, which has + hid broken tree objects from the checking logic. This has been + corrected, but to help exiting projects with broken tree objects + that they cannot fix retroactively, the severity of anomalies this + code detects has been demoted to "info" for now. + + * Fixes to sparse index compatibility work for "reset" and "checkout" + commands. + + * Documentation for "git add --renormalize" has been improved. + +Also contains other minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.37.4.txt b/Documentation/RelNotes/2.37.4.txt new file mode 100644 index 0000000..e42a5c1 --- /dev/null +++ b/Documentation/RelNotes/2.37.4.txt @@ -0,0 +1,65 @@ +Git 2.37.4 Release Notes +======================== + +This primarily is to backport various fixes accumulated on the 'master' +front since 2.37.3, and also includes the same security fixes as in +v2.30.6. + +Fixes since v2.37.3 +------------------- + + * CVE-2022-39253: + When relying on the `--local` clone optimization, Git dereferences + symbolic links in the source repository before creating hardlinks + (or copies) of the dereferenced link in the destination repository. + This can lead to surprising behavior where arbitrary files are + present in a repository's `$GIT_DIR` when cloning from a malicious + repository. + + Git will no longer dereference symbolic links via the `--local` + clone mechanism, and will instead refuse to clone repositories that + have symbolic links present in the `$GIT_DIR/objects` directory. + + Additionally, the value of `protocol.file.allow` is changed to be + "user" by default. + + Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis. + The fix was authored by Taylor Blau, with help from Johannes + Schindelin. + + * CVE-2022-39260: + An overly-long command string given to `git shell` can result in + overflow in `split_cmdline()`, leading to arbitrary heap writes and + remote code execution when `git shell` is exposed and the directory + `$HOME/git-shell-commands` exists. + + `git shell` is taught to refuse interactive commands that are + longer than 4MiB in size. `split_cmdline()` is hardened to reject + inputs larger than 2GiB. + + Credit for finding CVE-2022-39260 goes to Kevin Backhouse of + GitHub. The fix was authored by Kevin Backhouse, Jeff King, and + Taylor Blau. + + * An earlier optimization discarded a tree-object buffer that is + still in use, which has been corrected. + + * Fix deadlocks between main Git process and subprocess spawned via + the pipe_command() API, that can kill "git add -p" that was + reimplemented in C recently. + + * xcalloc(), imitating calloc(), takes "number of elements of the + array", and "size of a single element", in this order. A call that + does not follow this ordering has been corrected. + + * The preload-index codepath made copies of pathspec to give to + multiple threads, which were left leaked. + + * Update the version of Ubuntu used for GitHub Actions CI from 18.04 + to 22.04. + + * The auto-stashed local changes created by "git merge --autostash" + was mixed into a conflicted state left in the working tree, which + has been corrected. + +Also contains other minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.37.5.txt b/Documentation/RelNotes/2.37.5.txt new file mode 100644 index 0000000..faa1447 --- /dev/null +++ b/Documentation/RelNotes/2.37.5.txt @@ -0,0 +1,5 @@ +Git v2.37.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.37.6.txt b/Documentation/RelNotes/2.37.6.txt new file mode 100644 index 0000000..51dc149 --- /dev/null +++ b/Documentation/RelNotes/2.37.6.txt @@ -0,0 +1,7 @@ +Git v2.37.6 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7, +v2.32.6, v2.33.7, v2.34.7, v2.35.7 and v2.36.5 to address the +security issues CVE-2023-22490 and CVE-2023-23946; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.37.7.txt b/Documentation/RelNotes/2.37.7.txt new file mode 100644 index 0000000..4b8165f --- /dev/null +++ b/Documentation/RelNotes/2.37.7.txt @@ -0,0 +1,7 @@ +Git v2.37.7 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8 and v2.36.6 to address the +security issues CVE-2023-25652, CVE-2023-25815, and CVE-2023-29007; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.38.0.txt b/Documentation/RelNotes/2.38.0.txt new file mode 100644 index 0000000..870581f --- /dev/null +++ b/Documentation/RelNotes/2.38.0.txt @@ -0,0 +1,404 @@ +Git v2.38 Release Notes +======================= + +UI, Workflows & Features + + * "git remote show [-n] frotz" now pays attention to negative + pathspec. + + * "git push" sometimes performs poorly when reachability bitmaps are + used, even in a repository where other operations are helped by + bitmaps. The push.useBitmaps configuration variable is introduced + to allow disabling use of reachability bitmaps only for "git push". + + * "git grep -m<max-hits>" is a way to limit the hits shown per file. + + * "git merge-tree" learned a new mode where it takes two commits and + computes a tree that would result in the merge commit, if the + histories leading to these two commits were to be merged. + + * "git mv A B" in a sparsely populated working tree can be asked to + move a path between directories that are "in cone" (i.e. expected + to be materialized in the working tree) and "out of cone" + (i.e. expected to be hidden). The handling of such cases has been + improved. + + * Earlier, HTTP transport clients learned to tell the server side + what locale they are in by sending Accept-Language HTTP header, but + this was done only for some requests but not others. + + * Introduce a safe.barerepository configuration variable that + allows users to forbid discovery of bare repositories. + + * Various messages that come from the pack-bitmap codepaths have been + tweaked. + + * "git rebase -i" learns to update branches whose tip appear in the + rebased range with "--update-refs" option. + + * "git ls-files" learns the "--format" option to tweak its output. + + * "git cat-file" learned an option to use the mailmap when showing + commit and tag objects. + + * When "git merge" finds that it cannot perform a merge, it should + restore the working tree to the state before the command was + initiated, but in some corner cases it didn't. + + * Operating modes like "--batch" of "git cat-file" command learned to + take NUL-terminated input, instead of one-item-per-line. + + * "git rm" has become more aware of the sparse-index feature. + + * "git rev-list --disk-usage" learned to take an optional value + "human" to show the reported value in human-readable format, like + "3.40MiB". + + * The "diagnose" feature to create a zip archive for diagnostic + material has been lifted from "scalar" and made into a feature of + "git bugreport". + + * The namespaces used by "log --decorate" from "refs/" hierarchy by + default has been tightened. + + * "git rev-list --ancestry-path=C A..B" is a natural extension of + "git rev-list A..B"; instead of choosing a subset of A..B to those + that have ancestry relationship with A, it lets a subset with + ancestry relationship with C. + + * "scalar" now enables built-in fsmonitor on enlisted repositories, + when able. + + * The bash prompt (in contrib/) learned to optionally indicate when + the index is unmerged. + + * "git clone" command learned the "--bundle-uri" option to coordinate + with hosting sites the use of pre-prepared bundle files. + + * "git range-diff" learned to honor pathspec argument if given. + + * "git format-patch --from=<ident>" can be told to add an in-body + "From:" line even for commits that are authored by the given + <ident> with "--force-in-body-from" option. + + * The built-in fsmonitor refuses to work on a network mounted + repositories; a configuration knob for users to override this has + been introduced. + + * The "scalar" addition from Microsoft is now part of the core Git + installation. + + +Performance, Internal Implementation, Development Support etc. + + * Collection of what is referenced by objects in promisor packs have + been optimized to inspect these objects in the in-pack order. + + * Introduce a helper to see if a branch is already being worked on + (hence should not be newly checked out in a working tree), which + performs much better than the existing find_shared_symref() to + replace many uses of the latter. + + * Teach "git archive" to (optionally and then by default) avoid + spawning an external "gzip" process when creating ".tar.gz" (and + ".tgz") archives. + + * Allow large objects read from a packstream to be streamed into a + loose object file straight, without having to keep it in-core as a + whole. + + * Further preparation to turn git-submodule.sh into a builtin + continues. + + * Apply Coccinelle rule to turn raw memmove() into MOVE_ARRAY() cpp + macro, which would improve maintainability and readability. + + * Teach "make all" to build gitweb as well. + + * Tweak tests so that they still work when the "git init" template + did not create .git/info directory. + + * Add Coccinelle rules to detect the pattern of initializing and then + finalizing a structure without using it in between at all, which + happens after code restructuring and the compilers fail to + recognize as an unused variable. + + * The code to convert between GPG trust level strings and internal + constants we use to represent them have been cleaned up. + + * Support for libnettle as SHA256 implementation has been added. + + * The way "git multi-pack" uses parse-options API has been improved. + + * A Coccinelle rule (in contrib/) to encourage use of COPY_ARRAY + macro has been improved. + + * API tweak to make it easier to run fuzz testing on commit-graph parser. + + * Omit fsync-related trace2 entries when their values are all zero. + + * The codepath to write multi-pack index has been taught to release a + large chunk of memory that holds an array of objects in the packs, + as soon as it is done with the array, to reduce memory consumption. + + * Add a level of redirection to array allocation API in xdiff part, + to make it easier to share with the libgit2 project. + + * "git fetch" client logs the partial clone filter used in the trace2 + output. + + * The "bundle URI" design gets documented. + + * The common ancestor negotiation exchange during a "git fetch" + session now leaves trace log. + + * Test portability improvements. + (merge 4d1d843be7 mt/rot13-in-c later to maint). + + * The "subcommand" mode is introduced to parse-options API and update + the command line parser of Git commands with subcommands. + + * The pack bitmap file gained a bitmap-lookup table to speed up + locating the necessary bitmap for a given commit. + + * The assembly version of SHA-1 implementation for PPC has been + removed. + + * The server side that responds to "git fetch" and "git clone" + request has been optimized by allowing it to send objects in its + object store without recomputing and validating the object names. + + * Annotate function parameters that are not used (but cannot be + removed for structural reasons), to prepare us to later compile + with -Wunused warning turned on. + + * Share the text used to explain configuration variables used by "git + <subcmd>" in "git help <subcmd>" with the text from "git help config". + + * "git mv A B" in a sparsely populated working tree can be asked to + move a path from a directory that is "in cone" to another directory + that is "out of cone". Handling of such a case has been improved. + + * The chainlint script for our tests has been revamped. + + +Fixes since v2.37 +----------------- + + * Rewrite of "git add -i" in C that appeared in Git 2.25 didn't + correctly record a removed file to the index, which was fixed. + + * Certain diff options are currently ignored when combined-diff is + shown; mark them as incompatible with the feature. + + * Adjust technical/bitmap-format to be formatted by AsciiDoc, and + add some missing information to the documentation. + + * Fixes for tests when the source directory has unusual characters in + its path, e.g. whitespaces, double-quotes, etc. + + * "git mktree --missing" lazily fetched objects that are missing from + the local object store, which was totally unnecessary for the purpose + of creating the tree object(s) from its input. + + * Give _() markings to fatal/warning/usage: labels that are shown in + front of these messages. + + * References to commands-to-be-typed-literally in "git rebase" + documentation mark-up have been corrected. + + * In a non-bare repository, the behavior of Git when the + core.worktree configuration variable points at a directory that has + a repository as its subdirectory, regressed in Git 2.27 days. + + * Recent update to vimdiff layout code has been made more robust + against different end-user vim settings. + + * Plug various memory leaks, both in the main code and in test-tool + commands. + + * Fixes a long-standing corner case bug around directory renames in + the merge-ort strategy. + + * The resolve-undo information in the index was not protected against + GC, which has been corrected. + + * A corner case bug where lazily fetching objects from a promisor + remote resulted in infinite recursion has been corrected. + + * "git clone" from a repository with some ref whose HEAD is unborn + did not set the HEAD in the resulting repository correctly, which + has been corrected. + + * An earlier attempt to plug leaks placed a clean-up label to jump to + at a bogus place, which as been corrected. + + * Variable quoting fix in the vimdiff driver of "git mergetool" + + * "git shortlog -n" relied on the underlying qsort() to be stable, + which shouldn't have. Fixed. + + * A fix for a regression in test framework. + + * mkstemp() emulation on Windows has been improved. + + * Add missing documentation for "include" and "includeIf" features in + "git config" file format, which incidentally teaches the command + line completion to include them in its offerings. + + * Avoid "white/black-list" in documentation and code comments. + + * Workaround for a compiler warning against use of die() in + osx-keychain (in contrib/). + + * Workaround for a false positive compiler warning. + + * "git p4" working on UTF-16 files on Windows did not implement + CRLF-to-LF conversion correctly, which has been corrected. + + * "git p4" did not handle non-ASCII client name well, which has been + corrected. + + * "rerere-train" script (in contrib/) used to honor commit.gpgSign + while recreating the throw-away merges. + + * "git checkout" miscounted the paths it updated, which has been + corrected. + + * Fix for a bug that makes write-tree to fail to write out a + non-existent index as a tree, introduced in 2.37. + + * There was a bug in the codepath to upgrade generation information + in commit-graph from v1 to v2 format, which has been corrected. + + * Gitweb had legacy URL shortener that is specific to the way + projects hosted on kernel.org used to (but no longer) work, which + has been removed. + + * Fix build procedure for Windows that uses CMake so that it can pick + up the shell interpreter from local installation location. + + * Conditionally allow building Python interpreter on Windows + + * Fix to lstat() emulation on Windows. + + * Older gcc with -Wall complains about the universal zero initializer + "struct s = { 0 };" idiom, which makes developers' lives + inconvenient (as -Werror is enabled by DEVELOPER=YesPlease). The + build procedure has been tweaked to help these compilers. + + * Plug memory leaks in the failure code path in the "merge-ort" merge + strategy backend. + + * "git symbolic-ref symref non..sen..se" is now diagnosed as an error. + + * A follow-up fix to a fix for a regression in 2.36 around hooks. + + * Avoid repeatedly running getconf to ask libc version in the test + suite, and instead just as it once per script. + + * Platform-specific code that determines if a directory is OK to use + as a repository has been taught to report more details, especially + on Windows. + + * "vimdiff3" regression fix. + + * "git fsck" reads mode from tree objects but canonicalizes the mode + before passing it to the logic to check object sanity, which has + hid broken tree objects from the checking logic. This has been + corrected, but to help existing projects with broken tree objects + that they cannot fix retroactively, the severity of anomalies this + code detects has been demoted to "info" for now. + + * Fixes to sparse index compatibility work for "reset" and "checkout" + commands. + + * An earlier optimization discarded a tree-object buffer that is + still in use, which has been corrected. + + * Fix deadlocks between main Git process and subprocess spawned via + the pipe_command() API, that can kill "git add -p" that was + reimplemented in C recently. + + * The sequencer machinery translated messages left in the reflog by + mistake, which has been corrected. + + * xcalloc(), imitating calloc(), takes "number of elements of the + array", and "size of a single element", in this order. A call that + does not follow this ordering has been corrected. + + * The preload-index codepath made copies of pathspec to give to + multiple threads, which were left leaked. + + * Update the version of Ubuntu used for GitHub Actions CI from 18.04 + to 22.04. + + * The auto-stashed local changes created by "git merge --autostash" + was mixed into a conflicted state left in the working tree, which + has been corrected. + + * Multi-pack index got corrupted when preferred pack changed from one + pack to another in a certain way, which has been corrected. + (merge 99e4d084ff tb/midx-with-changing-preferred-pack-fix later to maint). + + * The clean-up of temporary files created via mks_tempfile_dt() was + racy and attempted to unlink() the leading directory when signals + are involved, which has been corrected. + (merge babe2e0559 rs/tempfile-cleanup-race-fix later to maint). + + * FreeBSD portability fix for "git maintenance" that spawns "crontab" + to schedule tasks. + (merge ee69e7884e bc/gc-crontab-fix later to maint). + + * Those who use diff-so-fancy as the diff-filter noticed a regression + or two in the code that parses the diff output in the built-in + version of "add -p", which has been corrected. + (merge 0a101676e5 js/add-p-diff-parsing-fix later to maint). + + * Segfault fix-up to an earlier fix to the topic to teach "git reset" + and "git checkout" work better in a sparse checkout. + (merge 037f8ea6d9 vd/sparse-reset-checkout-fixes later to maint). + + * "git diff --no-index A B" managed its the pathnames of its two + input files rather haphazardly, sometimes leaking them. The + command line argument processing has been straightened out to clean + it up. + (merge 2b43dd0eb5 rs/diff-no-index-cleanup later to maint). + + * "git rev-list --verify-objects" ought to inspect the contents of + objects and notice corrupted ones, but it didn't when the commit + graph is in use, which has been corrected. + (merge b27ccae34b jk/rev-list-verify-objects-fix later to maint). + + * More fixes to "add -p" + (merge 64ec8efb83 js/builtin-add-p-portability-fix later to maint). + + * The parser in the script interface to parse-options in "git + rev-parse" has been updated to diagnose a bogus input correctly. + (merge f20b9c36d0 ow/rev-parse-parseopt-fix later to maint). + + * The code that manages list-object-filter structure, used in partial + clones, leaked the instances, which has been plugged. + (merge 66eede4a37 jk/plug-list-object-filter-leaks later to maint). + + * Fix another UI regression in the reimplemented "add -p". + (merge f6f0ee247f rs/add-p-worktree-mode-prompt-fix later to maint). + + * "git fetch" over protocol v2 sent an incorrect ref prefix request + to the server and made "git pull" with configured fetch refspec + that does not cover the remote branch to merge with fail, which has + been corrected. + (merge 49ca2fba39 jk/proto-v2-ref-prefix-fix later to maint). + + * A result from opendir() was leaking in the commit-graph expiration + codepath, which has been plugged. + (merge 12f1ae5324 ml/commit-graph-expire-dir-leak-fix later to maint). + + * Just like we have coding guidelines, we now have guidelines for + reviewers. + (merge e01b851923 vd/doc-reviewing-guidelines later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 77b9e85c0f vd/fix-perf-tests later to maint). + (merge 0682bc43f5 jk/test-crontab-fixes later to maint). + (merge b46dd1726c cc/doc-trailer-whitespace-rules later to maint). diff --git a/Documentation/RelNotes/2.38.1.txt b/Documentation/RelNotes/2.38.1.txt new file mode 100644 index 0000000..b2b5854 --- /dev/null +++ b/Documentation/RelNotes/2.38.1.txt @@ -0,0 +1,5 @@ +Git v2.38.1 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.38.2.txt b/Documentation/RelNotes/2.38.2.txt new file mode 100644 index 0000000..92acb62 --- /dev/null +++ b/Documentation/RelNotes/2.38.2.txt @@ -0,0 +1,67 @@ +Git 2.38.2 Release Notes +======================== + +This is to backport various fixes accumulated during the development +towards Git 2.39, the next feature release. + + +Fixes since v2.38.1 +------------------- + + * Update CodingGuidelines to clarify what features to use and avoid + in C99. + + * The codepath that reads from the index v4 had unaligned memory + accesses, which has been corrected. + + * "git remote rename" failed to rename a remote without fetch + refspec, which has been corrected. + + * "git clone" did not like to see the "--bare" and the "--origin" + options used together without a good reason. + + * Fix messages incorrectly marked for translation. + + * "git fsck" failed to release contents of tree objects already used + from the memory, which has been fixed. + + * "git rebase -i" can mistakenly attempt to apply a fixup to a commit + itself, which has been corrected. + + * In read-only repositories, "git merge-tree" tried to come up with a + merge result tree object, which it failed (which is not wrong) and + led to a segfault (which is bad), which has been corrected. + + * Force C locale while running tests around httpd to make sure we can + find expected error messages in the log. + + * Fix a logic in "mailinfo -b" that miscomputed the length of a + substring, which lead to an out-of-bounds access. + + * The codepath to sign learned to report errors when it fails to read + from "ssh-keygen". + + * "GIT_EDITOR=: git branch --edit-description" resulted in failure, + which has been corrected. + + * Documentation on various Boolean GIT_* environment variables have + been clarified. + + * "git multi-pack-index repack/expire" used to repack unreachable + cruft into a new pack, which have been corrected. + + * The code to clean temporary object directories (used for + quarantine) tried to remove them inside its signal handler, which + was a no-no. + + * "git branch --edit-description" on an unborh branch misleadingly + said that no such branch exists, which has been corrected. + + * GitHub CI settings have been adjusted to recent reality, merging + and cherry-picking necessary topics that have been prepared for Git + 2.39. + + * `git rebase --update-refs` would delete references when all `update-ref` + commands in the sequencer were removed, which has been corrected. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.38.3.txt b/Documentation/RelNotes/2.38.3.txt new file mode 100644 index 0000000..4a46bb4 --- /dev/null +++ b/Documentation/RelNotes/2.38.3.txt @@ -0,0 +1,5 @@ +Git v2.38.3 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.38.4.txt b/Documentation/RelNotes/2.38.4.txt new file mode 100644 index 0000000..fdfde22 --- /dev/null +++ b/Documentation/RelNotes/2.38.4.txt @@ -0,0 +1,7 @@ +Git v2.38.4 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7, +v2.32.6, v2.33.7, v2.34.7, v2.35.7, v2.36.5 and v2.37.6 to +address the security issues CVE-2023-22490 and CVE-2023-23946; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.38.5.txt b/Documentation/RelNotes/2.38.5.txt new file mode 100644 index 0000000..2d1f3b1 --- /dev/null +++ b/Documentation/RelNotes/2.38.5.txt @@ -0,0 +1,8 @@ +Git v2.38.5 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8, v2.36.6 and v2.37.7 to address +the security issues CVE-2023-25652, CVE-2023-25815, and +CVE-2023-29007; see the release notes for these versions for +details. diff --git a/Documentation/RelNotes/2.39.0.txt b/Documentation/RelNotes/2.39.0.txt new file mode 100644 index 0000000..9bf00ec --- /dev/null +++ b/Documentation/RelNotes/2.39.0.txt @@ -0,0 +1,346 @@ +Git v2.39 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * "git grep" learned to expand the sparse-index more lazily and on + demand in a sparse checkout. + + * By default, use of fsmonitor on a repository on networked + filesystem is disabled. Add knobs to make it workable on macOS. + + * After checking out a "branch" that is a symbolic-ref that points at + another branch, "git symbolic-ref HEAD" reports the underlying + branch, not the symbolic-ref the user gave checkout as argument. + The command learned the "--no-recurse" option to stop after + dereferencing a symbolic-ref only once. + + * "git branch --edit-description @{-1}" is now a way to edit branch + description of the branch you were on before switching to the + current branch. + + * "git merge-tree --stdin" is a new way to request a series of merges + and report the merge results. + + * "git shortlog" learned to group by the "format" string. + + * A new "--include-whitespace" option is added to "git patch-id", and + existing bugs in the internal patch-id logic that did not match + what "git patch-id" produces have been corrected. + + * Enable gc.cruftpacks by default for those who opt into + feature.experimental setting. + + * "git repack" learns to send cruft objects out of the way into + packfiles outside the repository. + + * 'scalar reconfigure -a' is taught to automatically remove + scalar.repo entires which no longer exist. + + * Redact headers from cURL's h2h3 module in GIT_CURL_VERBOSE and + others. + + * 'git maintenance register' is taught to write configuration to an + arbitrary path, and 'git for-each-repo' is taught to expand tilde + characters in paths. + + * When creating new notes, the template used to get a stray empty + newline, which has been removed. + + * "git receive-pack" used to use all the local refs as the boundary for + checking connectivity of the data "git push" sent, but now it uses + only the refs that it advertised to the pusher. In a repository with + the .hideRefs configuration, this reduces the resources needed to + perform the check. + + * With '--recurse-submodules=on-demand', all submodules are + recursively pushed. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * With a bit of header twiddling, use the native regexp library on + macOS instead of the compat/ one. + + * Prepare for GNU [ef]grep that throw warning of their uses. + + * Sources related to fuzz testing have been moved down to their own + directory. + + * Most credential helpers ignored unknown entries in a credential + description, but a few died upon seeing them. The latter were + taught to ignore them, too + + * "scalar unregister" in a repository that is already been + unregistered reported an error. + + * Remove error detection from a function that fetches from promisor + remotes, and make it die when such a fetch fails to bring all the + requested objects, to give an early failure to various operations. + + * Update CodingGuidelines to clarify what features to use and avoid + in C99. + + * Avoid false-positive from LSan whose assumption may be broken with + higher optimization levels. + + * Enable address and undefined sanitizer tasks at GitHub Actions CI. + + * More UNUSED annotation to help using -Wunused option with the + compiler. + (merge 4b992f0a24 jk/unused-anno-more later to maint). + + * Rewrite a deep recursion in the skipping negotiator to use a loop + with on-heap prio queue to avoid stack wastage. + + * Add documentation for message IDs in fsck error messages. + + * Define the logical elements of a "bundle list", data structure to + store them in-core, format to transfer them, and code to parse + them. + + * The role the security mailing list plays in an embargoed release + has been documented. + + * Two new facilities, "timer" and "counter", are introduced to the + trace2 API. + + * Code simplification by using strvec_pushf() instead of building an + argument in a separate strbuf. + + * Make sure generated dependency file is stably sorted to help + developers debugging their build issues. + + * The glossary entries for "commit-graph file" and "reachability + bitmap" have been added. + + * Various tests exercising the transfer.credentialsInUrl + configuration are taught to avoid making requests which require + resolving localhost to reduce CI-flakiness. + + * A redundant diagnostic message is dropped from test_path_is_missing(). + + * Simplify the run-command API. + + * Update the actions/github-script dependency in CI to avoid a + deprecation warning. + + * Progress on being able to initialize a rev_info struct with a + macro. + + * Add trace2 counters to the region to clear skip worktree bits in a + sparse checkout. + + * Modernize test script to avoid "test -f" and friends. + + * Avoid calling 'cache_tree_update()' when doing so would be + redundant. + + * Update the credential-cache documentation to provide a more + realistic example. + + * Makefile comments updates and reordering to clarify knobs used to + choose SHA implementations. + + * A design document for sparse-checkout's future directions has been + added. + + * Teach chainlint.pl to annotate the original test definition instead + of the token stream. + + * "make coccicheck" is time consuming. It has been made to run more + incrementally. + + * `parse_object()` has been hardened to check for the existence of a + suspected blob object. + + * The build procedure has been adjusted to GNUmake version 4.4, which + made some changes to how pattern rule with multiple targets are + handled. + + +Fixes since v2.38 +----------------- + + * The codepath that reads from the index v4 had unaligned memory + accesses, which has been corrected. + + * Fix messages incorrectly marked for translation. + + * "git fsck" failed to release contents of tree objects already used + from the memory, which has been fixed. + + * "git clone" did not like to see the "--bare" and the "--origin" + options used together without a good reason. + + * "git remote rename" failed to rename a remote without fetch + refspec, which has been corrected. + + * Documentation on various Boolean GIT_* environment variables have + been clarified. + + * "git rebase -i" can mistakenly attempt to apply a fixup to a commit + itself, which has been corrected. + + * "git multi-pack-index repack/expire" used to repack unreachable + cruft into a new pack, which have been corrected. + + * In read-only repositories, "git merge-tree" tried to come up with a + merge result tree object, which it failed (which is not wrong) and + led to a segfault (which is bad), which has been corrected. + + * Force C locale while running tests around httpd to make sure we can + find expected error messages in the log. + + * Fix a logic in "mailinfo -b" that miscomputed the length of a + substring, which lead to an out-of-bounds access. + + * The codepath to sign learned to report errors when it fails to read + from "ssh-keygen". + + * Code clean-up that results in plugging a leak. + + * "GIT_EDITOR=: git branch --edit-description" resulted in failure, + which has been corrected. + + * The code to clean temporary object directories (used for + quarantine) tried to remove them inside its signal handler, which + was a no-no. + + * Update comment in the Makefile about the RUNTIME_PREFIX config knob. + + * Clarify that "the sentence after <area>: prefix does not begin with + a capital letter" rule applies only to the commit title. + + * "git branch --edit-description" on an unborn branch misleadingly + said that no such branch exists, which has been corrected. + + * Work around older clang that warns against C99 zero initialization + syntax for struct. + + * Giving "--invert-grep" and "--all-match" without "--grep" to the + "git log" command resulted in an attempt to access grep pattern + expression structure that has not been allocated, which has been + corrected. + (merge db84376f98 ab/grep-simplify-extended-expression later to maint). + + * "git diff rev^!" did not show combined diff to go to the rev from + its parents. + (merge a79c6b6081 rs/diff-caret-bang-with-parents later to maint). + + * Allow configuration files in "protected" scopes to include other + configuration files. + (merge ecec57b3c9 gc/bare-repo-discovery later to maint). + + * Give a bit more diversity to macOS CI by using sha1dc in one of the + jobs (the other one tests Apple Common Crypto). + (merge 1ad5c3df35 jc/ci-osx-with-sha1dc later to maint). + + * A bugfix with tracing support in midx codepath + (merge e9c3839944 tb/midx-bitmap-selection-fix later to maint). + + * When geometric repacking feature is in use together with the + --pack-kept-objects option, we lost packs marked with .keep files. + (merge 197443e80a tb/save-keep-pack-during-geometric-repack later to maint). + + * Move a global variable added as a hack during regression fixes to + its proper place in the API. + (merge 0b0ab95f17 ab/run-hook-api-cleanup later to maint). + + * Update to build procedure with VS using CMake/CTest. + (merge c858750b41 js/cmake-updates later to maint). + + * The short-help text shown by "git cmd -h" and the synopsis text + shown at the beginning of "git help cmd" have been made more + consistent. + + * When creating a multi-pack bitmap, remove per-pack bitmap files + unconditionally as they will never be consulted. + (merge 55d902cd61 tb/remove-unused-pack-bitmap later to maint). + + * Fix a longstanding syntax error in Git.pm error codepath. + + * "git diff --stat" etc. were invented back when everything was ASCII + and strlen() was a way to measure the display width of a string; + adjust them to compute the display width assuming UTF-8 pathnames. + (merge ce8529b2bb tb/diffstat-with-utf8-strwidth later to maint). + + * "git branch --edit-description" can exit with status -1 which is + not a good practice; it learned to use 1 as everybody else instead. + + * "git apply" limits its input to a bit less than 1 GiB. + + * Merging a branch with directory renames into a branch that changes + the directory to a symlink was mishandled by the ort merge + strategy, which has been corrected. + + * A bugfix to "git subtree" in its split and merge features. + + * Fix some bugs in the reflog messages when rebasing and changes the + reflog messages of "rebase --apply" to match "rebase --merge" with + the aim of making the reflog easier to parse. + + * "git rebase --keep-base" used to discard the commits that are + already cherry-picked to the upstream, even when "keep-base" meant + that the base, on top of which the history is being rebuilt, does + not yet include these cherry-picked commits. The --keep-base + option now implies --reapply-cherry-picks and --no-fork-point + options. + + * The way "git repack" created temporary files when it received a + signal was prone to deadlocking, which has been corrected. + + * Various tests exercising the transfer.credentialsInUrl + configuration are taught to avoid making requests which require + resolving localhost to reduce CI-flakiness. + + * The adjust_shared_perm() helper function learned to refrain from + setting the "g+s" bit on directories when it is not necessary. + + * "git archive" mistakenly complained twice about a missing + executable, which has been corrected. + + * Fix a bug where `git branch -d` did not work on an orphaned HEAD. + + * `git rebase --update-refs` would delete references when all + `update-ref` commands in the sequencer were removed, which has been + corrected. + + * Fix a regression in the bisect-helper which mistakenly treats + arguments to the command given to 'git bisect run' as arguments to + the helper. + + * Correct an error where `git rebase` would mistakenly use a branch or + tag named "refs/rewritten/xyz" when missing a rebase label. + + * Assorted fixes of parsing end-user input as integers. + (merge 14770cf0de pw/config-int-parse-fixes later to maint). + + * "git prune" may try to iterate over .git/objects/pack for trash + files to remove in it, and loudly fail when the directory is + missing, which is not necessary. The command has been taught to + ignore such a failure. + (merge 6974765352 ew/prune-with-missing-objects-pack later to maint). + + * Add one more candidate directory that may house httpd modules while + running tests. + (merge 1c7dc23d41 es/locate-httpd-module-location-in-test later to maint). + + * A handful of leaks in the line-log machinery have been plugged. + + * The format of a line in /proc/cpuinfo that describes a CPU on s390x + looked different from everybody else, and the code in chainlint.pl + failed to parse it. + (merge 1f51b77f4f ah/chainlint-cpuinfo-parse-fix later to maint). + + * Adjust the GitHub CI to newer ubuntu release. + (merge 0d3507f3e7 jx/ci-ubuntu-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 413bc6d20a ds/cmd-main-reorder later to maint). + (merge 8d2863e4ed nw/t1002-cleanup later to maint). + (merge 7c2dc122f9 rs/list-objects-filter-leakfix later to maint). + (merge 288fcb1c94 zk/push-use-bitmaps later to maint). + (merge 42db324c0f km/merge-recursive-typofix later to maint). diff --git a/Documentation/RelNotes/2.39.1.txt b/Documentation/RelNotes/2.39.1.txt new file mode 100644 index 0000000..60c86f4 --- /dev/null +++ b/Documentation/RelNotes/2.39.1.txt @@ -0,0 +1,5 @@ +Git v2.39.1 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.39.2.txt b/Documentation/RelNotes/2.39.2.txt new file mode 100644 index 0000000..ebb9900 --- /dev/null +++ b/Documentation/RelNotes/2.39.2.txt @@ -0,0 +1,7 @@ +Git v2.39.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.8, v2.31.7, +v2.32.6, v2.33.7, v2.34.7, v2.35.7, v2.36.5, v2.37.6 and v2.38.4 +to address the security issues CVE-2023-22490 and CVE-2023-23946; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.39.3.txt b/Documentation/RelNotes/2.39.3.txt new file mode 100644 index 0000000..66351b6 --- /dev/null +++ b/Documentation/RelNotes/2.39.3.txt @@ -0,0 +1,64 @@ +Git v2.39.3 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8, v2.36.6, v2.37.7 and v2.38.5 to +address the security issues CVE-2023-25652, CVE-2023-25815, and +CVE-2023-29007; see the release notes for these versions for +details. + +This release also merges fixes that have accumulated on the 'master' +front to prepare for the 2.40 release that are still relevant to +2.39.x maintenance track. + +Fixes since v2.39.2 +------------------- + + * Stop running win+VS build by default. + + * CI updates. We probably want a clean-up to move the long shell + script embedded in yaml file into a separate file, but that can + come later. + + * Avoid unnecessary builds in CI, with settings configured in + ci-config. + + * Redefining system functions for a few functions did not follow our + usual "implement git_foo() and #define foo(args) git_foo(args)" + pattern, which has broken build for some folks. + + * Deal with a few deprecation warning from cURL library. + + * Newer regex library macOS stopped enabling GNU-like enhanced BRE, + where '\(A\|B\)' works as alternation, unless explicitly asked with + the REG_ENHANCED flag. "git grep" now can be compiled to do so, to + retain the old behaviour. + + * When given a pattern that matches an empty string at the end of a + line, the code to parse the "git diff" line-ranges fell into an + infinite loop, which has been corrected. + + * Fix the sequence to fsync $GIT_DIR/packed-refs file that forgot to + flush its output to the disk.. + + * "git diff --relative" did not mix well with "git diff --ext-diff", + which has been corrected. + + * The logic to see if we are using the "cone" mode by checking the + sparsity patterns has been tightened to avoid mistaking a pattern + that names a single file as specifying a cone. + + * Doc update for environment variables set when hooks are invoked. + + * Document ORIG_HEAD a bit more. + + * "git ls-tree --format='%(path) %(path)' $tree $path" showed the + path three times, which has been corrected. + + * Document that "branch -f <branch>" disables only the safety to + avoid recreating an existing branch. + + * Clarify how "checkout -b/-B" and "git branch [-f]" are similar but + different in the documentation. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.40.0.txt b/Documentation/RelNotes/2.40.0.txt new file mode 100644 index 0000000..3ea445b --- /dev/null +++ b/Documentation/RelNotes/2.40.0.txt @@ -0,0 +1,320 @@ +Git v2.40 Release Notes +======================= + +UI, Workflows & Features + + * "merge-tree" learns a new `--merge-base` option. + + * "git jump" (in contrib/) learned to present the "quickfix list" to + its standard output (instead of letting it consumed by the editor + it invokes), and learned to also drive emacs/emacsclient. + + * "git var UNKNOWN_VARIABLE" and "git var VARIABLE" with the variable + given an empty value used to behave identically. Now the latter + just gives an empty output, while the former still gives an error + message. + + * Introduce a case insensitive mode to the Bash completion helpers. + + * The advice message given by "git status" when it takes long time to + enumerate untracked paths has been updated. + + * Just like "git var GIT_EDITOR" abstracts the complex logic to + choose which editor gets used behind it, "git var" now give support + to GIT_SEQUENCE_EDITOR. + + * "git format-patch" learned to honor format.mboxrd even when sending + patches to the standard output stream, + + * 'cat-file' gains mailmap support for its '--batch-check' and '-s' + options. + + * Conditionally skip the pre-applypatch and applypatch-msg hooks when + applying patches with 'git am'. + + * Introduce an optional configuration to allow the trailing hash that + protects the index file from bit flipping. + + * "git check-attr" learned to take an optional tree-ish to read the + .gitattributes file from. + + * "scalar" learned to give progress bar. + + * "grep -P" learned to use Unicode Character Property to grok + character classes when processing \b and \w etc. + + * "git rebase" often ignored incompatible options instead of + complaining, which has been corrected. + + * "scalar" warns but continues when its periodic maintenance + feature cannot be enabled. + + * The bundle-URI subsystem adds support for creation-token heuristics + to help incremental fetches. + + * Userdiff regexp update for Java language. + + * "git fetch --jobs=0" used to hit a BUG(), which has been corrected + to use the available CPUs. + + * An invalid label or ref in the "rebase -i" todo file used to + trigger an runtime error. SUch an error is now diagnosed while the + todo file is parsed. + + * The "diff" drivers specified by the "diff" attribute attached to + paths can now specify which algorithm (e.g. histogram) to use. + + * "git range-diff" learned --abbrev=<num> option. + + * "git archive HEAD^{tree}" records the paths with the current + timestamp in the archive, making it harder to obtain a stable + output. The command learned the --mtime option to specify an + arbitrary timestamp (e.g. --mtime="@0 +0000" for the epoch). + + * The credential subsystem learned that a password may have an + explicit expiration. + + * The format.attach configuration variable lacked a way to override a + value defined in a lower-priority configuration file (e.g. the + system one) by redefining it in a higher-priority configuration + file. Now, setting format.attach to an empty string means show the + patch inline in the e-mail message, without using MIME attachment. + + This is a backward incompatible change. + + +Performance, Internal Implementation, Development Support etc. + + * `git bisect` becomes a builtin. + + * The pack-bitmap machinery is taught to log the paths of redundant + bitmap(s) to trace2 instead of stderr. + + * Use the SHA1DC implementation on macOS, just like other platforms, + by default. + + * Even in a repository with promisor remote, it is useless to + attempt to lazily attempt fetching an object that is expected to be + commit, because no "filter" mode omits commit objects. Take + advantage of this assumption to fail fast on errors. + + * Stop using "git --super-prefix" and narrow the scope of its use to + the submodule--helper. + + * Stop running win+VS build by default. + + * CI updates. We probably want a clean-up to move the long shell + script embedded in yaml file into a separate file, but that can + come later. + + * Use `git diff --no-index` as a test_cmp on Windows. + + We'd probably need to revisit "do we really want to, and have to, + lose CRLF vs LF?" later, at which time we may be able to further + clean this up by replacing "git diff --no-index" with "diff -u". + + * Avoid unnecessary builds in CI, with settings configured in + ci-config. + + * Plug leaks in sequencer subsystem and its users. + + * In-tree .gitattributes update to match the way we recommend our + users to mark a file as text. + (merge 1f34e0cd3d po/attributes-text later to maint). + + * Finally retire the scripted "git add -p/-i" implementation and have + everybody use the one reimplemented in C. + + +Fixes since v2.39 +----------------- + + * Various leak fixes. + + * Fix a bug where `pack-objects` would not respect multiple `--filter` + arguments when invoked directly. + (merge d4f7036887 rs/multi-filter-args later to maint). + + * Make fsmonitor more robust to avoid the flakiness seen in t7527. + (merge 6692d45477 jh/t7527-unflake-by-forcing-cookie later to maint). + + * Stop using deprecated macOS API in fsmonitor. + (merge b0226007f0 jh/fsmonitor-darwin-modernize later to maint). + + * Redefining system functions for a few functions did not follow our + usual "implement git_foo() and #define foo(args) git_foo(args)" + pattern, which has broken build for some folks. + + * The way the diff machinery prepares the options array for the + parse_options API has been refactored to avoid resource leaks. + (merge 189e97bc4b rs/diff-parseopts later to maint). + + * Correct pthread API usage. + (merge 786e67611d sx/pthread-error-check-fix later to maint). + + * The code to auto-correct a misspelt subcommand unnecessarily called + into git_default_config() from the early config codepath, which was + a no-no. This has bee corrected. + (merge 0918d08887 sg/help-autocorrect-config-fix later to maint). + + * "git http-fetch" (which is rarely used) forgot to identify itself + in the trace2 output. + (merge 7abb43cbc8 jt/http-fetch-trace2-report-name later to maint). + + * The output from "git diff --stat" on an unmerged path lost the + terminating LF in Git 2.39, which has been corrected. + (merge 209d9cb011 pg/diff-stat-unmerged-regression-fix later to maint). + + * "git pull -v --recurse-submodules" attempted to pass "-v" down to + underlying "git submodule update", which did not understand the + request and barfed, which has been corrected. + (merge 6f65f84766 ss/pull-v-recurse-fix later to maint). + + * When given a pattern that matches an empty string at the end of a + line, the code to parse the "git diff" line-ranges fell into an + infinite loop, which has been corrected. + + * Fix the sequence to fsync $GIT_DIR/packed-refs file that forgot to + flush its output to the disk.. + + * Fix to a small regression in 2.38 days. + + * "git diff --relative" did not mix well with "git diff --ext-diff", + which has been corrected. + + * The logic to see if we are using the "cone" mode by checking the + sparsity patterns has been tightened to avoid mistaking a pattern + that names a single file as specifying a cone. + + * Deal with a few deprecation warning from cURL library. + + * Doc update for environment variables set when hooks are invoked. + + * Document ORIG_HEAD a bit more. + + * "git ls-tree --format='%(path) %(path)' $tree $path" showed the + path three times, which has been corrected. + + * Remove "git env--helper" and demote it to a test-tool subcommand. + (merge 4a1baacd46 ab/test-env-helper later to maint). + + * Newer regex library macOS stopped enabling GNU-like enhanced BRE, + where '\(A\|B\)' works as alternation, unless explicitly asked with + the REG_ENHANCED flag. "git grep" now can be compiled to do so, to + retain the old behaviour. + + * Pthread emulation on Win32 leaked thread handle when a thread is + joined. + (merge 238a9dfe86 sk/win32-close-handle-upon-pthread-join later to maint). + + * "git send-email -v 3" used to be expanded to "git send-email + --validate 3" when the user meant to pass them down to + "format-patch", which has been corrected. + (merge 8774aa56ad km/send-email-with-v-reroll-count later to maint). + + * Document that "branch -f <branch>" disables only the safety to + avoid recreating an existing branch. + + * "git fetch <group>", when "<group>" of remotes lists the same + remote twice, unnecessarily failed when parallel fetching was + enabled, which has been corrected. + (merge 06a668cb90 cw/fetch-remote-group-with-duplication later to maint). + + * Clarify how "checkout -b/-B" and "git branch [-f]" are similar but + different in the documentation. + + * "git hash-object" now checks that the resulting object is well + formed with the same code as "git fsck". + (merge 8e4309038f jk/hash-object-fsck later to maint). + + * Improve the error message given when private key is not loaded in + the ssh agent in the codepath to sign with an ssh key. + (merge dce7b31126 as/ssh-signing-improve-key-missing-error later to maint). + + * Adjust "git request-pull" to strip embedded signature from signed + tags to notice non-PGP signatures. + (merge a9cad02538 gm/request-pull-with-non-pgp-signed-tags later to maint). + + * Remove support for MSys, which now lags way behind MSys2. + (merge 2987407f3c hj/remove-msys-support later to maint). + + * Fix use of CreateThread() API call made early in the windows + start-up code. + (merge 592bcab61b sk/winansi-createthread-fix later to maint). + + * "git pack-objects" learned to release delta-island bitmap data when + it is done using it, saving peak heap memory usage. + (merge 647982bb71 ew/free-island-marks later to maint). + + * In an environment where dynamically generated code is prohibited to + run (e.g. SELinux), failure to JIT pcre patterns is expected. Fall + back to interpreted execution in such a case. + (merge 50b6ad55b0 cb/grep-fallback-failing-jit later to maint). + + * "git name-rev" heuristics update. + (merge b2182a8730 en/name-rev-make-taggerdate-much-less-important later to maint). + + * Remove more remaining uses of macros that relies on the_index + singleton instance without explicitly spelling it out. + + * Remove unnecessary explicit sizing of strbuf. + (merge 93ea118bed rs/cache-tree-strbuf-growth-fix later to maint). + + * Doc update. + (merge d9ec3b0dc0 jk/doc-ls-remote-matching later to maint). + + * Error messages given upon a signature verification failure used to + discard the errors from underlying gpg program, which has been + corrected. + (merge ad6b320756 js/gpg-errors later to maint). + + * Update --date=default documentation. + (merge 9deef088ae rd/doc-default-date-format later to maint). + + * A test helper had a single write(2) of 256kB, which was too big for + some platforms (e.g. NonStop), which has been corrected by using + xwrite() wrapper appropriately. + (merge 58eab6ff13 jc/genzeros-avoid-raw-write later to maint). + + * sscanf(3) used in "git symbolic-ref --short" implementation found + to be not working reliably on macOS in UTF-8 locales. Rewrite the + code to avoid sscanf() altogether to work it around. + (merge 613bef56b8 jk/shorten-unambiguous-ref-wo-sscanf later to maint). + + * Various fix-ups on HTTP tests. + (merge 8f2146dbf1 jk/http-test-fixes later to maint). + + * Fixes to code that parses the todo file used in "rebase -i". + (merge 666b6e1135 pw/rebase-i-parse-fix later to maint). + + * Test library clean-up. + (merge c600a91c94 ar/test-lib-remove-stale-comment later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 4eb1ccecd4 dh/mingw-ownership-check-typofix later to maint). + (merge f95526419b ar/typofix-gitattributes-doc later to maint). + (merge 27875aeec9 km/doc-branch-start-point later to maint). + (merge 35c194dc57 es/t1509-root-fixes later to maint). + (merge 7b341645e3 pw/ci-print-failure-name-fix later to maint). + (merge bcb71d45bf jx/t1301-updates later to maint). + (merge ebdc46c242 jc/doc-diff-patch.txt later to maint). + (merge a87a20cbb4 ar/test-cleanup later to maint). + (merge f5156f1885 ar/bisect-doc-update later to maint). + (merge fca2d86c97 jk/interop-error later to maint). + (merge cf4936ed74 tl/ls-tree-code-clean-up later to maint). + (merge dcb47e52b0 en/t6426-todo-cleanup later to maint). + (merge 5b8db44bdd jc/format-patch-v-unleak later to maint). + (merge 590b636737 jk/hash-object-literally-fd-leak later to maint). + (merge 5458ba0a4d tb/t0003-invoke-dd-more-portably later to maint). + (merge 70661d288b ar/markup-em-dash later to maint). + (merge e750951e74 en/ls-files-doc-update later to maint). + (merge 4f542975d1 mh/doc-credential-cache-only-in-core later to maint). + (merge 3a2ebaebc7 gc/index-format-doc later to maint). + (merge b08edf709d jk/httpd-test-updates later to maint). + (merge d85e9448dd wl/new-command-doc later to maint). + (merge d912a603ed kf/t5000-modernise later to maint). + (merge e65b868d07 rs/size-t-fixes later to maint). + (merge 3eb1e1ca9a ab/config-h-remove-unused later to maint). + (merge d390e08076 cw/doc-pushurl-vs-url later to maint). + (merge 567342fc77 rs/ctype-test later to maint). + (merge d35d8f2e7a ap/t2015-style-update later to maint). diff --git a/Documentation/RelNotes/2.40.1.txt b/Documentation/RelNotes/2.40.1.txt new file mode 100644 index 0000000..e72f6b1 --- /dev/null +++ b/Documentation/RelNotes/2.40.1.txt @@ -0,0 +1,8 @@ +Git v2.40.1 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8, v2.36.6, v2.37.7, v2.38.5 +and v2.39.3 to address the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007; see the release notes for these +versions for details. diff --git a/Documentation/RelNotes/2.41.0.txt b/Documentation/RelNotes/2.41.0.txt new file mode 100644 index 0000000..8a9e170 --- /dev/null +++ b/Documentation/RelNotes/2.41.0.txt @@ -0,0 +1,399 @@ +Git v2.41 Release Notes +======================= + +UI, Workflows & Features + + * Allow information carried on the WWW-Authenticate header to be + passed to the credential helpers. + + * A new "fetch.hideRefs" option can be used to exclude specified refs + from "rev-list --objects --stdin --not --all" traversal for + checking object connectivity, most useful when there are many + unrelated histories in a single repository. + + * "git push" has been taught to allow deletion of refs with one-level + names to help repairing a repository who acquired such a ref by + mistake. In general, we don't encourage use of such a ref, and + creation or update to such a ref is rejected as before. + + * Allow "git bisect reset" to check out the original branch when the + branch is already checked out in a different worktree linked to the + same repository. + + * A few subcommands have been taught to stop users from working on a + branch that is being used in another worktree linked to the same + repository. + + * "git format-patch" learned to write a log-message only output file + for empty commits. + + * "git format-patch" honors the src/dst prefixes set to nonstandard + values with configuration variables like "diff.noprefix", causing + receiving end of the patch that expects the standard -p1 format to + break. "format-patch" has been taught to ignore end-user configuration + and always use the standard prefixes. + + This is a backward compatibility breaking change. + + * Lift the limitation that colored prompts can only be used with + PROMPT_COMMAND mode. + + * "git blame --contents=<file> <rev> -- <path>" used to be forbidden, + but now it finds the origins of lines starting at <file> contents + through the history that leads to <rev>. + + * "git pack-redundant" gave a warning when run, as the command has + outlived its usefulness long ago and is nominated for future + removal. Now we escalate to give an error. + + * "git clone" from an empty repository learned to propagate the + choice of the hash algorithm from the source repository to the + newly created repository over any one of the v0/v1/v2 protocol. + + * "git mergetool" and "git difftool" learns a new configuration + guiDefault to optionally favor configured guitool over non-gui-tool + automatically when $DISPLAY is set. + + * "git branch -d origin/master" would say "no such branch", but it is + likely a missed "-r" if refs/remotes/origin/master exists. The + command has been taught to give such a hint in its error message. + + * Clean-up of the code path that deals with merge strategy option + handling in "git rebase". + + * "git clone --local" stops copying from an original repository that + has symbolic links inside its $GIT_DIR; an error message when that + happens has been updated. + + * The "--format=..." option of "git for-each-ref", "git branch", and + "git tag" commands learn "--omit-empty" to hide refs whose + formatting results in an empty string from the output. + + * The sendemail-validate validate hook learned to pass the total + number of input files and where in the sequence each invocation is + via environment variables. + + * When "gc" needs to retain unreachable objects, packing them into + cruft packs (instead of exploding them into loose object files) has + been offered as a more efficient option for some time. Now the use + of cruft packs has been made the default and no longer considered + an experimental feature. + + * The output given by "git blame" that attributes a line to contents + taken from the file specified by the "--contents" option shows it + differently from a line attributed to the working tree file. + + * "git send-email" learned to give the e-mail headers to the validate + hook by passing an extra argument from the command line. + + * The credential subsystem learns to help OAuth framework. + + * The titles of manual pages used to be chomped at an unreasonably + short limit, which has been removed. + + * Error messages given when working on an unborn branch that is + checked out in another worktree have been improved. + + * The documentation was misleading about the interaction between + GIT_DEFAULT_HASH and "git clone", which has been clarified to + stress that the variable is to be ignored by the command. + + * "git send-email" learned "--header-cmd=<cmd>" that can inject + arbitrary e-mail header lines to the outgoing messages. + + * "git fsck" learned to detect bit-flip breakages in the reachability + bitmap files. + + * The "--stdin" option of "git name-rev" has been replaced with + the "--annotate-stdin" option more than a year ago. We stop + advertising it in the "git name-rev -h" output. + + * "git push --all" gained an alias "git push --branches". + + * "git fetch" learned the "--porcelain" option that emits what it did + in a machine-parseable format. + + * "git --attr-source=<tree> cmd $args" is a new way to have any + command to read attributes not from the working tree but from the + given tree object. + + +Performance, Internal Implementation, Development Support etc. + + * Code clean-up to clarify directory traversal API. + + * Code clean-up to clarify the rule that "git-compat-util.h" must be + the first to be included. + + * More work towards -Wunused. + + * Instead of forcing each command to choose to honor GPG related + configuration variables, make the subsystem lazily initialize + itself. + + * Remove workaround for ancient versions of DocBook to make it work + correctly with groff, which has not been necessary since docbook + 1.76 from 2010. + + * Code clean-up to include and/or uninclude parse-options.h file as + needed. + + * The code path that reports what "git fetch" did to each ref has + been cleaned up. + + * Assorted config API updates. + + * A few configuration variables to tell the cURL library that + different types of ssl-cert and ssl-key are in use have been added. + + * Split key function and data structure definitions out of cache.h to + new header files and adjust the users. + + * "git fetch --all" does not have to download and handle the same + bundleURI over and over, which has been corrected. + + * "git sparse-checkout" command learns a debugging aid for the sparse + rule definitions. + + * "git write-tree" learns to work better with sparse-index. + + * The on-disk reverse index that allows mapping from the pack offset + to the object name for the object stored at the offset has been + enabled by default. + + * "git fsck" learned to validate the on-disk pack reverse index files. + + * strtok() and strtok_r() are banned in this codebase. + + * The detect-compilers script to help auto-tweaking the build system + had trouble working with compilers whose version number has extra + suffixes. The script has been taught that certain suffixes (like + "-win32" in "gcc 10-win32") can be safely stripped as they share + the same features and bugs with the version without the suffix. + + * ctype tests have been taught to test EOF, too. + + * The implementation of credential helpers used fgets() over fixed + size buffers to read protocol messages, causing the remainder of + the folded long line to trigger unexpected behaviour, which has + been corrected. + + * The implementation of the default "negotiator", used to find common + ancestor over the network for object tranfer, used to be recursive; + it was updated to be iterative to conserve stackspace usage. + + * Our custom callout formatter is no longer used in the documentation + formatting toolchain, as the upstream default ones give better + output these days. + + * The tracing mechanism learned to notice and report when + auto-discovered bare repositories are being used, as allowing so + without explicitly stating the user intends to do so (with setting + GIT_DIR for example) can be used with social engineering as an + attack vector. + + * "git diff-files" learned not to expand sparse-index unless needed. + + +Fixes since v2.40 +----------------- + + * "git fsck" learned to check the index files in other worktrees, + just like "git gc" honors them as anchoring points. + (merge 8d3e7eac52 jk/fsck-indices-in-worktrees later to maint). + + * Fix a segfaulting loop. The function and its caller may need + further clean-up. + (merge c5773dc078 ew/commit-reach-clean-up-flags-fix later to maint). + + * "git restore" supports options like "--ours" that are only + meaningful during a conflicted merge, but these options are only + meaningful when updating the working tree files. These options are + marked to be incompatible when both "--staged" and "--worktree" are + in effect. + (merge ee8a88826a ak/restore-both-incompatible-with-conflicts later to maint). + + * Simplify UI to control progress meter given by "git bundle" command. + (merge 8b95521edb jk/bundle-progress later to maint). + + * "git bundle" learned that "-" is a common way to say that the input + comes from the standard input and/or the output goes to the + standard output. It used to work only for output and only from the + root level of the working tree. + (merge 0bbe10313e jk/bundle-use-dash-for-stdfiles later to maint). + + * Once we start running, we assumed that the list of alternate object + databases would never change. Hook into the machinery used to + update the list of packfiles during runtime to update this list as + well. + (merge e2d003dbed ds/reprepare-alternates-when-repreparing-packfiles later to maint). + + * The code to parse "git rebase -X<opt>" was not prepared to see an + unparsable option string, which has been corrected. + (merge 15a4cc912e ab/fix-strategy-opts-parsing later to maint). + + * "git add -p" while the index is unmerged sometimes failed to parse + the diff output it internally produces and died, which has been + corrected. + (merge 28d1122f9c jk/add-p-unmerged-fix later to maint). + + * Fix for a "ls-files --format="%(path)" that produced nonsense + output, which was a bug in 2.38. + (merge cfb62dd006 aj/ls-files-format-fix later to maint). + + * "git receive-pack" that responds to "git push" requests failed to + clean a stale lockfile when killed in the middle, which has been + corrected. + (merge c55c30669c ps/receive-pack-unlock-before-die later to maint). + + * "git rev-parse --quiet foo@{u}", or anything that asks @{u} to be + parsed with GET_OID_QUIETLY option, did not quietly fail, which has + been corrected. + (merge dfbfdc521d fc/oid-quietly-parse-upstream later to maint). + + * Transports that do not support protocol v2 did not correctly fall + back to protocol v0 under certain conditions, which has been + corrected. + (merge eaa0fd6584 jk/fix-proto-downgrade-to-v0 later to maint). + + * time(2) on glib 2.31+, especially on Linux, goes out of sync with + higher resolution timers used for gettimeofday(2) and by the + filesystem. Replace all calls to it with a git_time() wrapper and + (merge 370ddcbc89 pe/time-use-gettimeofday later to maint). + + * Code clean-up to use designated initializers in parse-options API. + (merge 353e6d4554 sg/parse-options-h-initializers later to maint). + + * A recent-ish change to allow unicode character classes to be used + with "grep -P" triggered a JIT bug in older pcre2 libraries. + The problematic change in Git built with these older libraries has + been disabled to work around the bug. + (merge 14b9a04479 mk/workaround-pcre-jit-ucp-bug later to maint). + + * The wildmatch library code unlearns exponential behaviour it + acquired some time ago since it was borrowed from rsync. + (merge 3dc0b7f0dc pw/wildmatch-fixes later to maint). + + * The index files can become corrupt under certain conditions when + the split-index feature is in use, especially together with + fsmonitor, which have been corrected. + (merge 061dd722dc js/split-index-fixes later to maint). + + * Document what the pathname-looking strings in "rev-list --object" + output are for and what they mean. + (merge 15364d2a3c jk/document-rev-list-object-name later to maint). + + * Fix unnecessary truncation of generation numbers used in-core. + (merge d3af1c193d ps/ahead-behind-truncation-fix later to maint). + + * Code clean-up around the use of the_repository. + (merge 4a93b899c1 ab/remove-implicit-use-of-the-repository later to maint). + + * Consistently spell "Message-ID" as such, not "Message-Id". + (merge ba4324c4e1 jc/spell-id-in-both-caps-in-message-id later to maint). + + * Correct use of an uninitialized structure member. + (merge dc12ee77ab jx/cap-object-info-uninitialized-fix later to maint). + + * Tests had a few places where we ignored PERL_PATH and blindly used + /usr/bin/perl, which have been corrected. + (merge c1917156a0 jk/use-perl-path-consistently later to maint). + + * Documentation mark-up fix. + (merge 78b6369e67 la/mfc-markup-fix later to maint). + + * Doc toolchain update to remove old workaround for AsciiDoc. + (merge 8806120de6 fc/remove-header-workarounds-for-asciidoc later to maint). + + * The userdiff regexp patterns for various filetypes that are built + into the system have been updated to avoid triggering regexp errors + from UTF-8 aware regex engines. + (merge be39144954 rs/userdiff-multibyte-regex later to maint). + + * The approxidate() API has been simplified by losing an extra + function that did the same thing as another one. + (merge 8a7f0b666f rs/remove-approxidate-relative later to maint). + + * Code clean-up to replace a hardcoded constant with a CPP macro. + (merge c870de6502 rs/get-tar-commit-id-use-defined-const later to maint). + + * Doc build simplification. + (merge 9a09ed3229 fc/doc-stop-using-manversion later to maint). + + * "git archive" run from a subdirectory mishandled attributes and + paths outside the current directory. + (merge 92b1dd1b9e rs/archive-from-subdirectory-fixes later to maint). + + * The code to parse capability list for v0 on-wire protocol fell into + an infinite loop when a capability appears multiple times, which + has been corrected. + + * Geometric repacking ("git repack --geometric=<n>") in a repository + that borrows from an alternate object database had various corner + case bugs, which have been corrected. + (merge d85cd18777 ps/fix-geom-repack-with-alternates later to maint). + + * The "%GT" placeholder for the "--format" option of "git log" and + friends caused BUG() to trigger on a commit signed with an unknown + key, which has been corrected. + (merge 7891e46585 jk/gpg-trust-level-fix later to maint). + + * The completion script used to use bare "read" without the "-r" + option to read the contents of various state files, which risked + getting confused with backslashes in them. This has been + corrected. + (merge 197152098a ek/completion-use-read-r-to-read-literally later to maint). + + * A small API fix to the ort merge strategy backend. + (merge 000c4ceca7 en/ort-finalize-after-0-merges-fix later to maint). + + * The commit object parser has been taught to be a bit more lenient + to parse timestamps on the author/committer line with a malformed + author/committer ident. + (merge 90ef0f14eb jk/parse-commit-with-malformed-ident later to maint). + + * Retitle a test script with an overly narrow name. + (merge 8bb19c14fb ob/t3501-retitle later to maint). + + * Doc update to clarify how text and eol attributes interact to + specify the end-of-line conversion. + (merge 6696077ace ah/doc-attributes-text later to maint). + + * Gitk updates from GfW project. + (merge 99e70f3077 js/gitk-fixes-from-gfw later to maint). + + * "git diff --dirstat" leaked memory, which has been plugged. + (merge 83973981eb jc/dirstat-plug-leaks later to maint). + + * "git merge-tree" reads the basic configuration, which can be used + by git forges to disable replace-refs feature. + (merge b6551feadf ds/merge-tree-use-config later to maint). + + * A few bugs in the sequencer machinery that results in miscounting + the steps have been corrected. + (merge 170eea9750 js/rebase-count-fixes later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge f7111175df as/doc-markup-fix later to maint). + (merge 90ff7c9898 fc/test-aggregation-clean-up later to maint). + (merge 9b0c7f308a jc/am-doc-refer-to-format-patch later to maint). + (merge b10cbdac4c bb/unicode-width-table-15 later to maint). + (merge 3457b50e8c ab/retire-scripted-add-p later to maint). + (merge d52fcf493b ds/p2000-fix-grep-sparse later to maint). + (merge ec063d2591 ss/hashmap-typofix later to maint). + (merge 1aaed69d11 rs/archive-mtime later to maint). + (merge 2da2cc9b28 ob/rollback-after-commit-lock-failure later to maint). + (merge 54dbd0933b ob/sequencer-save-head-simplify later to maint). + (merge a93cbe8d78 ar/test-cleanup-unused-file-creation later to maint). + (merge cc48ddd937 jk/chainlint-fixes later to maint). + (merge 4833b08426 ow/ref-format-remove-unused-member later to maint). + (merge d0ea2ca1cf dw/doc-submittingpatches-grammofix later to maint). + (merge fd72637423 ar/t2024-checkout-output-fix later to maint). + (merge d45cbe3fe0 ob/sequencer-i18n-fix later to maint). + (merge b734fe49fd ob/messages-capitalize-exception later to maint). + (merge ad353d7e77 ma/gittutorial-fixes later to maint). + (merge a5855fd8d4 ar/test-cleanup-unused-file-creation-part2 later to maint). + (merge 0c5308af30 sd/doc-gitignore-and-rm-cached later to maint). + (merge cbb83daeaf kh/doc-interpret-trailers-updates later to maint). + (merge 3d77fbb664 ar/config-count-tests-updates later to maint). + (merge b7cf25c8f4 jc/t9800-fix-use-of-show-s-raw later to maint). diff --git a/Documentation/RelNotes/2.42.0.txt b/Documentation/RelNotes/2.42.0.txt new file mode 100644 index 0000000..0f1897a --- /dev/null +++ b/Documentation/RelNotes/2.42.0.txt @@ -0,0 +1,329 @@ +Git v2.42 Release Notes +======================= + +UI, Workflows & Features + + * "git pack-refs" learns "--include" and "--exclude" to tweak the ref + hierarchy to be packed using pattern matching. + + * 'git worktree add' learned how to create a worktree based on an + orphaned branch with `--orphan`. + + * "git pack-objects" learned to invoke a new hook program that + enumerates extra objects to be used as anchoring points to keep + otherwise unreachable objects in cruft packs. + + * Add more "git var" for toolsmiths to learn various locations Git is + configured with either via the configuration or hard-coded defaults. + + * 'git notes append' was taught '--separator' to specify string to insert + between paragraphs. + + * The "git for-each-ref" family of commands learned placeholders + related to GPG signature verification. + + * "git diff --no-index" learned to read from named pipes as if they + were regular files, to allow "git diff <(process) <(substitution)" + some shells support. + + * Help newbies by suggesting that there are cases where force-pushing + is a valid and sensible thing to update a branch at a remote + repository, rather than reconciling with merge/rebase. + + * "git blame --contents=file" has been taught to work in a bare + repository. + + * "git branch -f X" to repoint the branch X said that X was "checked + out" in another worktree, even when branch X was not and instead + being bisected or rebased. The message was reworded to say the + branch was "in use". + + * Tone down the warning on SHA-256 repositories being an experimental + curiosity. We do not have support for them to interoperate with + traditional SHA-1 repositories, but at this point, we do not plan + to make breaking changes to SHA-256 repositories and there is no + longer need for such a strongly phrased warning. + + +Performance, Internal Implementation, Development Support etc. + + * "git diff-tree" has been taught to take advantage of the + sparse-index feature. + + * Clang's sanitizer implementation seems to work better than GCC's. + (merge d88d727143 jk/ci-use-clang-for-sanitizer-jobs later to maint). + + * The object traversal using reachability bitmap done by + "pack-object" has been tweaked to take advantage of the fact that + using "boundary" commits as representative of all the uninteresting + ones can save quite a lot of object enumeration. + + * discover_git_directory() no longer touches the_repository. + + * "git worktree" learned to work better with sparse index feature. + + * When the external merge driver is killed by a signal, its output + should not be trusted as a resolution with conflicts that is + proposed by the driver, but the code did. + + * The set-up code for the get_revision() API now allows feeding + options like --all and --not in the --stdin mode. + + * Move functions that are not about pure string manipulation out of + strbuf.[ch] + + * "imap-send" codepaths got cleaned up to get rid of unused + parameters. + + * Enumerating refs in the packed-refs file, while excluding refs that + match certain patterns, has been optimized. + + * Mark-up unused parameters in the code so that we can eventually + enable -Wunused-parameter by default. + + * Instead of inventing a custom counter variables for debugging, + use existing trace2 facility in the fsync customization codepath. + + * "git branch --list --format=<format>" and friends are taught + a new "%(describe)" placeholder. + + * Clarify how to choose the starting point for a new topic in + developer guidance document. + + * The implementation of "get_sha1_hex()" that reads a hexadecimal + string that spells a full object name has been extended to cope + with any hash function used in the repository, but the "sha1" in + its name survived. Rename it to get_hash_hex(), a name that is + more consistent within its friends like get_hash_hex_algop(). + + * Command line parser fix, and a small parse-options API update. + + +Fixes since v2.41 +----------------- + + * "git tag" learned to leave the "$GIT_DIR/TAG_EDITMSG" file when the + command failed, so that the user can salvage what they typed. + (merge 08c12ec1d0 kh/keep-tag-editmsg-upon-failure later to maint). + + * The "-s" (silent, squelch) option of the "diff" family of commands + did not interact with other options that specify the output format + well. This has been cleaned up so that it will clear all the + formatting options given before. + (merge 9d484b92ed jc/diff-s-with-other-options later to maint). + + * Update documentation regarding Coccinelle patches. + (merge 3bd0097cfc gc/doc-cocci-updates later to maint). + + * Some atoms that can be used in "--format=<format>" for "git ls-tree" + were not supported by "git ls-files", even though they were relevant + in the context of the latter. + (merge 4d28c4f75f zh/ls-files-format-atoms later to maint). + + * Document more pseudo-refs and teach the command line completion + machinery to complete AUTO_MERGE. + (merge 982ff3a649 pb/complete-and-document-auto-merge-and-friends later to maint). + + * "git submodule" code trusted the data coming from the config (and + the in-tree .gitmodules file) too much without validating, leading + to NULL dereference if the user mucks with a repository (e.g. + submodule.<name>.url is removed). This has been corrected. + (merge fbc806acd1 tb/submodule-null-deref-fix later to maint). + + * The value of config.worktree is per-repository, but has been kept + in a singleton global variable per process. This has been OK as + most Git operations interacted with a single repository at a time, + but not right for operations like recursive "grep" that want to + access multiple repositories from a single process without forking. + + The global variable has been eliminated and made into a member in + the per-repository data structure. + (merge 3867f6d650 vd/worktree-config-is-per-repository later to maint). + + * "git [-c log.follow=true] log [--follow] ':(glob)f**'" used to barf. + (merge 8260bc5902 jk/log-follow-with-non-literal-pathspec later to maint). + + * Introduce a mechanism to disable replace refs globally and per + repository. + (merge 9c7d1b057f ds/disable-replace-refs later to maint). + + * "git cat-file --batch" and friends learned "-Z" that uses NUL + delimiter for both input and output. + (merge f79e18849b ps/cat-file-null-output later to maint). + + * The reimplemented "git add -i" did not honor color.ui configuration. + (merge 6f74648cea ds/add-i-color-configuration-fix later to maint). + + * Compilation fix for platforms without D_TYPE in struct dirent. + (merge 03bf92b9bf as/dtype-compilation-fix later to maint). + + * Suggest to refrain from using hex literals that are non-portable + when writing printf(1) format strings. + (merge f0b68f0546 jt/doc-use-octal-with-printf later to maint). + + * Simplify error message when run-command fails to start a command. + (merge 6d224ac286 rs/run-command-exec-error-on-noent later to maint). + + * Gracefully deal with a stale MIDX file that lists a packfile that + no longer exists. + (merge 06f3867865 tb/open-midx-bitmap-fallback later to maint). + + * Even when diff.ignoreSubmodules tells us to ignore submodule + changes, "git commit" with an index that already records changes to + submodules should include the submodule changes in the resulting + commit, but it did not. + (merge 5768478edc js/defeat-ignore-submodules-config-with-explicit-addition later to maint). + + * When "git commit --trailer=..." invokes the interpret-trailers + machinery, it knows what it feeds to interpret-trailers is a full + log message without any patch, but failed to express that by + passing the "--no-divider" option, which has been corrected. + (merge be3d654343 jk/commit-use-no-divider-with-interpret-trailers later to maint). + + * Avoid breakage of "git pack-objects --cruft" due to inconsistency + between the way the code enumerates packfiles in the repository. + (merge 73320e49ad tb/collect-pack-filenames-fix later to maint). + + * We create .pack and then .idx, we consider only packfiles that have + .idx usable (those with only .pack are not ready yet), so we should + remove .idx before removing .pack for consistency. + (merge 0dd1324a73 ds/remove-idx-before-pack later to maint). + + * Partially revert a sanity check that the rest of the config code + was not ready, to avoid triggering it in a corner case. + (merge a53f43f900 gc/config-partial-submodule-kvi-fix later to maint). + + * "git apply" punts when it is fed too large a patch input; the error + message it gives when it happens has been clarified. + (merge 42612e18d2 pw/apply-too-large later to maint). + + * During a cherry-pick or revert session that works on multiple + commits, "git status" did not give correct information, which has + been corrected. + (merge a096a889f4 jk/cherry-pick-revert-status later to maint). + + * A few places failed to differentiate the case where the index is + truly empty (nothing added) and we haven't yet read from the + on-disk index file, which have been corrected. + (merge 2ee045eea1 js/empty-index-fixes later to maint). + + * "git bugreport" tests did not test what it wanted to test, which + has been corrected. + (merge 1aa92b8500 ma/t0091-fixup later to maint). + + * Code snippets in a tutorial document no longer compiled after + recent header shuffling, which have been corrected. + (merge bbd7c7b7c0 vd/adjust-mfow-doc-to-updated-headers later to maint). + + * "git ls-files '(attr:X)D/'" that triggers the common prefix + optimization codepath failed to read from "D/.gitattributes", + which has been corrected. + (merge f4a8fde057 jc/pathspec-match-with-common-prefix later to maint). + + * "git fsck --no-progress" still spewed noise from the commit-graph + subsystem, which has been corrected. + (merge 9281cd07f0 tb/fsck-no-progress later to maint). + + * Various offset computation in the code that accesses the packfiles + and other data in the object layer has been hardened against + arithmetic overflow, especially on 32-bit systems. + (merge 9a25cad7e0 tb/object-access-overflow-protection later to maint). + + * Names of MinGW header files are spelled in mixed case in some + source files, but the build host can be using case sensitive + filesystem with header files with their name spelled in all + lowercase. + (merge 4a53d0d0bc mh/mingw-case-sensitive-build later to maint). + + * Update message mark-up for i18n in "git bundle". + (merge bbb6acd998 dk/bundle-i18n-more later to maint). + + * "git tag --list --points-at X" showed tags that directly refers to + object X, but did not list a tag that points at such a tag, which + has been corrected. + + * "./configure --with-expat=no" did not work as a way to refuse use + of the expat library on a system with the library installed, which + has been corrected. + (merge fb8f7269c2 ah/autoconf-fixes later to maint). + + * When the user edits "rebase -i" todo file so that it starts with a + "fixup", which would make it invalid, the command truncated the + rest of the file before giving an error and returning the control + back to the user. Stop truncating to make it easier to correct + such a malformed todo file. + (merge 9645a087c2 ah/sequencer-rewrite-todo-fix later to maint). + + * Rewrite the description of giving a custom command to the + submodule.<name>.update configuration variable. + (merge 7cebc5bd78 pv/doc-submodule-update-settings later to maint). + + * Adjust to OpenSSL 3+, which deprecates its SHA-1 functions based on + its traditional API, by using its EVP API instead. + (merge bda9c12073 ew/hash-with-openssl-evp later to maint). + + * Exclude "." from the set of characters to be removed from the + beginning and the end of the human-readable name. + (merge 1c04cb0744 bc/ident-dot-is-no-longer-crud-letter later to maint). + + * "git bisect visualize" stopped running "gitk" on Git for Windows + when the command was reimplemented in C around Git 2.34 timeframe. + This has been corrected. + (merge fff1594fa7 ma/locate-in-path-for-windows later to maint). + + * "git rebase -i" with a series of squash/fixup, when one of the + steps stopped in conflicts and ended up getting skipped, did not + handle the accumulated commit log messages, which has been + corrected. + (merge 6ce7afe163 pw/rebase-skip-commit-message-fix later to maint). + + * Adjust to newer Term::ReadLine to prevent it from breaking + the interactive prompt code in send-email. + (merge c016726c2d jk/send-email-with-new-readline later to maint). + + * Windows updates. + (merge 0050f8e401 ds/maintenance-on-windows-fix later to maint). + + * Correct use of lstat() that assumed a failing call would not + clobber the statbuf. + (merge 72695d8214 st/mv-lstat-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 51f9d2e563 sa/doc-ls-remote later to maint). + (merge c6d26a9dda jk/format-patch-message-id-unleak later to maint). + (merge f7e063f326 ps/fetch-cleanups later to maint). + (merge e4cf013468 tl/quote-problematic-arg-for-clarity later to maint). + (merge 20025fdfc7 tz/test-ssh-verifytime-fix later to maint). + (merge e48a21df65 tz/test-fix-pthreads-prereq later to maint). + (merge 68b51172e3 mh/commit-reach-get-reachable-plug-leak later to maint). + (merge aeee1408ce kh/use-default-notes-doc later to maint). + (merge 3b8724bce6 jc/test-modernization later to maint). + (merge 447a3b7331 jc/test-modernization-2 later to maint). + (merge d57fa7fc73 la/doc-interpret-trailers later to maint). + (merge 548afb0d9a la/docs-typofixes later to maint). + (merge 3744ffcbcd rs/doc-ls-tree-hex-literal later to maint). + (merge 6c26da8404 mh/credential-erase-improvements later to maint). + (merge 78e56cff69 tz/lib-gpg-prereq-fix later to maint). + (merge 80d32e84b5 rj/leakfixes later to maint). + (merge 0a868031ed pb/complete-diff-options later to maint). + (merge d4f28279ad jc/doc-hash-object-types later to maint). + (merge 1876a5ae15 ks/t4205-test-describe-with-abbrev-fix later to maint). + (merge 6e6a529b57 jk/fsck-indices-in-worktrees later to maint). + (merge 3e81b896f7 rs/packet-length-simplify later to maint). + (merge 4c9cb51fe7 mh/doc-credential-helpers later to maint). + (merge 3437f549dd jr/gitignore-doc-example-markup later to maint). + (merge 947ebd62a0 jc/am-parseopt-fix later to maint). + (merge e12cb98e1e jc/branch-parseopt-fix later to maint). + (merge d6f598e443 jc/gitignore-doc-pattern-markup later to maint). + (merge a2dad4868b jc/transport-parseopt-fix later to maint). + (merge 68cbb20e73 jc/parse-options-show-branch later to maint). + (merge 3821eb6c3d jc/parse-options-reset later to maint). + (merge c48af99a3e bb/trace2-comment-fix later to maint). + (merge c95ae3ff9c rs/describe-parseopt-fix later to maint). + (merge 36f76d2a25 rs/pack-objects-parseopt-fix later to maint). + (merge 30c8c55cbf jc/tree-walk-drop-base-offset later to maint). + (merge d089a06421 rs/bundle-parseopt-cleanup later to maint). + (merge 823839bda1 ew/sha256-gcrypt-leak-fixes later to maint). + (merge a5c01603b3 bc/ignore-clangd-cache later to maint). + (merge 12009a182b js/allow-t4000-to-be-indented-with-spaces later to maint). + (merge b3dcd24b8a jc/send-email-pre-process-fix later to maint). diff --git a/Documentation/RelNotes/2.42.1.txt b/Documentation/RelNotes/2.42.1.txt new file mode 100644 index 0000000..3d391b7 --- /dev/null +++ b/Documentation/RelNotes/2.42.1.txt @@ -0,0 +1,88 @@ +Git 2.42.1 Release Notes +======================== + +There is nothing exciting to see here. Relative to Git 2.42, this +release contains the fixes that have already been merged to the +'master' branch of the development towards Git 2.43 that has been +tagged as Git 2.43.0-rc0. + +Fixes since Git 2.42.0 +---------------------- + + * Tests that are known to pass with LSan are now marked as such. + + * Flaky "git p4" tests, as well as "git svn" tests, are now skipped + in the (rather expensive) sanitizer CI job. + + * Tests with LSan from time to time seem to emit harmless message + that makes our tests unnecessarily flaky; we work it around by + filtering the uninteresting output. + + * GitHub CI workflow has learned to trigger Coverity check. + + * Overly long label names used in the sequencer machinery are now + chopped to fit under filesystem limitation. + + * Scalar updates. + + * Tweak GitHub Actions CI so that pushing the same commit to multiple + branch tips at the same time will not waste building and testing + the same thing twice. + + * The commit-graph verification code that detects mixture of zero and + non-zero generation numbers has been updated. + + * "git diff -w --exit-code" with various options did not work + correctly, which is being addressed. + + * transfer.unpackLimit ought to be used as a fallback, but overrode + fetch.unpackLimit and receive.unpackLimit instead. + + * The use of API between two calls to require_clean_work_tree() from + the sequencer code has been cleaned up for consistency. + + * "git diff --no-such-option" and other corner cases around the exit + status of the "diff" command has been corrected. + + * "git for-each-ref --sort='contents:size'" sorts the refs according + to size numerically, giving a ref that points at a blob twelve-byte + (12) long before showing a blob hundred-byte (100) long. + + * Various fixes to the behavior of "rebase -i" when the command got + interrupted by conflicting changes. + + * References from description of the `--patch` option in various + manual pages have been simplified and improved. + + * "git grep -e A --no-or -e B" is accepted, even though the negation + of "or" did not mean anything, which has been tightened. + + * The completion script (in contrib/) has been taught to treat the + "-t" option to "git checkout" and "git switch" just like the + "--track" option, to complete remote-tracking branches. + + * "git diff --no-index -R <(one) <(two)" did not work correctly, + which has been corrected. + + * Update "git maintenance" timers' implementation based on systemd + timers to work with WSL. + + * "git diff --cached" codepath did not fill the necessary stat + information for a file when fsmonitor knows it is clean and ended + up behaving as if it is not clean, which has been corrected. + + * Clarify how "alias.foo = : git cmd ; aliased-command-string" should + be spelled with necessary whitespaces around punctuation marks to + work. + + * HTTP Header redaction code has been adjusted for a newer version of + cURL library that shows its traces differently from earlier + versions. + + * An error message given by "git send-email" when given a malformed + address did not give correct information, which has been corrected. + + * UBSan options were not propagated through the test framework to git + run via the httpd, unlike ASan options, which has been corrected. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.43.0.txt b/Documentation/RelNotes/2.43.0.txt new file mode 100644 index 0000000..e0e5b53 --- /dev/null +++ b/Documentation/RelNotes/2.43.0.txt @@ -0,0 +1,323 @@ +Git v2.43 Release Notes +======================= + +Backward Compatibility Notes + + * The "--rfc" option of "git format-patch" used to be a valid way to + override an earlier "--subject-prefix=<something>" on the command + line and replace it with "[RFC PATCH]", but from this release, it + merely prefixes the string "RFC " in front of the given subject + prefix. If you are negatively affected by this change, please use + "--subject-prefix=PATCH --rfc" as a replacement. + + * In Git 2.42, "git rev-list --stdin" learned to take non-revisions + (like "--not") from the standard input, but the way such a "--not" was + handled was quite confusing, which has been rethought. The updated + rule is that "--not" given from the command line only affects revs + given from the command line that comes but not revs read from the + standard input, and "--not" read from the standard input affects + revs given from the standard input and not revs given from the + command line. + +UI, Workflows & Features + + * A message written in olden time prevented a branch from getting + checked out, saying it is already checked out elsewhere. But these + days, we treat a branch that is being bisected or rebased just like + a branch that is checked out and protect it from getting modified + with the same codepath. The message has been rephrased to say that + the branch is "in use" to avoid confusion. + + * Hourly and other schedules of "git maintenance" jobs are randomly + distributed now. + + * "git cmd -h" learned to signal which options can be negated by + listing such options like "--[no-]opt". + + * The way authentication related data other than passwords (e.g., + oauth token and password expiration data) are stored in libsecret + keyrings has been rethought. + + * Update the libsecret and wincred credential helpers to correctly + match which credential to erase; they erased the wrong entry in + some cases. + + * Git GUI updates. + + * "git format-patch" learned a new "--description-file" option that + lets cover letter description to be fed; this can be used on + detached HEAD where there is no branch description available, and + also can override the branch description if there is one. + + * Use of the "--max-pack-size" option to allow multiple packfiles to + be created is now supported even when we are sending unreachable + objects to cruft packs. + + * "git format-patch --rfc --subject-prefix=<foo>" used to ignore the + "--subject-prefix" option and used "[RFC PATCH]"; now we will add + "RFC" prefix to whatever subject prefix is specified. + + * "git log --format" has been taught the %(decorate) placeholder for + further customization over what the "--decorate" option offers. + + * The default log message created by "git revert", when reverting a + commit that records a revert, has been tweaked, to encourage people + to describe complex "revert of revert of revert" situations better in + their own words. + + * The command-line completion support (in contrib/) learned to + complete "git commit --trailer=" for possible trailer keys. + + * "git update-index" learned the "--show-index-version" option to + inspect the index format version used by the on-disk index file. + + * "git diff" learned the "diff.statNameWidth" configuration variable, + to give the default width for the name part in the "--stat" output. + + * "git range-diff --notes=foo" compared "log --notes=foo --notes" of + the two ranges, instead of using just the specified notes tree, + which has been corrected to use only the specified notes tree. + + * The command line completion script (in contrib/) can be told to + complete aliases by including ": git <cmd> ;" in the alias to tell + it that the alias should be completed in a similar way to how "git + <cmd>" is completed. The parsing code for the alias has been + loosened to allow ';' without an extra space before it. + + * "git for-each-ref" and friends learned to apply mailmap to + authorname and other fields in a more flexible way than using + separate placeholder letters like %a[eElL] every time we want to + come up with small variants. + + * "git repack" machinery learned to pay attention to the "--filter=" + option. + + * "git repack" learned the "--max-cruft-size" option to prevent cruft + packs from growing without bounds. + + * "git merge-tree" learned to take strategy backend specific options + via the "-X" option, like "git merge" does. + + * "git log" and friends learned the "--dd" option that is a + short-hand for "--diff-merges=first-parent -p". + + * The attribute subsystem learned to honor the "attr.tree" + configuration variable that specifies which tree to read the + .gitattributes files from. + + * "git merge-file" learns a mode to read three variants of the + contents to be merged from blob objects. + + +Performance, Internal Implementation, Development Support etc. + + * "git check-attr" has been taught to work better with sparse-index. + + * It may be tempting to leave the help text NULL for a command line + option that is either hidden or too obvious, but "git subcmd -h" + and "git subcmd --help-all" would have segfaulted if done so. Now + the help text is truly optional. + + * Tests that are known to pass with LSan are now marked as such. + + * Flaky "git p4" tests, as well as "git svn" tests, are now skipped + in the (rather expensive) sanitizer CI job. + + * Tests with LSan from time to time seem to emit harmless messages + that make our tests unnecessarily flaky; we work around it by + filtering the uninteresting output. + + * Unused parameters to functions are marked as such, and/or removed, + in order to bring us closer to "-Wunused-parameter" clean. + + * The code to keep track of existing packs in the repository while + repacking has been refactored. + + * The "streaming" interface used for bulk-checkin codepath has been + narrowed to take only blob objects for now, with no real loss of + functionality. + + * GitHub CI workflow has learned to trigger Coverity check. + + * Test coverage for trailers has been improved. + + * The code to iterate over loose references has been optimized to + reduce the number of lstat() system calls. + + * The codepaths that read "chunk" formatted files have been corrected + to pay attention to the chunk size and notice broken files. + + * Replace macos-12 used at GitHub CI with macos-13. + (merge 682a868f67 js/ci-use-macos-13 later to maint). + + +Fixes since v2.42 +----------------- + + * Overly long label names used in the sequencer machinery are now + chopped to fit under filesystem limitation. + + * Scalar updates. + + * Tweak GitHub Actions CI so that pushing the same commit to multiple + branch tips at the same time will not waste building and testing + the same thing twice. + + * The commit-graph verification code that detects a mixture of zero and + non-zero generation numbers has been updated. + + * "git diff -w --exit-code" with various options did not work + correctly, which has been corrected. + + * The "transfer.unpackLimit" configuration variable ought to be used + as a fallback, but overrode the more specific "fetch.unpackLimit" + and "receive.unpackLimit" configuration variables by mistake, which + has been corrected. + + * The use of API between two calls to require_clean_work_tree() from + the sequencer code has been cleaned up for consistency. + + * "git diff --no-such-option" and other corner cases around the exit + status of the "diff" command have been corrected. + + * "git for-each-ref --sort='contents:size'" sorted the refs according + to size numerically, giving a ref that points at a blob twelve-byte + (12) long before showing a blob hundred-byte (100) long, which has + been corrected. + + * We now limit the depth of the tree objects and maximum length of + pathnames recorded in tree objects. + (merge 4d5693ba05 jk/tree-name-and-depth-limit later to maint). + + * Various fixes to the behavior of "rebase -i", when the command got + interrupted by conflicting changes, have been made. + + * References from a description of the `--patch` option in various + manual pages have been simplified and improved. + + * "git grep -e A --no-or -e B" is accepted, even though the negation + of the "--or" option did not mean anything, which has been tightened. + + * The completion script (in contrib/) has been taught to treat the + "-t" option to "git checkout" and "git switch" just like the + "--track" option, to complete remote-tracking branches. + + * "git diff --no-index -R <(one) <(two)" did not work correctly, + which has been corrected. + + * "git maintenance" timers' implementation has been updated, based on + systemd timers, to work with WSL. + + * "git diff --cached" codepath did not fill the necessary stat + information for a file when fsmonitor knows it is clean and ended + up behaving as if it were not clean, which has been corrected. + + * How "alias.foo = : git cmd ; aliased-command-string" should be + spelled with necessary whitespace around punctuation marks to work + has been more clearly documented (but this will be moot with newer + versions of Git where the parsing rules have been improved). + + * HTTP Header redaction code has been adjusted for a newer version of + cURL library that shows its traces differently from earlier + versions. + + * An error message given by "git send-email", when given a malformed + address, did not show the offending address, which has been corrected. + + * UBSan options were not propagated through the test framework to git + run via the httpd, unlike ASan options, which has been corrected. + + * "checkout --merge -- path" and "update-index --unresolve path" did + not resurrect conflicted state that was resolved to remove path, + but now they do. + (merge 5bdedac3c7 jc/unresolve-removal later to maint). + + * The display width table for unicode characters has been updated for + Unicode 15.1 + (merge 872976c37e bb/unicode-width-table-15 later to maint). + + * Update mailmap entry for Derrick. + (merge 6e5457d8c7 ds/mailmap-entry-update later to maint). + + * In the ".gitmodules" files, submodules are keyed by their names, + and the path to the submodule whose name is $name is specified by + the submodule.$name.path variable. There were a few codepaths that + mixed the name and path up when consulting the submodule database, + which have been corrected. It took long for these bugs to be found + as the name of a submodule initially is the same as its path, and + the problem does not surface until it is moved to a different path, + which apparently happens very rarely. + + * "git diff --merge-base X other args..." insisted that X must be a + commit and errored out when given an annotated tag that peels to a + commit, but we only need it to be a committish. This has been + corrected. + (merge 4adceb5a29 ar/diff-index-merge-base-fix later to maint). + + * "git merge-tree" used to segfault when the "--attr-source" + option is used, which has been corrected. + (merge e95bafc52f jc/merge-ort-attr-index-fix later to maint). + + * Unlike "git log --pretty=%D", "git log --pretty="%(decorate)" did + not auto-initialize the decoration subsystem, which has been + corrected. + + * Feeding "git stash store" with a random commit that was not created + by "git stash create" now errors out. + (merge d9b6634589 jc/fail-stash-to-store-non-stash later to maint). + + * The index file has room only for the lower 32-bit of the file size in + the cached stat information, which means cached stat information + will have 0 in its sd_size member for a file whose size is a multiple + of 4GiB. This is mistaken for a racily clean path. Avoid it by + storing a bogus sd_size value instead for such files. + (merge 5143ac07b1 bc/racy-4gb-files later to maint). + + * "git p4" tried to store symlinks to LFS when told, but has been + fixed not to do so, because it does not make sense. + (merge 10c89a02b0 mm/p4-symlink-with-lfs later to maint). + + * The codepath to handle recipient addresses `git send-email + --compose` learns from the user was completely broken, which has + been corrected. + (merge 3ec6167567 jk/send-email-fix-addresses-from-composed-messages later to maint). + + * "cd sub && git grep -f patterns" tried to read "patterns" file at + the top level of the working tree; it has been corrected to read + "sub/patterns" instead. + + * "git reflog expire --single-worktree" has been broken for the past + 20 months or so, which has been corrected. + + * "git send-email" did not have certain pieces of data computed yet + when it tried to validate the outgoing messages and its recipient + addresses, which has been sorted out. + + * "git bugreport" learned to complain when it received a command line + argument that it will not use. + + * The codepath to traverse the commit-graph learned to notice that a + commit is missing (e.g., corrupt repository lost an object), even + though it knows something about the commit (like its parents) from + what is in commit-graph. + (merge 7a5d604443 ps/do-not-trust-commit-graph-blindly-for-existence later to maint). + + * "git rev-list --missing" did not work for missing commit objects, + which has been corrected. + + * "git rev-list --unpacked --objects" failed to exclude packed + non-commit objects, which has been corrected. + (merge 7b3c8e9f38 tb/rev-list-unpacked-fix later to maint). + + * "To dereference" and "to peel" were sometimes used in in-code + comments and documentation but without description in the glossary. + (merge 893dce2ffb vd/glossary-dereference-peel later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge c2c349a15c xz/commit-title-soft-limit-doc later to maint). + (merge 1bd809938a tb/format-pack-doc-update later to maint). + (merge 8f81532599 an/clang-format-typofix later to maint). + (merge 3ca86adc2d la/strvec-header-fix later to maint). + (merge 6789275d37 jc/test-i18ngrep later to maint). + (merge 9972cd6004 ps/leakfixes later to maint). + (merge 46edab516b tz/send-email-helpfix later to maint). 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.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.45.0.txt b/Documentation/RelNotes/2.45.0.txt new file mode 100644 index 0000000..039cce7 --- /dev/null +++ b/Documentation/RelNotes/2.45.0.txt @@ -0,0 +1,410 @@ +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 is a useful + addition to be 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. + + +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-brakets> 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. + + * The code to iterate over refs with the reftable backend has seen + some optimization. + + * Uses of xwrite() helper have been audited and updated for better + error checking and simpler code. + + * 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. + + +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 trialing 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 has 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 message can fall into an + endless loop, which has been corrected. + (merge 2541cba2d6 fs/find-end-of-log-message-fix later to maint). + + * Mark-ups used in the documentation has been improved for + 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). + + * 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). diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt new file mode 100644 index 0000000..515d470 --- /dev/null +++ b/Documentation/ReviewingGuidelines.txt @@ -0,0 +1,162 @@ +Reviewing Patches in the Git Project +==================================== + +Introduction +------------ +The Git development community is a widely distributed, diverse, ever-changing +group of individuals. Asynchronous communication via the Git mailing list poses +unique challenges when reviewing or discussing patches. This document contains +some guiding principles and helpful tools you can use to make your reviews both +more efficient for yourself and more effective for other contributors. + +Note that none of the recommendations here are binding or in any way a +requirement of participation in the Git community. They are provided as a +resource to supplement your skills as a contributor. + +Principles +---------- + +Selecting patch(es) to review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you are looking for a patch series in need of review, start by checking +the latest "What's cooking in git.git" email +(https://lore.kernel.org/git/xmqqilm1yp3m.fsf@gitster.g/[example]). The "What's +cooking" emails & replies can be found using the query `s:"What's cooking"` on +the https://lore.kernel.org/git/[`lore.kernel.org` mailing list archive]; +alternatively, you can find the contents of the "What's cooking" email tracked +in `whats-cooking.txt` on the `todo` branch of Git. Topics tagged with "Needs +review" and those in the "[New Topics]" section are typically those that would +benefit the most from additional review. + +Patches can also be searched manually in the mailing list archive using a query +like `s:"PATCH" -s:"Re:"`. You can browse these results for topics relevant to +your expertise or interest. + +If you've already contributed to Git, you may also be CC'd in another +contributor's patch series. These are topics where the author feels that your +attention is warranted. This may be because their patch changes something you +wrote previously (making you a good judge of whether the new approach does or +doesn't work), or because you have the expertise to provide an exceptionally +helpful review. There is no requirement to review these patches but, in the +spirit of open source collaboration, you should strongly consider doing so. + +Reviewing patches +~~~~~~~~~~~~~~~~~ +While every contributor takes their own approach to reviewing patches, here are +some general pieces of advice to make your reviews as clear and helpful as +possible. The advice is broken into two rough categories: high-level reviewing +guidance, and concrete tips for interacting with patches on the mailing list. + +==== High-level guidance +- Remember to review the content of commit messages for correctness and clarity, + in addition to the code change in the patch's diff. The commit message of a + patch should accurately and fully explain the code change being made in the + diff. + +- Reviewing test coverage is an important - but easy to overlook - component of + reviews. A patch's changes may be covered by existing tests, or new tests may + be introduced to exercise new behavior. Checking out a patch or series locally + allows you to manually mutate lines of new & existing tests to verify expected + pass/fail behavior. You can use this information to verify proper coverage or + to suggest additional tests the author could add. + +- When providing a recommendation, be as clear as possible about whether you + consider it "blocking" (the code would be broken or otherwise made worse if an + issue isn't fixed) or "non-blocking" (the patch could be made better by taking + the recommendation, but acceptance of the series does not require it). + Non-blocking recommendations can be particularly ambiguous when they are + related to - but outside the scope of - a series ("nice-to-have"s), or when + they represent only stylistic differences between the author and reviewer. + +- When commenting on an issue, try to include suggestions for how the author + could fix it. This not only helps the author to understand and fix the issue, + it also deepens and improves your understanding of the topic. + +- Reviews do not need to exclusively point out problems. Feel free to "think out + loud" in your review: describe how you read & understood a complex section of + a patch, ask a question about something that confused you, point out something + you found exceptionally well-written, etc. In particular, uplifting feedback + goes a long way towards encouraging contributors to participate more actively + in the Git community. + +==== Performing your review +- Provide your review comments per-patch in a plaintext "Reply-All" email to the + relevant patch. Comments should be made inline, immediately below the relevant + section(s). + +- You may find that the limited context provided in the patch diff is sometimes + insufficient for a thorough review. In such cases, you can review patches in + your local tree by either applying patches with linkgit:git-am[1] or checking + out the associated branch from https://github.com/gitster/git once the series + is tracked there. + +- Large, complicated patch diffs are sometimes unavoidable, such as when they + refactor existing code. If you find such a patch difficult to parse, try + reviewing the diff produced with the `--color-moved` and/or + `--ignore-space-change` options. + +- If a patch is long, you are encouraged to delete parts of it that are + unrelated to your review from the email reply. Make sure to leave enough + context for readers to understand your comments! + +- If you cannot complete a full review of a series all at once, consider letting + the author know (on- or off-list) if/when you plan to review the rest of the + series. + +Completing a review +~~~~~~~~~~~~~~~~~~~ +Once each patch of a series is reviewed, the author (and/or other contributors) +may discuss the review(s). This may result in no changes being applied, or the +author will send a new version of their patch(es). + +After a series is rerolled in response to your or others' review, make sure to +re-review the updates. If you are happy with the state of the patch series, +explicitly indicate your approval (typically with a reply to the latest +version's cover letter). Optionally, you can let the author know that they can +add a "Reviewed-by: <you>" trailer if they resubmit the reviewed patch verbatim +in a later iteration of the series. + +Finally, subsequent "What's cooking" emails may explicitly ask whether a +reviewed topic is ready for merging to the `next` branch (typically phrased +"Will merge to \'next\'?"). You can help the maintainer and author by responding +with a short description of the state of your (and others', if applicable) +review, including the links to the relevant thread(s). + +Terminology +----------- +nit: :: + Denotes a small issue that should be fixed, such as a typographical error + or misalignment of conditions in an `if()` statement. + +aside: :: +optional: :: +non-blocking: :: + Indicates to the reader that the following comment should not block the + acceptance of the patch or series. These are typically recommendations + related to code organization & style, or musings about topics related to + the patch in question, but beyond its scope. + +s/<before>/<after>/:: + Shorthand for "you wrote <before>, but I think you meant <after>," usually + for misspellings or other typographical errors. The syntax is a reference + to "substitute" command commonly found in Unix tools such as `ed`, `sed`, + `vim`, and `perl`. + +cover letter:: + The "Patch 0" of a multi-patch series. This email describes the + high-level intent and structure of the patch series to readers on the + Git mailing list. It is also where the changelog notes and range-diff of + subsequent versions are provided by the author. ++ +On single-patch submissions, cover letter content is typically not sent as a +separate email. Instead, it is inserted between the end of the patch's commit +message (after the `---`) and the beginning of the diff. + +#leftoverbits:: + Used by either an author or a reviewer to describe features or suggested + changes that are out-of-scope of a given patch or series, but are relevant + to the topic for the sake of discussion. + +See Also +-------- +link:MyFirstContribution.html[MyFirstContribution] diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5bd795e..c647c7e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,45 +3,101 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. -[[base-branch]] -=== Decide what to base your work on. - -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on other topics that are in `next`, but not in - `master`, fork a branch from the tip of `master`, merge these topics - to the branch, and work on that branch. You can remind yourself of - how you prepared the base with `git log --first-parent master..`. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `seen` privately and - send out patches only for discussion. Once your new feature starts - to stabilize, you would have to rebase it (see the "depends on other - topics" above). - -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - -To find the tip of a topic branch, run `git log --first-parent -master..seen` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. +[[choose-starting-point]] +=== Choose a starting point. + +As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch). + +There are several important branches to be aware of. Namely, there are +four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + +The branches lower on the list are typically descendants of the ones +that come before it. For example, `maint` is an "older" branch than +`master` because `master` usually has patches (commits) on top of +`maint`. + +There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What's cooking in +git.git" announcements. To find the tip of a topic branch, run `git log +--first-parent master..seen` and look for the merge commit. The second +parent of this commit is the tip of the topic branch. + +There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +linkgit:gitworkflows[7]). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +latest HEAD commit of `maint` or `master` based on the following cases: + +* If you are fixing bugs in the released version, use `maint` as the + starting point (which may mean you have to fix things without using + new API features on the cutting edge that recently appeared in + `master` but were not available in the released version). + +* Otherwise (such as if you are adding new features) use `master`. + + +NOTE: In exceptional cases, a bug that was introduced in an old +version may have to be fixed for users of releases that are much older +than the recent releases. `git describe --contains X` may describe +`X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the +bug, and the bug may be so high-impact that we may need to issue a new +maintenance release for Git 2.30.x series, when "Git 2.41.0" is the +current release. In such a case, you may want to use the tip of the +maintenance branch for the 2.30.x series, which may be available in the +`maint-2.30` branch in https://github.com/gitster/git[the maintainer's +"broken out" repo]. + +This also means that `next` or `seen` are inappropriate starting points +for your work, if you want your work to have a realistic chance of +graduating to `master`. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both `next` and `seen` are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of `next` cannot be merged to `master` without +dragging in all the other topics in `next`, some of which may not be +ready. + +For example, if you are making tree-wide changes, while somebody else is +also making their own tree-wide changes, your work may have severe +overlap with the other person's work. This situation may tempt you to +use `next` as your starting point (because it would have the other +person's work included in it), but doing so would mean you'll not only +depend on the other person's work, but all the other random things from +other contributors that are already integrated into `next`. And as soon +as `next` is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer. + +Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in `next` but not in +`master`, you may want to create your own custom base-branch by forking +`master` and merging the required topic branches into it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work. + +Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below). [[separate-commits]] === Make separate commits for logically separate changes. @@ -153,7 +209,9 @@ files you are modifying to see the current conventions. [[summary-section]] The title sentence after the "area:" prefix omits the full stop at the -end, and its first word is not capitalized unless there is a reason to +end, and its first word is not capitalized (the omission +of capitalization applies only to the word after the "area:" +prefix of the title) unless there is a reason to capitalize it other than because it is the first word in the sentence. E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt: improve...", not "githooks.txt: Improve...". But "refs: HEAD is also @@ -208,7 +266,7 @@ date)", like this: noticed that ... .... -The "Copy commit summary" command of gitk can be used to obtain this +The "Copy commit reference" command of gitk can be used to obtain this format (with the subject enclosed in a pair of double-quotes), or this invocation of `git show`: @@ -297,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. @@ -315,10 +385,13 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, -and unless it targets the `master` branch (which is the default), -mark your patches as such. +sending out, please make sure it cleanly applies to the starting point you +have chosen in the "Choose a starting point" section. + +NOTE: From the perspective of those reviewing your patch, the `master` +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. [[send-patches]] @@ -332,8 +405,8 @@ mailing list{security-ml}, instead of the public mailing list. Learn to use format-patch and send-email if possible. These commands are optimized for the workflow of sending patches, avoiding many ways -your existing e-mail client that is optimized for "multipart/*" mime -type e-mails to corrupt and render your patches unusable. +your existing e-mail client (often optimized for "multipart/*" MIME +type e-mails) might render your patches unusable. People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for @@ -386,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 @@ -454,8 +539,8 @@ repositories. git://git.ozlabs.org/~paulus/gitk - Those who are interested in improve gitk can volunteer to help Paul - in maintaining it cf. <YntxL/fTplFm8lr6@cleo>. + Those who are interested in improving gitk can volunteer to help Paul + maintain it, cf. <YntxL/fTplFm8lr6@cleo>. - `po/` comes from the localization coordinator, Jiang Xin: @@ -495,7 +580,7 @@ help you find out who they are. In any time between the (2)-(3) cycle, the maintainer may pick it up from the list and queue it to `seen`, in order to make it easier for -people play with it without having to pick up and apply the patch to +people to play with it without having to pick up and apply the patch to their trees themselves. [[patch-status]] @@ -509,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]] @@ -529,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. @@ -541,7 +627,7 @@ trigger a new CI build to ensure all tests pass. [[mua]] == MUA specific hints -Some of patches I receive or pick up from the list share common +Some of the patches I receive or pick up from the list share common patterns of breakage. Please make sure your MUA is set up properly not to corrupt whitespaces. @@ -625,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/ToolsForGit.txt b/Documentation/ToolsForGit.txt index 5060d0d..ae7690b 100644 --- a/Documentation/ToolsForGit.txt +++ b/Documentation/ToolsForGit.txt @@ -5,7 +5,7 @@ Tools for developing Git [[summary]] == Summary -This document gathers tips, scripts and configuration file to help people +This document gathers tips, scripts, and configuration files to help people working on Git's codebase use their favorite tools while following Git's coding style. @@ -32,7 +32,7 @@ information on using the script. This is adapted from Linux's suggestion in its CodingStyle document: -- To follow rules of the CodingGuideline, it's useful to put the following in +- To follow the rules in CodingGuidelines, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: ---- ;; note the first part is useful for C editing, too diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 3e4c139..60f76f4 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -51,25 +51,6 @@ ifdef::doctype-manpage[] endif::doctype-manpage[] endif::backend-docbook[] -ifdef::doctype-manpage[] -ifdef::backend-docbook[] -[header] -template::[header-declarations] -<refentry> -<refmeta> -<refentrytitle>{mantitle}</refentrytitle> -<manvolnum>{manvolnum}</manvolnum> -<refmiscinfo class="source">{mansource}</refmiscinfo> -<refmiscinfo class="version">{manversion}</refmiscinfo> -<refmiscinfo class="manual">{manmanual}</refmiscinfo> -</refmeta> -<refnamediv> - <refname>{manname}</refname> - <refpurpose>{manpurpose}</refpurpose> -</refnamediv> -endif::backend-docbook[] -endif::doctype-manpage[] - ifdef::backend-xhtml11[] [attributes] git-relative-html-prefix= diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 9a66353..552dcc6 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -64,11 +64,9 @@ include::line-range-format.txt[] manual page. --contents <file>:: - When <rev> is not specified, the command annotates the - changes starting backwards from the working tree copy. - This flag makes the command pretend as if the working - tree copy has the contents of the named file (specify - `-` to make the command read from the standard input). + Annotate using the contents from the named file, starting from <rev> + if it is specified, and HEAD otherwise. You may specify '-' to make + the command read from the standard input for the file contents. --date <format>:: Specifies the format used to output dates. If --date is not diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl index ba4205e..1b3ac8f 100755 --- a/Documentation/build-docdep.perl +++ b/Documentation/build-docdep.perl @@ -38,9 +38,10 @@ while ($changed) { } } -while (my ($text, $included) = each %include) { +foreach my $text (sort keys %include) { + my $included = $include{$text}; if (! exists $included{$text} && (my $base = $text) =~ s/\.txt$//) { - print "$base.html $base.xml : ", join(" ", keys %$included), "\n"; + print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n"; } } diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index af5da45..755a110 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -10,7 +10,7 @@ sub format_one { $state = 0; open I, '<', "$name.txt" or die "No such file $name.txt"; while (<I>) { - if (/^git[a-z0-9-]*\(([0-9])\)$/) { + if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) { $mansection = $1; next; } diff --git a/Documentation/config.txt b/Documentation/config.txt index e284b04..70b448b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -11,7 +11,7 @@ file. The file `/etc/gitconfig` can be used to store a system-wide default configuration. The configuration variables are used by both the Git plumbing -and the porcelains. The variables are divided into sections, wherein +and the porcelain commands. The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive, allow only alphanumeric @@ -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) @@ -103,7 +105,7 @@ was found. See below for examples. Conditional includes ~~~~~~~~~~~~~~~~~~~~ -You can include a config file from another conditionally by setting a +You can conditionally include a config file from another by setting an `includeIf.<condition>.path` variable to the name of the file to be included. @@ -118,7 +120,7 @@ are: pattern, the include condition is met. + The .git location may be auto-discovered, or come from `$GIT_DIR` -environment variable. If the repository is auto discovered via a .git +environment variable. If the repository is auto-discovered via a .git file (e.g. from submodules, or a linked worktree), the .git location would be the final location where the .git directory is, not where the .git file is. @@ -182,7 +184,7 @@ included, Git breaks the cycle by prohibiting these files from affecting the resolution of these conditions (thus, prohibiting them from declaring remote URLs). + -As for the naming of this keyword, it is for forwards compatibiliy with +As for the naming of this keyword, it is for forwards compatibility with a naming scheme that supports more variable-based include conditions, but currently Git only supports the exact keyword described above. @@ -369,24 +371,26 @@ 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/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[] include::config/browser.txt[] +include::config/bundle.txt[] + include::config/checkout.txt[] include::config/clean.txt[] @@ -401,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[] @@ -417,22 +423,24 @@ 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[] + include::config/gc.txt[] 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[] @@ -445,6 +453,8 @@ include::config/i18n.txt[] include::config/imap.txt[] +include::config/includeif.txt[] + include::config/index.txt[] include::config/init.txt[] @@ -495,6 +505,8 @@ include::config/repack.txt[] include::config/rerere.txt[] +include::config/revert.txt[] + include::config/safe.txt[] include::config/sendemail.txt[] @@ -509,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/add.txt b/Documentation/config/add.txt index 3e859f3..e0354ce 100644 --- a/Documentation/config/add.txt +++ b/Documentation/config/add.txt @@ -7,6 +7,7 @@ add.ignore-errors (deprecated):: variables. add.interactive.useBuiltin:: - Set to `false` to fall back to the original Perl implementation of - the interactive version of linkgit:git-add[1] instead of the built-in - version. Is `true` by default. + Unused configuration variable. Used in Git versions v2.25.0 to + v2.36.0 to enable the built-in version of linkgit:git-add[1]'s + interactive mode, which then became the default in Git + versions v2.37.0 to v2.39.0. diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index a00d010..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 fetch refspec for multiple remotes map 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. @@ -63,77 +126,32 @@ advice.*:: the template shown when writing commit messages in linkgit:git-commit[1], and in the help message shown by linkgit:git-switch[1] or - linkgit:git-checkout[1] when switching branch. + 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 detach 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 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. + waitingForEditor:: + Shown when Git is waiting for editor input. Relevant + when e.g. the editor is not launched inside the terminal. + worktreeAddOrphan:: + 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/alias.txt b/Documentation/config/alias.txt index f1ca739..01df96f 100644 --- a/Documentation/config/alias.txt +++ b/Documentation/config/alias.txt @@ -4,7 +4,7 @@ alias.*:: `git last` is equivalent to `git cat-file commit HEAD`. To avoid confusion and troubles with script usage, aliases that hide existing Git commands are ignored. Arguments are split by - spaces, the usual shell quoting and escaping is supported. + spaces, the usual shell quoting and escaping are supported. A quote pair or a backslash can be used to quote them. + Note that the first word of an alias does not necessarily have to be a diff --git a/Documentation/config/apply.txt b/Documentation/config/apply.txt index 8fb8ef7..f9908e2 100644 --- a/Documentation/config/apply.txt +++ b/Documentation/config/apply.txt @@ -2,10 +2,10 @@ apply.ignoreWhitespace:: When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the `--ignore-space-change` option. - When set to one of: no, none, never, false tells 'git apply' to + When set to one of: no, none, never, false, it tells 'git apply' to respect all whitespace differences. See linkgit:git-apply[1]. apply.whitespace:: - Tells 'git apply' how to handle whitespaces, in the same way + Tells 'git apply' how to handle whitespace, in the same way as the `--whitespace` option. See linkgit:git-apply[1]. diff --git a/Documentation/config/attr.txt b/Documentation/config/attr.txt new file mode 100644 index 0000000..1a482d6 --- /dev/null +++ b/Documentation/config/attr.txt @@ -0,0 +1,7 @@ +attr.tree:: + A reference to a tree in the repository from which to read attributes, + instead of the `.gitattributes` file in the working tree. In a bare + repository, this defaults to `HEAD:.gitattributes`. If the value does + not resolve to a valid tree object, an empty tree is used instead. + When the `GIT_ATTR_SOURCE` environment variable or `--attr-source` + command line option are used, this configuration variable has no effect. diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index 445341a..432b9cd 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -36,7 +36,7 @@ branch.sort:: branch.<name>.remote:: When on branch <name>, it tells 'git fetch' and 'git push' - which remote to fetch from/push to. The remote to push to + which remote to fetch from or push to. The remote to push to may be overridden with `remote.pushDefault` (for all branches). The remote to push to, for the current branch, may be further overridden by `branch.<name>.pushRemote`. If no remote is @@ -64,7 +64,7 @@ branch.<name>.merge:: handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by "branch.<name>.remote". - The merge information is used by 'git pull' (which at first calls + The merge information is used by 'git pull' (which first calls 'git fetch') to lookup the default branch for merging. Without this option, 'git pull' defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. @@ -99,5 +99,5 @@ for details). branch.<name>.description:: Branch description, can be edited with `git branch --edit-description`. Branch description is - automatically added in the format-patch cover letter or + automatically added to the format-patch cover letter or request-pull summary. diff --git a/Documentation/config/bundle.txt b/Documentation/config/bundle.txt new file mode 100644 index 0000000..3faae386 --- /dev/null +++ b/Documentation/config/bundle.txt @@ -0,0 +1,31 @@ +bundle.*:: + The `bundle.*` keys may appear in a bundle list file found via the + `git clone --bundle-uri` option. These keys currently have no effect + if placed in a repository config file, though this will change in the + future. See link:technical/bundle-uri.html[the bundle URI design + document] for more details. + +bundle.version:: + This integer value advertises the version of the bundle list format + used by the bundle list. Currently, the only accepted value is `1`. + +bundle.mode:: + This string value should be either `all` or `any`. This value describes + whether all of the advertised bundles are required to unbundle a + complete understanding of the bundled information (`all`) or if any one + of the listed bundle URIs is sufficient (`any`). + +bundle.heuristic:: + If this string-valued key exists, then the bundle list is designed to + work well with incremental `git fetch` commands. The heuristic signals + that there are additional keys available for each bundle that help + determine which subset of bundles the client should download. The + only value currently understood is `creationToken`. + +bundle.<id>.*:: + The `bundle.<id>.*` keys are used to describe a single item in the + bundle list, grouped under `<id>` for identification purposes. + +bundle.<id>.uri:: + This string value defines the URI by which Git can reach the contents + of this `<id>`. This URI may be a bundle file or another bundle list. diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt index bfbca90..a323022 100644 --- a/Documentation/config/checkout.txt +++ b/Documentation/config/checkout.txt @@ -30,7 +30,7 @@ checkout.workers:: all commands that perform checkout. E.g. checkout, clone, reset, sparse-checkout, etc. + -Note: parallel checkout usually delivers better performance for repositories +Note: Parallel checkout usually delivers better performance for repositories located on SSDs or over NFS. For repositories on spinning disks and/or machines with a small number of cores, the default sequential checkout often performs better. The size and compression level of a repository might also influence how @@ -39,6 +39,6 @@ well the parallel version performs. checkout.thresholdForParallelism:: When running parallel checkout with a small number of files, the cost of subprocess spawning and inter-process communication might outweigh - the parallelization gains. This setting allows to define the minimum + the parallelization gains. This setting allows you to define the minimum number of files for which parallel checkout should be attempted. The default is 100. diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.txt index a807c92..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 26f4fb1..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:: - Reject to clone a repository if it is a shallow one, can be overridden by - passing option `--reject-shallow` in command line. See linkgit:git-clone[1] +`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. +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/color.txt b/Documentation/config/color.txt index 1795b2d..2f2275a 100644 --- a/Documentation/config/color.txt +++ b/Documentation/config/color.txt @@ -106,7 +106,7 @@ color.grep.<slot>:: matching text in context lines `matchSelected`;; matching text in selected lines. Also, used to customize the following - linkgit:git-log[1] subcommands: `--grep`, `--author` and `--committer`. + linkgit:git-log[1] subcommands: `--grep`, `--author`, and `--committer`. `selected`;; non-matching text in selected lines. Also, used to customize the following linkgit:git-log[1] subcommands: `--grep`, `--author` and diff --git a/Documentation/config/column.txt b/Documentation/config/column.txt index 76aa2f2..01e4198 100644 --- a/Documentation/config/column.txt +++ b/Documentation/config/column.txt @@ -43,7 +43,7 @@ column.branch:: See `column.ui` for details. column.clean:: - Specify the layout when list items in `git clean -i`, which always + Specify the layout when listing items in `git clean -i`, which always shows files and directories in columns. See `column.ui` for details. column.status:: @@ -51,5 +51,5 @@ column.status:: See `column.ui` for details. column.tag:: - Specify whether to output tag listing in `git tag` in columns. + Specify whether to output tag listings in `git tag` in columns. See `column.ui` for details. diff --git a/Documentation/config/commit.txt b/Documentation/config/commit.txt index 2c95573..62f0d92 100644 --- a/Documentation/config/commit.txt +++ b/Documentation/config/commit.txt @@ -2,7 +2,7 @@ commit.cleanup:: This setting overrides the default of the `--cleanup` option in `git commit`. See linkgit:git-commit[1] for details. Changing the default can be useful when you always want to keep lines that begin - with comment character `#` in your log message, in which case you + with the comment character `#` in your log message, in which case you would do `git config commit.cleanup whitespace` (note that you will have to remove the help lines that begin with `#` in the commit log template yourself, if you do this). @@ -25,5 +25,5 @@ commit.template:: new commit messages. commit.verbose:: - A boolean or int to specify the level of verbose with `git commit`. + A boolean or int to specify the level of verbosity with `git commit`. See linkgit:git-commit[1]. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 41e330f..93d65e1 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -444,17 +444,32 @@ You probably do not need to adjust this value. Common unit suffixes of 'k', 'm', or 'g' are supported. core.bigFileThreshold:: - Files larger than this size are stored deflated, without - attempting delta compression. Storing large files without - delta compression avoids excessive memory usage, at the - slight expense of increased disk usage. Additionally files - larger than this size are always treated as binary. + The size of files considered "big", which as discussed below + changes the behavior of numerous git commands, as well as how + such files are stored within the repository. The default is + 512 MiB. Common unit suffixes of 'k', 'm', or 'g' are + supported. + -Default is 512 MiB on all platforms. This should be reasonable -for most projects as source code and other text files can still -be delta compressed, but larger binary media files won't be. +Files above the configured limit will be: + -Common unit suffixes of 'k', 'm', or 'g' are supported. +* Stored deflated in packfiles, without attempting delta compression. ++ +The default limit is primarily set with this use-case in mind. With it, +most projects will have their source code and other text files delta +compressed, but not larger binary media files. ++ +Storing large files without delta compression avoids excessive memory +usage, at the slight expense of increased disk usage. ++ +* Will be treated as if they were labeled "binary" (see + linkgit:gitattributes[5]). e.g. linkgit:git-log[1] and + linkgit:git-diff[1] will not compute diffs for files above this limit. ++ +* Will generally be streamed when written, which avoids excessive +memory usage, at the cost of some fixed overhead. Commands that make +use of this include linkgit:git-archive[1], +linkgit:git-fast-import[1], linkgit:git-index-pack[1], +linkgit:git-unpack-objects[1] and linkgit:git-fsck[1]. core.excludesFile:: Specifies the pathname to the file that contains patterns to @@ -505,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 @@ -512,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 @@ -603,7 +633,7 @@ but risks losing recent work in the event of an unclean system shutdown. * `loose-object` hardens objects added to the repo in loose-object form. * `pack` hardens objects added to the repo in packfile form. * `pack-metadata` hardens packfile bitmaps and indexes. -* `commit-graph` hardens the commit graph file. +* `commit-graph` hardens the commit-graph file. * `index` hardens the index when it is modified. * `objects` is an aggregate option that is equivalent to `loose-object,pack`. @@ -673,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:: @@ -707,8 +737,8 @@ core.sparseCheckout:: core.sparseCheckoutCone:: Enables the "cone mode" of the sparse checkout feature. When the sparse-checkout file contains a limited set of patterns, this - mode provides significant performance advantages. The "non - cone mode" can be requested to allow specifying a more flexible + mode provides significant performance advantages. The "non-cone + mode" can be requested to allow specifying more flexible patterns by setting this variable to 'false'. See linkgit:git-sparse-checkout[1] for more information. @@ -721,3 +751,9 @@ core.abbrev:: If set to "no", no abbreviation is made and the object names are shown in their full length. The minimum length is 4. + +core.maxTreeDepth:: + The maximum depth Git is willing to recurse while traversing a + tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe + to allow Git to abort cleanly, and should not generally need to + be adjusted. The default is 4096. diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt index 512f318..0221c3e 100644 --- a/Documentation/config/credential.txt +++ b/Documentation/config/credential.txt @@ -21,7 +21,7 @@ credential.username:: credential.<url>.*:: Any of the credential.* options above can be applied selectively to - some credentials. For example "credential.https://example.com.username" + some credentials. For example, "credential.https://example.com.username" would set the default username only for https connections to example.com. See linkgit:gitcredentials[7] for details on how URLs are matched. @@ -31,6 +31,6 @@ credentialCache.ignoreSIGHUP:: credentialStore.lockTimeoutMS:: The length of time, in milliseconds, for git-credential-store to retry - when trying to lock the credentials file. Value 0 means not to retry at + when trying to lock the credentials file. A value of 0 means not to retry at all; -1 means to try indefinitely. Default is 1000 (i.e., retry for 1s). diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 32f8483..5ce7b91 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -1,6 +1,6 @@ diff.autoRefreshIndex:: When using 'git diff' to compare with work tree - files, do not consider stat-only change as changed. + files, do not consider stat-only changes as changed. Instead, silently run `git update-index --refresh` to update the cached stat information for paths whose contents in the work tree match the contents in the @@ -52,6 +52,10 @@ directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: `files,10,cumulative`. +diff.statNameWidth:: + Limit the width of the filename part in --stat output. If set, applies + to all commands generating --stat output except format-patch. + diff.statGraphWidth:: Limit the width of the graph part in --stat output. If set, applies to all commands generating --stat output except format-patch. @@ -104,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. @@ -178,21 +188,6 @@ diff.<driver>.cachetextconv:: Set this option to true to make the diff driver cache the text conversion outputs. See linkgit:gitattributes[5] for details. -diff.tool:: - Controls which diff tool is used by linkgit:git-difftool[1]. - This variable overrides the value configured in `merge.tool`. - The list below shows the valid built-in values. - Any other value is treated as a custom diff tool and requires - that a corresponding difftool.<tool>.cmd variable is defined. - -diff.guitool:: - Controls which diff tool is used by linkgit:git-difftool[1] when - the -g/--gui flag is specified. This variable overrides the value - configured in `merge.guitool`. The list below shows the valid - built-in values. Any other value is treated as a custom diff tool - and requires that a corresponding difftool.<guitool>.cmd variable - is defined. - include::../mergetools-diff.txt[] diff.indentHeuristic:: @@ -234,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/difftool.txt b/Documentation/config/difftool.txt index 6762594..447c40d 100644 --- a/Documentation/config/difftool.txt +++ b/Documentation/config/difftool.txt @@ -1,6 +1,17 @@ -difftool.<tool>.path:: - Override the path for the given tool. This is useful in case - your tool is not in the PATH. +diff.tool:: + Controls which diff tool is used by linkgit:git-difftool[1]. + This variable overrides the value configured in `merge.tool`. + The list below shows the valid built-in values. + Any other value is treated as a custom diff tool and requires + that a corresponding difftool.<tool>.cmd variable is defined. + +diff.guitool:: + Controls which diff tool is used by linkgit:git-difftool[1] when + the -g/--gui flag is specified. This variable overrides the value + configured in `merge.guitool`. The list below shows the valid + built-in values. Any other value is treated as a custom diff tool + and requires that a corresponding difftool.<guitool>.cmd variable + is defined. difftool.<tool>.cmd:: Specify the command to invoke the specified diff tool. @@ -9,6 +20,24 @@ difftool.<tool>.cmd:: file containing the contents of the diff pre-image and 'REMOTE' is set to the name of the temporary file containing the contents of the diff post-image. ++ +See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details. + +difftool.<tool>.path:: + Override the path for the given tool. This is useful in case + your tool is not in the PATH. + +difftool.trustExitCode:: + Exit difftool if the invoked diff tool returns a non-zero exit status. ++ +See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details. difftool.prompt:: Prompt before each invocation of the diff tool. + +difftool.guiDefault:: + Set `true` to use the `diff.guitool` by default (equivalent to specifying + the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool` + depending on the presence of a `DISPLAY` environment variable value. The + default is `false`, where the `--gui` argument must be provided + explicitly for the `diff.guitool` to be used. 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/fastimport.txt b/Documentation/config/fastimport.txt index c1166e3..903677d 100644 --- a/Documentation/config/fastimport.txt +++ b/Documentation/config/fastimport.txt @@ -1,8 +1,8 @@ fastimport.unpackLimit:: If the number of objects imported by linkgit:git-fast-import[1] is below this limit, then the objects will be unpacked into - loose object files. However if the number of imported objects - equals or exceeds this limit then the pack will be stored as a + loose object files. However, if the number of imported objects + equals or exceeds this limit, then the pack will be stored as a pack. Storing the pack from a fast-import can make the import operation complete faster, especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index cdecd04..f061b64 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -14,12 +14,23 @@ feature.experimental:: + * `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by 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 working directory. With many files, commands such as `git status` and `git checkout` may be slow and these new defaults improve performance: + +* `index.skipHash=true` speeds up index writes by not computing a trailing + checksum. Note that this will cause Git versions earlier than 2.13.0 to + refuse to parse the index and Git versions earlier than 2.40.0 will report + a corrupted index during `git fsck`. ++ * `index.version=4` enables path-prefix compression in the index. + * `core.untrackedCache=true` enables the untracked cache. This setting assumes diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index cd65d23..d7dc461 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -50,10 +50,16 @@ 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 section - OUTPUT in linkgit:git-fetch[1] for detail. + `full` and `compact`. Default value is `full`. See the + OUTPUT section in linkgit:git-fetch[1] for details. fetch.negotiationAlgorithm:: Control how information about the commits in the local repository @@ -96,3 +102,27 @@ fetch.writeCommitGraph:: merge and the write may take longer. Having an updated commit-graph file helps performance of many Git commands, including `git merge-base`, `git push -f`, and `git log --graph`. Defaults to false. + +fetch.bundleURI:: + This value stores a URI for downloading Git object data from a bundle + URI before performing an incremental fetch from the origin Git server. + This is similar to how the `--bundle-uri` option behaves in + linkgit:git-clone[1]. `git clone --bundle-uri` will set the + `fetch.bundleURI` value if the supplied bundle URI contains a bundle + list that is organized for incremental fetches. ++ +If you modify this value and your repository has a `fetch.bundleCreationToken` +value, then remove that `fetch.bundleCreationToken` value before fetching from +the new bundle URI. + +fetch.bundleCreationToken:: + When using `fetch.bundleURI` to fetch incrementally from a bundle + list that uses the "creationToken" heuristic, this config value + stores the maximum `creationToken` value of the downloaded bundles. + This value is used to prevent downloading bundles in the future + if the advertised `creationToken` is not strictly larger than this + value. ++ +The creation token values are chosen by the provider serving the specific +bundle URI. If you modify the URI at `fetch.bundleURI`, then be sure to +remove the value for the `fetch.bundleCreationToken` value before fetching. diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index fdbc06a..7410e93 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -3,7 +3,8 @@ format.attach:: 'format-patch'. The value can also be a double quoted string which will enable attachments as the default and set the value as the boundary. See the --attach option in - linkgit:git-format-patch[1]. + linkgit:git-format-patch[1]. To countermand an earlier + value, set it to an empty string. format.from:: Provides the default value for the `--from` option to format-patch. @@ -15,6 +16,10 @@ format.from:: different. If set to a non-boolean value, format-patch uses that value instead of your committer identity. Defaults to false. +format.forceInBodyFrom:: + Provides the default value for the `--[no-]force-in-body-from` + option to format-patch. Defaults to false. + format.numbered:: A boolean which can enable or disable sequence numbers in patch subjects. It defaults to "auto" which enables it only if there @@ -63,7 +68,7 @@ format.encodeEmailHeaders:: Defaults to true. format.pretty:: - The default pretty format for log/show/whatchanged command, + The default pretty format for log/show/whatchanged command. See linkgit:git-log[1], linkgit:git-show[1], linkgit:git-whatchanged[1]. @@ -114,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 @@ -135,3 +140,14 @@ For example, ------------ + will only show notes from `refs/notes/bar`. + +format.mboxrd:: + A boolean value which enables the robust "mboxrd" format when + `--stdout` is in use to escape "^>+From " lines. + +format.noprefix:: + If set, do not show any source or destination prefix in patches. + This is equivalent to the `diff.noprefix` option used by `git + diff` (but which is not respected by `format-patch`). Note that + by setting this, the receiver of any patches you generate will + have to apply them using the `-p0` option. diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt index 450e8c3..8e9e508 100644 --- a/Documentation/config/fsck.txt +++ b/Documentation/config/fsck.txt @@ -11,13 +11,13 @@ to clone or fetch it set `fetch.fsck.<msg-id>`. + The rest of the documentation discusses `fsck.*` for brevity, but the same applies for the corresponding `receive.fsck.*` and -`fetch.<msg-id>.*`. variables. +`fetch.fsck.*`. variables. + -Unlike variables like `color.ui` and `core.editor` the +Unlike variables like `color.ui` and `core.editor`, the `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>` variables will not fall back on the `fsck.<msg-id>` configuration if they aren't set. To -uniformly configure the same fsck settings in different circumstances -all three of them they must all set to the same values. +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values. + When `fsck.<msg-id>` is set, errors can be switched to warnings and vice versa by configuring the `fsck.<msg-id>` setting where the @@ -35,16 +35,20 @@ allow new instances of the same breakages go unnoticed. Setting an unknown `fsck.<msg-id>` value will cause fsck to die, but doing the same for `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>` will only cause git to warn. ++ +See the `Fsck Messages` section of linkgit:git-fsck[1] for supported +values of `<msg-id>`. + fsck.skipList:: The path to a list of object names (i.e. one unabbreviated SHA-1 per line) that are known to be broken in a non-fatal way and should - be ignored. On versions of Git 2.20 and later comments ('#'), empty - lines, and any leading and trailing whitespace is ignored. Everything + be ignored. On versions of Git 2.20 and later, comments ('#'), empty + lines, and any leading and trailing whitespace are ignored. Everything but a SHA-1 per line will error out on older versions. + This feature is useful when an established project should be accepted -despite early commits containing errors that can be safely ignored +despite early commits containing errors that can be safely ignored, such as invalid committer email addresses. Note: corrupt objects cannot be skipped with this setting. + @@ -54,11 +58,11 @@ Like `fsck.<msg-id>` this variable has corresponding Unlike variables like `color.ui` and `core.editor` the `receive.fsck.skipList` and `fetch.fsck.skipList` variables will not fall back on the `fsck.skipList` configuration if they aren't set. To -uniformly configure the same fsck settings in different circumstances -all three of them they must all set to the same values. +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values. + Older versions of Git (before 2.20) documented that the object names -list should be sorted. This was never a requirement, the object names +list should be sorted. This was never a requirement; the object names could appear in any order, but when reading the list we tracked whether the list was sorted for the purposes of an internal binary search implementation, which could save itself some work with an already sorted diff --git a/Documentation/config/fsmonitor--daemon.txt b/Documentation/config/fsmonitor--daemon.txt new file mode 100644 index 0000000..671f9b9 --- /dev/null +++ b/Documentation/config/fsmonitor--daemon.txt @@ -0,0 +1,11 @@ +fsmonitor.allowRemote:: + By default, the fsmonitor daemon refuses to work with network-mounted + repositories. Setting `fsmonitor.allowRemote` to `true` overrides this + behavior. Only respected when `core.fsmonitor` is set to `true`. + +fsmonitor.socketDir:: + This Mac OS-specific option, if set, specifies the directory in + which to create the Unix domain socket used for communication + between the fsmonitor daemon and various Git commands. The directory must + reside on a native Mac OS filesystem. Only respected when `core.fsmonitor` + is set to `true`. diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 38fea07..664a3c2 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -24,7 +24,7 @@ gc.auto:: default value is 6700. + Setting this to 0 disables not only automatic packing based on the -number of loose objects, but any other heuristic `git gc --auto` will +number of loose objects, but also any other heuristic `git gc --auto` will otherwise use to determine if there's work to do, such as `gc.autoPackLimit`. @@ -39,15 +39,15 @@ See the `gc.bigPackThreshold` configuration variable below. When in use, it'll affect how the auto pack limit works. gc.autoDetach:: - Make `git gc --auto` return immediately and run in background + Make `git gc --auto` return immediately and run in the background if the system supports it. Default is true. gc.bigPackThreshold:: - If non-zero, all packs larger than this limit are kept when - `git gc` is run. This is very similar to `--keep-largest-pack` - except that all packs that meet the threshold are kept, not - just the largest pack. Defaults to zero. Common unit suffixes of - 'k', 'm', or 'g' are supported. + If non-zero, all non-cruft packs larger than this limit are kept + when `git gc` is run. This is very similar to + `--keep-largest-pack` except that all non-cruft packs that meet + the threshold are kept, not just the largest pack. Defaults to + zero. Common unit suffixes of 'k', 'm', or 'g' are supported. + Note that if the number of kept packs is more than gc.autoPackLimit, this configuration variable is ignored, all packs except the base pack @@ -84,7 +84,13 @@ gc.packRefs:: gc.cruftPacks:: Store unreachable objects in a cruft pack (see linkgit:git-repack[1]) instead of as loose objects. The default - is `false`. + is `true`. + +gc.maxCruftSize:: + Limit the size of new cruft packs when repacking. When + specified in addition to `--max-cruft-size`, the command line + option takes priority. See the `--max-cruft-size` option of + linkgit:git-repack[1]. gc.pruneExpire:: When 'git gc' is run, it will call 'prune --expire 2.weeks.ago' @@ -130,6 +136,37 @@ or rebase occurring. Since these changes are not part of the current project most users will want to expire them sooner, which is why the default is more aggressive than `gc.reflogExpire`. +gc.recentObjectsHook:: + When considering whether or not to remove an object (either when + generating a cruft pack or storing unreachable objects as + loose), use the shell to execute the specified command(s). + Interpret their output as object IDs which Git will consider as + "recent", regardless of their age. By treating their mtimes as + "now", any objects (and their descendants) mentioned in the + output will be kept regardless of their true age. ++ +Output must contain exactly one hex object ID per line, and nothing +else. Objects which cannot be found in the repository are ignored. +Multiple hooks are supported, but all must exit successfully, else the +operation (either generating a cruft pack or unpacking unreachable +objects) will be halted. + +gc.repackFilter:: + When repacking, use the specified filter to move certain + objects into a separate packfile. See the + `--filter=<filter-spec>` option of linkgit:git-repack[1]. + +gc.repackFilterTo:: + When repacking and using a filter, see `gc.repackFilter`, the + specified location will be used to create the packfile + containing the filtered out objects. **WARNING:** The + specified location should be accessible, using for example the + Git alternates mechanism, otherwise the repo could be + considered corrupt by Git as it migh not be able to access the + objects in that packfile. See the `--filter-to=<dir>` option + of linkgit:git-repack[1] and the `objects/info/alternates` + section of linkgit:gitrepository-layout[5]. + gc.rerereResolved:: Records of conflicted merge you resolved earlier are kept for this many days when 'git rerere gc' is run. diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index 86f6308..5cf32b1 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -4,7 +4,7 @@ gpg.program:: same command-line interface as GPG, namely, to verify a detached signature, "`gpg --verify $signature - <$file`" is run, and the program is expected to signal a good signature by exiting with - code 0, and to generate an ASCII-armored detached signature, the + code 0. To generate an ASCII-armored detached signature, the standard input of "`gpg -bsau $key`" is fed with the contents to be signed, and the program is expected to send the result to its standard output. @@ -12,6 +12,9 @@ gpg.program:: gpg.format:: Specifies which key format to use when signing with `--gpg-sign`. Default is "openpgp". Other possible values are "x509", "ssh". ++ +See linkgit:gitformat-signature[5] for the signature format, which differs +based on the selected `gpg.format`. gpg.<format>.program:: Use this to customize the program used for the signing format you @@ -22,7 +25,7 @@ gpg.<format>.program:: gpg.minTrustLevel:: Specifies a minimum trust level for signature verification. If this option is unset, then signature verification for merge - operations require a key with at least `marginal` trust. Other + operations requires a key with at least `marginal` trust. Other operations that perform signature verification require a key with at least `undefined` trust. Setting this option overrides the required trust-level for all operations. Supported values, @@ -35,7 +38,7 @@ gpg.minTrustLevel:: * `ultimate` gpg.ssh.defaultKeyCommand:: - This command that will be run when user.signingkey is not set and a ssh + This command will be run when user.signingkey is not set and a ssh signature is requested. On successful exit a valid ssh public key prefixed with `key::` is expected in the first line of its output. This allows for a script doing a dynamic lookup of the correct public diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt index 182edd8..10041f2 100644 --- a/Documentation/config/grep.txt +++ b/Documentation/config/grep.txt @@ -17,9 +17,12 @@ grep.extendedRegexp:: other than 'default'. grep.threads:: - Number of grep worker threads to use. - See `grep.threads` in linkgit:git-grep[1] for more information. + Number of grep worker threads to use. If unset (or set to 0), Git will + use as many threads as the number of logical cores available. + +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/gui.txt b/Documentation/config/gui.txt index 0c087fd..171be77 100644 --- a/Documentation/config/gui.txt +++ b/Documentation/config/gui.txt @@ -24,7 +24,7 @@ gui.matchTrackingBranch:: not. Default: "false". gui.newBranchTemplate:: - Is used as suggested name when creating new branches using the + Is used as a suggested name when creating new branches using the linkgit:git-gui[1]. gui.pruneDuringFetch:: diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index afeeccf..2d4e0c9 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -246,20 +246,21 @@ significantly since the entire buffer is allocated even for small pushes. http.lowSpeedLimit, http.lowSpeedTime:: - If the HTTP transfer speed is less than 'http.lowSpeedLimit' - for longer than 'http.lowSpeedTime' seconds, the transfer is aborted. + If the HTTP transfer speed, in bytes per second, is less than + 'http.lowSpeedLimit' for longer than 'http.lowSpeedTime' seconds, + the transfer is aborted. Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and `GIT_HTTP_LOW_SPEED_TIME` environment variables. http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. - This can helpful with some "poor" ftp servers which don't + This can be helpful with some "poor" ftp servers which don't support EPSV mode. Can be overridden by the `GIT_CURL_FTP_NO_EPSV` environment variable. Default is false (curl will use EPSV). http.userAgent:: The HTTP USER_AGENT string presented to an HTTP server. The default - value represents the version of the client Git such as git/1.7.1. + value represents the version of the Git client such as git/1.7.1. This option allows you to override this value to a more common value such as Mozilla/4.0. This may be necessary, for instance, if connecting through a firewall that restricts HTTP connections to a set diff --git a/Documentation/config/i18n.txt b/Documentation/config/i18n.txt index cc25621..6e72fdb 100644 --- a/Documentation/config/i18n.txt +++ b/Documentation/config/i18n.txt @@ -2,7 +2,7 @@ i18n.commitEncoding:: Character encoding the commit messages are stored in; Git itself does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history - browser (and possibly at other places in the future or in other + browser (and possibly in other places in the future or in other porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'. i18n.logOutputEncoding:: diff --git a/Documentation/config/imap.txt b/Documentation/config/imap.txt index 06166fb..3d28f72 100644 --- a/Documentation/config/imap.txt +++ b/Documentation/config/imap.txt @@ -4,7 +4,7 @@ imap.folder:: "[Gmail]/Drafts". Required. imap.tunnel:: - Command used to setup a tunnel to the IMAP server through which + Command used to set up a tunnel to the IMAP server through which commands will be piped instead of using a direct network connection to the server. Required when imap.host is not set. @@ -37,7 +37,7 @@ imap.preformattedHTML:: format=fixed email. Default is `false`. imap.authMethod:: - Specify authenticate method for authentication with IMAP server. + Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older than 7.34.0, or if you're running git-imap-send with the `--no-curl` option, the only supported method is 'CRAM-MD5'. If this is not set diff --git a/Documentation/config/includeif.txt b/Documentation/config/includeif.txt new file mode 100644 index 0000000..82fe431 --- /dev/null +++ b/Documentation/config/includeif.txt @@ -0,0 +1,6 @@ +include.path:: +includeIf.<condition>.path:: + Special variables to include other configuration files. See + the "CONFIGURATION FILE" section in the main + linkgit:git-config[1] documentation, + specifically the "Includes" and "Conditional Includes" subsections. diff --git a/Documentation/config/index.txt b/Documentation/config/index.txt index 75f3a2d..3eff420 100644 --- a/Documentation/config/index.txt +++ b/Documentation/config/index.txt @@ -23,10 +23,21 @@ index.threads:: Specifies the number of threads to spawn when loading the index. This is meant to reduce index load time on multiprocessor machines. Specifying 0 or 'true' will cause Git to auto-detect the number of - CPU's and set the number of threads accordingly. Specifying 1 or + CPUs and set the number of threads accordingly. Specifying 1 or 'false' will disable multithreading. Defaults to 'true'. index.version:: Specify the version with which new index files should be initialized. This does not affect existing repositories. If `feature.manyFiles` is enabled, then the default is 4. + +index.skipHash:: + When enabled, do not compute the trailing hash for the index file. + This accelerates Git commands that manipulate the index, such as + `git add`, `git commit`, or `git status`. Instead of storing the + checksum, write a trailing set of bytes with value zero, indicating + that the computation was skipped. ++ +If you enable `index.skipHash`, then Git clients older than 2.13.0 will +refuse to parse the index and Git clients older than 2.40.0 will report an +error during `git fsck`. 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/log.txt b/Documentation/config/log.txt index 456eb07..9003a82 100644 --- a/Documentation/config/log.txt +++ b/Documentation/config/log.txt @@ -7,6 +7,10 @@ log.date:: Set the default date-time mode for the 'log' command. Setting a value for log.date is similar to using 'git log''s `--date` option. See linkgit:git-log[1] for details. ++ +If the format is set to "auto:foo" and the pager is in use, format +"foo" will be used for the date format. Otherwise, "default" will +be used. log.decorate:: Print out the ref names of any commits that are shown by the log @@ -18,6 +22,11 @@ log.decorate:: names are shown. This is the same as the `--decorate` option of the `git log`. +log.initialDecorationSet:: + By default, `git log` only shows decorations for certain known ref + namespaces. If 'all' is specified, then show all refs as + decorations. + log.excludeDecoration:: Exclude the specified patterns from the log decorations. This is similar to the `--decorate-refs-exclude` command-line option, but @@ -25,9 +34,9 @@ log.excludeDecoration:: option. log.diffMerges:: - Set default diff format to be used for merge commits. See - `--diff-merges` in linkgit:git-log[1] for details. - Defaults to `separate`. + Set diff format to be used when `--diff-merges=on` is + specified, see `--diff-merges` in linkgit:git-log[1] for + details. Defaults to `separate`. log.follow:: If `true`, `git log` will act as if the `--follow` option was used when diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt index adeda0f..3d88fb0 100644 --- a/Documentation/config/lsrefs.txt +++ b/Documentation/config/lsrefs.txt @@ -1,7 +1,7 @@ lsrefs.unborn:: May be "advertise" (the default), "allow", or "ignore". If "advertise", the server will respond to the client sending "unborn" (as described in - protocol-v2.txt) and will advertise support for this feature during the + linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the protocol v2 capability advertisement. "allow" is the same as "advertise" except that the server will not advertise support for this feature; this is useful for load-balanced servers that cannot be diff --git a/Documentation/config/mailinfo.txt b/Documentation/config/mailinfo.txt index 3854d4a..ec3a5d8 100644 --- a/Documentation/config/mailinfo.txt +++ b/Documentation/config/mailinfo.txt @@ -1,6 +1,6 @@ mailinfo.scissors:: If true, makes linkgit:git-mailinfo[1] (and therefore linkgit:git-am[1]) act by default as if the --scissors option - was provided on the command-line. When active, this features + was provided on the command-line. When active, this feature removes everything from the message body before a scissors line (i.e. consisting mainly of ">8", "8<" and "-"). diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt index 18f0562..69a4f05 100644 --- a/Documentation/config/maintenance.txt +++ b/Documentation/config/maintenance.txt @@ -12,7 +12,7 @@ maintenance.strategy:: then that value is used instead of the one provided by `maintenance.strategy`. The possible strategy strings are: + -* `none`: This default setting implies no task are run at any schedule. +* `none`: This default setting implies no tasks are run at any schedule. * `incremental`: This setting optimizes for performing small maintenance activities that do not delete any data. This does not schedule the `gc` task, but runs the `prefetch` and `commit-graph` tasks hourly, the diff --git a/Documentation/config/man.txt b/Documentation/config/man.txt index a727d98..5a0f82c 100644 --- a/Documentation/config/man.txt +++ b/Documentation/config/man.txt @@ -5,7 +5,7 @@ man.viewer:: man.<tool>.cmd:: Specify the command to invoke the specified man viewer. The specified command is evaluated in shell with the man page - passed as argument. (See linkgit:git-help[1].) + passed as an argument. (See linkgit:git-help[1].) man.<tool>.path:: Override the path for the given tool that may be used to diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 99e83dd..8851b6c 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -7,7 +7,7 @@ merge.conflictStyle:: marker and the original text before the `=======` marker. The "merge" style tends to produce smaller conflict regions than diff3, both because of the exclusion of the original text, and because - when a subset of lines match on the two sides they are just pulled + when a subset of lines match on the two sides, they are just pulled out of the conflict region. Another alternate style, "zdiff3", is similar to diff3 but removes matching lines on the two sides from the conflict region when those matching lines appear near either diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index 90b3809..00bf665 100644 --- a/Documentation/config/mergetool.txt +++ b/Documentation/config/mergetool.txt @@ -22,8 +22,8 @@ mergetool.<tool>.trustExitCode:: For a custom merge command, specify whether the exit code of the merge command can be used to determine whether the merge was successful. If this is not set to true then the merge target file - timestamp is checked and the merge assumed to have been successful - if the file has been updated, otherwise the user is prompted to + timestamp is checked, and the merge is assumed to have been successful + if the file has been updated; otherwise, the user is prompted to indicate the success of the merge. mergetool.meld.hasOutput:: @@ -37,7 +37,7 @@ mergetool.meld.hasOutput:: mergetool.meld.useAutoMerge:: When the `--auto-merge` is given, meld will merge all non-conflicting - parts automatically, highlight the conflicting parts and wait for + parts automatically, highlight the conflicting parts, and wait for user decision. Setting `mergetool.meld.useAutoMerge` to `true` tells Git to unconditionally use the `--auto-merge` option with `meld`. Setting this value to `auto` makes git detect whether `--auto-merge` @@ -45,21 +45,28 @@ 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 look like. 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 + During a merge, Git will automatically resolve as many conflicts as possible and write the 'MERGED' file containing conflict markers around any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally represent the versions of the file from before Git's conflict - resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwriten so + resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so that only the unresolved conflicts are presented to the merge tool. Can be configured per-tool via the `mergetool.<tool>.hideResolved` configuration variable. Defaults to `false`. @@ -74,7 +81,7 @@ mergetool.keepTemporaries:: When invoking a custom merge tool, Git uses a set of temporary files to pass to the tool. If the tool returns an error and this variable is set to `true`, then these temporary files will be - preserved, otherwise they will be removed after the tool has + preserved; otherwise, they will be removed after the tool has exited. Defaults to `false`. mergetool.writeToTemp:: @@ -85,3 +92,10 @@ mergetool.writeToTemp:: mergetool.prompt:: Prompt before each invocation of the merge resolution program. + +mergetool.guiDefault:: + Set `true` to use the `merge.guitool` by default (equivalent to + specifying the `--gui` argument), or `auto` to select `merge.guitool` + or `merge.tool` depending on the presence of a `DISPLAY` environment + variable value. The default is `false`, where the `--gui` argument + must be provided explicitly for the `merge.guitool` to be used. diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt index aeef56d..43db8e8 100644 --- a/Documentation/config/notes.txt +++ b/Documentation/config/notes.txt @@ -1,8 +1,11 @@ notes.mergeStrategy:: Which merge strategy to choose by default when resolving notes conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or - `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" + `cat_sort_uniq`. Defaults to `manual`. See the "NOTES MERGE STRATEGIES" section of linkgit:git-notes[1] for more information on each strategy. ++ +This setting can be overridden by passing the `--strategy` option to +linkgit:git-notes[1]. notes.<name>.mergeStrategy:: Which merge strategy to choose when doing a notes merge into @@ -11,28 +14,35 @@ notes.<name>.mergeStrategy:: linkgit:git-notes[1] for more information on the available strategies. notes.displayRef:: - The (fully qualified) refname from which to show notes when - showing commit messages. The value of this variable can be set - to a glob, in which case notes from all matching refs will be - shown. You may also specify this configuration variable - several times. A warning will be issued for refs that do not - exist, but a glob that does not match any refs is silently - ignored. + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by `core.notesRef` or + `GIT_NOTES_REF`, to read notes from when showing commit + messages with the 'git log' family of commands. + This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` environment variable, which must be a colon separated list of refs or globs. + +A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored. ++ +This setting can be disabled by the `--no-notes` option to the 'git +log' family of commands, or by the `--notes=<ref>` option accepted by +those commands. ++ The effective value of "core.notesRef" (possibly overridden by GIT_NOTES_REF) is also implicitly added to the list of refs to be displayed. notes.rewrite.<command>:: When rewriting commits with <command> (currently `amend` or - `rebase`) and this variable is set to `true`, Git - automatically copies your notes from the original to the - rewritten commit. Defaults to `true`, but see - "notes.rewriteRef" below. + `rebase`), if this variable is `false`, git will not copy + notes from the original to the rewritten commit. Defaults to + `true`. See also "`notes.rewriteRef`" below. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_REF` +environment variable, which must be a colon separated list of refs or +globs. notes.rewriteMode:: When copying notes during a rewrite (see the @@ -46,14 +56,13 @@ environment variable. notes.rewriteRef:: When copying notes during a rewrite, specifies the (fully - qualified) ref whose notes should be copied. The ref may be a - glob, in which case notes in all matching refs will be copied. - You may also specify this configuration several times. + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. + Does not have a default value; you must configure this variable to enable note rewriting. Set it to `refs/notes/commits` to enable rewriting for the default commit notes. + -This setting can be overridden with the `GIT_NOTES_REWRITE_REF` -environment variable, which must be a colon separated list of refs or -globs. +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable. +See `notes.rewrite.<command>` above for a further description of its format. diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index ad7f73a..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 @@ -74,7 +79,7 @@ pack.threads:: warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. - Specifying 0 will cause Git to auto-detect the number of CPU's + Specifying 0 will cause Git to auto-detect the number of CPUs and set the number of threads accordingly. pack.indexVersion:: @@ -83,11 +88,11 @@ pack.indexVersion:: the new pack index with capabilities for packs larger than 4 GB as well as proper protection against the repacking of corrupted packs. Version 2 is the default. Note that version 2 is enforced - and this config option ignored whenever the corresponding pack is + and this config option is ignored whenever the corresponding pack is larger than 2 GB. + If you have an old Git that does not understand the version 2 `*.idx` file, -cloning or fetching over a non native protocol (e.g. "http") +cloning or fetching over a non-native protocol (e.g. "http") that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your older version of Git. If the `*.pack` file is smaller than 2 GB, however, @@ -102,8 +107,8 @@ pack.packSizeLimit:: in the creation of multiple packfiles. + Note that this option is rarely useful, and may result in a larger total -on-disk size (because Git will not store deltas between packs), as well -as worse runtime performance (object lookup within multiple packs is +on-disk size (because Git will not store deltas between packs) and +worse runtime performance (object lookup within multiple packs is slower than a single pack, and optimizations like reachability bitmaps cannot cope with multiple packs). + @@ -123,6 +128,23 @@ pack.useBitmaps:: true. You should not generally need to turn this off unless you are debugging pack bitmaps. +pack.useBitmapBoundaryTraversal:: + When true, Git will use an experimental algorithm for computing + reachability queries with bitmaps. Instead of building up + complete bitmaps for all of the negated tips and then OR-ing + them together, consider negated tips with existing bitmaps as + additive (i.e. OR-ing them into the result if they exist, + ignoring them otherwise), and build up a bitmap at the boundary + instead. ++ +When using this algorithm, Git may include too many objects as a result +of not opening up trees belonging to certain UNINTERESTING commits. This +inexactness matches the non-bitmap traversal algorithm. ++ +In many cases, this can provide a speed-up over the exact algorithm, +particularly when there is poor bitmap coverage of the negated side of +the query. + pack.useSparse:: When true, git will default to using the '--sparse' option in 'git pack-objects' when the '--revs' option is present. This @@ -164,9 +186,22 @@ When writing a multi-pack reachability bitmap, no new namehashes are computed; instead, any namehashes stored in an existing bitmap are permuted into their appropriate location when writing a new bitmap. +pack.writeBitmapLookupTable:: + When true, Git will include a "lookup table" section in the + bitmap index (if one is written). This table is used to defer + loading individual bitmaps as late as possible. This can be + beneficial in repositories that have relatively large bitmap + indexes. Defaults to false. + +pack.readReverseIndex:: + When true, git will read any .rev file(s) that may be available + (see: linkgit:gitformat-pack[5]). When false, the reverse index + will be generated from scratch and stored in memory. Defaults to + true. + pack.writeReverseIndex:: When true, git will write a corresponding .rev file (see: - link:../technical/pack-format.html[Documentation/technical/pack-format.txt]) + linkgit:gitformat-pack[5]) for each new packfile that it writes in all places except for linkgit:git-fast-import[1] and in the bulk checkin mechanism. - Defaults to false. + Defaults to true. diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index 756591d..a9bf187 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -1,10 +1,10 @@ protocol.allow:: If set, provide a user defined default policy for all protocols which don't explicitly have a policy (`protocol.<name>.allow`). By default, - if unset, known-safe protocols (http, https, git, ssh, file) have a + if unset, known-safe protocols (http, https, git, ssh) have a default policy of `always`, known-dangerous protocols (ext) have a - default policy of `never`, and all other protocols have a default - policy of `user`. Supported policies: + default policy of `never`, and all other protocols (including file) + have a default policy of `user`. Supported policies: + -- @@ -58,6 +58,6 @@ protocol.version:: * `1` - the original wire protocol with the addition of a version string in the initial response from the server. -* `2` - link:technical/protocol-v2.html[wire protocol version 2]. +* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5]. -- diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index e32801e..0acbbea 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -35,7 +35,7 @@ push.default:: * `tracking` - This is a deprecated synonym for `upstream`. -* `simple` - pushes the current branch with the same name on the remote. +* `simple` - push the current branch with the same name on the remote. + If you are working on a centralized workflow (pushing to the same repository you pull from, which is typically `origin`), then you need to configure an upstream @@ -67,7 +67,7 @@ new default). -- push.followTags:: - If set to true enable `--follow-tags` option by default. You + If set to true, enable `--follow-tags` option by default. You may override this configuration at time of push by specifying `--no-follow-tags`. @@ -110,18 +110,8 @@ This will result in only b (a and c are cleared). ---- push.recurseSubmodules:: - Make sure all submodule commits used by the revisions to be pushed - are available on a remote-tracking branch. If the value is 'check' - then Git will verify that all submodule commits that changed in the - revisions to be pushed are available on at least one remote of the - submodule. If any commits are missing, the push will be aborted and - exit with non-zero status. If the value is 'on-demand' then all - submodules that changed in the revisions to be pushed will be - pushed. If on-demand was not able to push all necessary revisions - it will also be aborted and exit with non-zero status. If the value - is 'no' then default behavior of ignoring submodules when pushing - is retained. You may override this configuration at time of push by - specifying '--recurse-submodules=check|on-demand|no'. + May be "check", "on-demand", "only", or "no", with the same behavior + as that of "push --recurse-submodules". If not set, 'no' is used by default, unless 'submodule.recurse' is set (in which case a 'true' value means 'on-demand'). @@ -137,3 +127,8 @@ push.negotiate:: server attempt to find commits in common. If "false", Git will rely solely on the server's ref advertisement to find commits in common. + +push.useBitmaps:: + If set to "false", disable use of bitmaps for "git push" even if + `pack.useBitmaps` is "true", without preventing other git operations + from using bitmaps. Default is true. diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index 8c979cb..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 @@ -21,6 +23,9 @@ rebase.autoStash:: `--autostash` options of linkgit:git-rebase[1]. Defaults to false. +rebase.updateRefs:: + If set to true enable `--update-refs` option by default. + rebase.missingCommitsCheck:: If set to "warn", git rebase -i will print a warning if some commits are removed (e.g. a line was deleted), however the @@ -35,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 @@ -64,3 +69,19 @@ rebase.rescheduleFailedExec:: rebase.forkPoint:: If set to false set `--no-fork-point` option by default. + +rebase.rebaseMerges:: + Whether and how to set the `--rebase-merges` option by default. Can + be `rebase-cousins`, `no-rebase-cousins`, or a boolean. Setting to + true or to `no-rebase-cousins` is equivalent to + `--rebase-merges=no-rebase-cousins`, setting to `rebase-cousins` is + equivalent to `--rebase-merges=rebase-cousins`, and setting to false is + equivalent to `--no-rebase-merges`. Passing `--rebase-merges` on the + command line, with or without an argument, overrides any + `rebase.rebaseMerges` configuration. + +rebase.maxLabelLength:: + When generating label names from commit subjects, truncate the names to + this length. By default, the names are truncated to a little less than + `NAME_MAX` (to allow e.g. `.lock` files to be written for the + corresponding loose refs). diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt index 85d5b5a..c77e55b 100644 --- a/Documentation/config/receive.txt +++ b/Documentation/config/receive.txt @@ -14,12 +14,12 @@ receive.autogc:: receive.certNonceSeed:: By setting this variable to a string, `git receive-pack` - will accept a `git push --signed` and verifies it by using + will accept a `git push --signed` and verify it by using a "nonce" protected by HMAC using this string as a secret key. receive.certNonceSlop:: - When a `git push --signed` sent a push certificate with a + When a `git push --signed` sends a push certificate with a "nonce" that was issued by a receive-pack serving the same repository within this many seconds, export the "nonce" found in the certificate to `GIT_PUSH_CERT_NONCE` to the diff --git a/Documentation/config/rerere.txt b/Documentation/config/rerere.txt index 40abdf6..3a78b5e 100644 --- a/Documentation/config/rerere.txt +++ b/Documentation/config/rerere.txt @@ -1,7 +1,7 @@ rerere.autoUpdate:: When set to true, `git-rerere` updates the index with the resulting contents after it cleanly resolves conflicts using - previously recorded resolution. Defaults to false. + previously recorded resolutions. Defaults to false. rerere.enabled:: Activate recording of resolved conflicts, so that identical diff --git a/Documentation/config/revert.txt b/Documentation/config/revert.txt index 797bfb6..802d6fa 100644 --- a/Documentation/config/revert.txt +++ b/Documentation/config/revert.txt @@ -1,3 +1,3 @@ revert.reference:: - Setting this variable to true makes `git revert` to behave + Setting this variable to true makes `git revert` behave as if the `--reference` option is given. diff --git a/Documentation/config/safe.txt b/Documentation/config/safe.txt index fa02f3c..577df40 100644 --- a/Documentation/config/safe.txt +++ b/Documentation/config/safe.txt @@ -1,3 +1,22 @@ +safe.bareRepository:: + Specifies which bare repositories Git will work with. The currently + supported values are: ++ +* `all`: Git works with all bare repositories. This is the default. +* `explicit`: Git only works with bare repositories specified via + the top-level `--git-dir` command-line option, or the `GIT_DIR` + environment variable (see linkgit:git[1]). ++ +If you do not use bare repositories in your workflow, then it may be +beneficial to set `safe.bareRepository` to `explicit` in your global +config. This will protect you from attacks that involve cloning a +repository that contains a bare repository and running a Git command +within that directory. ++ +This config setting is only respected in protected configuration (see +<<SCOPES>>). This prevents untrusted repositories from tampering with +this value. + safe.directory:: These config entries specify Git-tracked directories that are considered safe even if they are owned by someone other than the @@ -12,9 +31,9 @@ via `git config --add`. To reset the list of safe directories (e.g. to override any such directories specified in the system config), add a `safe.directory` entry with an empty value. + -This config setting is only respected when specified in a system or global -config, not when it is specified in a repository config, via the command -line option `-c safe.directory=<path>`, or in environment variables. +This config setting is only respected in protected configuration (see +<<SCOPES>>). This prevents untrusted repositories from tampering with this +value. + The value of this setting is interpolated, i.e. `~/<path>` expands to a path relative to the home directory and `%(prefix)/<path>` expands to a diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 50baa5d..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. @@ -18,23 +18,56 @@ sendemail.<identity>.*:: identity is selected, through either the command-line or `sendemail.identity`. +sendemail.multiEdit:: + If true (default), a single editor instance will be spawned to edit + files you have to edit (patches when `--annotate` is used, and the + summary when `--compose` is used). If false, files will be edited one + after the other, spawning a new editor each time. + +sendemail.confirm:: + Sets the default for whether to confirm before sending. Must be + one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` + in the linkgit:git-send-email[1] documentation for the meaning of these + values. + sendemail.aliasesFile:: + To avoid typing long email addresses, point this to one or more + email aliases files. You must also supply `sendemail.aliasFileType`. + sendemail.aliasFileType:: + Format of the file(s) specified in sendemail.aliasesFile. Must be + one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'. ++ +What an alias file in each format looks like can be found in +the documentation of the email program of the same name. The +differences and limitations from the standard formats are +described below: ++ +-- +sendmail;; +* Quoted aliases and quoted addresses are not supported: lines that + contain a `"` symbol are ignored. +* Redirection to a file (`/path/name`) or pipe (`|command`) is not + supported. +* File inclusion (`:include: /path/name`) is not supported. +* Warnings are printed on the standard error output for any + explicitly unsupported constructs, and any other lines that are not + recognized by the parser. +-- sendemail.annotate:: sendemail.bcc:: sendemail.cc:: sendemail.ccCmd:: sendemail.chainReplyTo:: -sendemail.confirm:: sendemail.envelopeSender:: sendemail.from:: -sendemail.multiEdit:: -sendemail.signedoffbycc:: +sendemail.headerCmd:: +sendemail.signedOffByCc:: sendemail.smtpPass:: -sendemail.suppresscc:: +sendemail.suppressCc:: sendemail.suppressFrom:: sendemail.to:: -sendemail.tocmd:: +sendemail.toCmd:: sendemail.smtpDomain:: sendemail.smtpServer:: sendemail.smtpServerPort:: @@ -44,10 +77,12 @@ sendemail.thread:: sendemail.transferEncoding:: sendemail.validate:: sendemail.xmailer:: - See linkgit:git-send-email[1] for description. + These configuration variables all provide a default for + 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 @@ -56,7 +91,7 @@ sendemail.smtpBatchSize:: See also the `--batch-size` option of linkgit:git-send-email[1]. sendemail.smtpReloginDelay:: - Seconds wait before reconnecting to smtp server. + Seconds to wait before reconnecting to the smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. sendemail.forbidSendmailVariables:: diff --git a/Documentation/config/sequencer.txt b/Documentation/config/sequencer.txt index b48d532..e664eef 100644 --- a/Documentation/config/sequencer.txt +++ b/Documentation/config/sequencer.txt @@ -2,4 +2,4 @@ sequence.editor:: Text editor used by `git rebase -i` for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable. - When not configured the default commit message editor is used instead. + When not configured, the default commit message editor is used instead. diff --git a/Documentation/config/splitindex.txt b/Documentation/config/splitindex.txt index afdb186..cfaa296 100644 --- a/Documentation/config/splitindex.txt +++ b/Documentation/config/splitindex.txt @@ -3,10 +3,10 @@ splitIndex.maxPercentChange:: percent of entries the split index can contain compared to the total number of entries in both the split index and the shared index before a new shared index is written. - The value should be between 0 and 100. If the value is 0 then - a new shared index is always written, if it is 100 a new + The value should be between 0 and 100. If the value is 0, then + a new shared index is always written; if it is 100, a new shared index is never written. - By default the value is 20, so a new shared index is written + By default, the value is 20, so a new shared index is written if the number of entries in the split index would be greater than 20 percent of the total number of entries. See linkgit:git-update-index[1]. diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt index b9f609e..ec1edae 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -1,14 +1,14 @@ stash.showIncludeUntracked:: If this is set to true, the `git stash show` command will show the untracked files of a stash entry. Defaults to false. See - description of 'show' command in linkgit:git-stash[1]. + the description of the 'show' command in linkgit:git-stash[1]. stash.showPatch:: If this is set to true, the `git stash show` command without an option will show the stash entry in patch form. Defaults to false. - See description of 'show' command in linkgit:git-stash[1]. + See the description of the 'show' command in linkgit:git-stash[1]. stash.showStat:: If this is set to true, the `git stash show` command without an - option will show diffstat of the stash entry. Defaults to true. - See description of 'show' command in linkgit:git-stash[1]. + option will show a diffstat of the stash entry. Defaults to true. + See the description of the 'show' command in linkgit:git-stash[1]. diff --git a/Documentation/config/status.txt b/Documentation/config/status.txt index 0fc704a..8caf90f 100644 --- a/Documentation/config/status.txt +++ b/Documentation/config/status.txt @@ -47,7 +47,7 @@ status.showUntrackedFiles:: contain only untracked files, are shown with the directory name only. Showing untracked files means that Git needs to lstat() all the files in the whole repository, which might be slow on some - systems. So, this variable controls how the commands displays + systems. So, this variable controls how the commands display the untracked files. Possible values are: + -- @@ -57,12 +57,14 @@ 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]. status.submoduleSummary:: Defaults to false. - If this is set to a non zero number or true (identical to -1 or an + If this is set to a non-zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled and a summary of commits for modified submodules will be shown (see --summary-limit option of linkgit:git-submodule[1]). Please note diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 6490527..0672d99 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -2,7 +2,7 @@ submodule.<name>.url:: The URL for a submodule. This variable is copied from the .gitmodules file to the git config via 'git submodule init'. The user can change the configured URL before obtaining the submodule via 'git submodule - update'. If neither submodule.<name>.active or submodule.active are + update'. If neither submodule.<name>.active nor submodule.active are set, the presence of this variable is used as a fallback to indicate whether the submodule is of interest to git commands. See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. @@ -35,7 +35,7 @@ submodule.<name>.ignore:: a submodule as modified. When set to "all", it will never be considered modified (but it will nonetheless show up in the output of status and commit when it has been staged), "dirty" will ignore all changes - to the submodules work tree and + to the submodule's work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index fe1642f..3b6bca2 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -66,6 +66,6 @@ trace2.destinationDebug:: trace2.maxFiles:: Integer. When writing trace files to a target directory, do not - write additional traces if we would exceed this many files. Instead, + write additional traces if doing so would exceed this many files. Instead, write a sentinel file that will block further tracing to this directory. Defaults to 0, which disables this check. diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt index b4475c0..f1ce50f 100644 --- a/Documentation/config/transfer.txt +++ b/Documentation/config/transfer.txt @@ -7,26 +7,26 @@ transfer.credentialsInUrl:: and any other direct use of the configured URL. + Note that this is currently limited to detecting credentials in -`remote.<name>.url` configuration, it won't detect credentials in +`remote.<name>.url` configuration; it won't detect credentials in `remote.<name>.pushurl` configuration. + You might want to enable this to prevent inadvertent credentials exposure, e.g. because: + -* The OS or system where you're running git may not provide way way or +* The OS or system where you're running git may not provide a way or otherwise allow you to configure the permissions of the configuration file where the username and/or password are stored. * Even if it does, having such data stored "at rest" might expose you in other ways, e.g. a backup process might copy the data to another system. * The git programs will pass the full URL to one another as arguments - on the command-line, meaning the credentials will be exposed to oher - users on OS's or systems that allow other users to see the full + on the command-line, meaning the credentials will be exposed to other + unprivileged users on systems that allow them to see the full process list of other users. On linux the "hidepid" setting documented in procfs(5) allows for configuring this behavior. + If such concerns don't apply to you then you probably don't need to be -concerned about credentials exposure due to storing that sensitive +concerned about credentials exposure due to storing sensitive data in git's configuration files. If you do want to use this, set `transfer.credentialsInUrl` to one of these values: + @@ -115,3 +115,13 @@ transfer.unpackLimit:: transfer.advertiseSID:: Boolean. When true, client and server processes will advertise their unique session IDs to their remote counterpart. Defaults to false. + +transfer.bundleURI:: + When `true`, local `git clone` commands will request bundle + 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/config/uploadpack.txt b/Documentation/config/uploadpack.txt index 32fad5b..16264d8 100644 --- a/Documentation/config/uploadpack.txt +++ b/Documentation/config/uploadpack.txt @@ -49,9 +49,9 @@ uploadpack.packObjectsHook:: `pack-objects` to the hook, and expects a completed packfile on stdout. + -Note that this configuration variable is ignored if it is seen in the -repository-level config (this is a safety measure against fetching from -untrusted repositories). +Note that this configuration variable is only respected when it is specified +in protected configuration (see <<SCOPES>>). This is a safety measure +against fetching from untrusted repositories. uploadpack.allowFilter:: If this option is set, `upload-pack` will support partial diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index ec9233b..2ffc38d 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -5,14 +5,14 @@ author.email:: committer.name:: committer.email:: The `user.name` and `user.email` variables determine what ends - up in the `author` and `committer` field of commit + up in the `author` and `committer` fields of commit objects. If you need the `author` or `committer` to be different, the - `author.name`, `author.email`, `committer.name` or + `author.name`, `author.email`, `committer.name`, or `committer.email` variables can be set. - Also, all of these can be overridden by the `GIT_AUTHOR_NAME`, + All of these can be overridden by the `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, - `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables. + `GIT_COMMITTER_EMAIL`, and `EMAIL` environment variables. + Note that the `name` forms of these variables conventionally refer to some form of a personal name. See linkgit:git-commit[1] and the @@ -40,7 +40,7 @@ user.signingKey:: your private ssh key or the public key when ssh-agent is used. Alternatively it can contain a public key prefixed with `key::` directly (e.g.: "key::ssh-rsa XXXXXX identifier"). The private key - needs to be available via ssh-agent. If not set git will call + needs to be available via ssh-agent. If not set Git will call gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first key available. For backward compatibility, a raw key which begins with "ssh-", such as "ssh-rsa XXXXXX identifier", is treated diff --git a/Documentation/config/versionsort.txt b/Documentation/config/versionsort.txt index 6c7cc05..0cff090 100644 --- a/Documentation/config/versionsort.txt +++ b/Documentation/config/versionsort.txt @@ -19,14 +19,14 @@ with those suffixes. E.g. if "-pre" appears before "-rc" in the configuration, then all "1.0-preX" tags will be listed before any "1.0-rcX" tags. The placement of the main release tag relative to tags with various suffixes can be determined by specifying the empty suffix -among those other suffixes. E.g. if the suffixes "-rc", "", "-ck" and +among those other suffixes. E.g. if the suffixes "-rc", "", "-ck", and "-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags are listed first, followed by "v4.8", then "v4.8-ckX" and finally "v4.8-bfsX". + -If more than one suffixes match the same tagname, then that tagname will +If more than one suffix matches the same tagname, then that tagname will be sorted according to the suffix which starts at the earliest position in -the tagname. If more than one different matching suffixes start at +the tagname. If more than one different matching suffix starts at that earliest position, then that tagname will be sorted according to the longest of those suffixes. The sorting order between different suffixes is undefined if they are diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 7a9c3b6..a3ae874 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -43,7 +43,7 @@ That is, from the left to the right: . a space. . sha1 for "src"; 0\{40\} if creation or unmerged. . a space. -. sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree". +. sha1 for "dst"; 0\{40\} if deletion, unmerged or "work tree out of sync with the index". . a space. . status, followed by optional "score" number. . a tab or a NUL when `-z` option is used. @@ -69,8 +69,8 @@ percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites. -<sha1> is shown as all 0's if a file is new on the filesystem -and it is out of sync with the index. +The sha1 for "dst" is shown as all 0's if a file on the filesystem +is out of sync with the index. Example: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index c78063d..4b5aa5c 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -1,3 +1,4 @@ +[[generate_patch_text_with_p]] Generating patch text with -p ----------------------------- @@ -16,7 +17,7 @@ You can customize the creation of patch text via the What the -p option produces is slightly different from the traditional diff format: -1. It is preceded with a "git diff" header that looks like this: +1. It is preceded by a "git diff" header that looks like this: diff --git a/file1 b/file2 + @@ -24,9 +25,9 @@ The `a/` and `b/` filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, `/dev/null` is _not_ used in place of the `a/` or `b/` filenames. + -When rename/copy is involved, `file1` and `file2` show the +When a rename/copy is involved, `file1` and `file2` show the name of the source file of the rename/copy and the name of -the file that rename/copy produces, respectively. +the file that the rename/copy produces, respectively. 2. It is followed by one or more extended header lines: @@ -76,7 +77,7 @@ separate lines indicate the old and the new mode. 5. Hunk headers mention the name of the function to which the hunk applies. See "Defining a custom hunk-header" in - linkgit:gitattributes[5] for details of how to tailor to this to + linkgit:gitattributes[5] for details of how to tailor this to specific languages. @@ -88,7 +89,7 @@ produce a 'combined diff' when showing a merge. This is the default format when showing merges with linkgit:git-diff[1] or linkgit:git-show[1]. Note also that you can give suitable `--diff-merges` option to any of these commands to force generation of -diffs in specific format. +diffs in a specific format. A "combined diff" format looks like this: @@ -122,7 +123,7 @@ index fabadb8,cc95eb0..4866510 for_each_ref(get_name); ------------ -1. It is preceded with a "git diff" header, that looks like +1. It is preceded by a "git diff" header, that looks like this (when the `-c` option is used): diff --combined file @@ -141,22 +142,22 @@ or like this (when the `--cc` option is used): + The `mode <mode>,<mode>..<mode>` line appears only if at least one of the <mode> is different from the rest. Extended headers with -information about detected contents movement (renames and -copying detection) are designed to work with diff of two +information about detected content movement (renames and +copying detection) are designed to work with the diff of two <tree-ish> and are not used by combined diff format. -3. It is followed by two-line from-file/to-file header +3. It is followed by a two-line from-file/to-file header: --- a/file +++ b/file + -Similar to two-line header for traditional 'unified' diff +Similar to the two-line header for the traditional 'unified' diff format, `/dev/null` is used to signal created or deleted files. + However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file you get a N+1 line from-file/to-file header, -where N is the number of parents in the merge commit +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit: --- a/file --- a/file @@ -196,7 +197,7 @@ added, from the point of view of that parent). In the above example output, the function signature was changed from both files (hence two `-` removals from both file1 and file2, plus `++` to mean one line that was added does not appear -in either file1 or file2). Also eight other lines are the same +in either file1 or file2). Also, eight other lines are the same from file1 but do not appear in file2 (hence prefixed with `+`). When shown by `git diff-tree -c`, it compares the parents of a diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 3674ac4..0e94569 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,78 +22,94 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section on generating patches). + Generate patch (see <<generate_patch_text_with_p>>). ifdef::git-diff[] This is the default. endif::git-diff[] -s:: --no-patch:: - Suppress diff output. Useful for commands like `git show` that - show the patch by default, or to cancel the effect of `--patch`. + Suppress all output from the diff machinery. Useful for + commands like `git show` that show the patch by default to + squelch their output, or to cancel the effect of options like + `--patch`, `--stat` earlier on the command line in an alias. + endif::git-format-patch[] ifdef::git-log[] ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r):: +-m:: + Show diffs for merge commits in the default format. This is + similar to '--diff-merges=on', except `-m` will + produce no output unless `-p` is given as well. + +-c:: + Produce combined diff output for merge commits. + Shortcut for '--diff-merges=combined -p'. + +--cc:: + Produce dense combined diff output for merge commits. + Shortcut for '--diff-merges=dense-combined -p'. + +--dd:: + Produce diff with respect to first parent for both merge and + regular commits. + Shortcut for '--diff-merges=first-parent -p'. + +--remerge-diff:: + Produce remerge-diff output for merge commits. + Shortcut for '--diff-merges=remerge -p'. + --no-diff-merges:: + Synonym for '--diff-merges=off'. + +--diff-merges=<format>:: Specify diff format to be used for merge commits. Default is - {diff-merges-default} unless `--first-parent` is in use, in which case - `first-parent` is the default. + {diff-merges-default} unless `--first-parent` is in use, in + which case `first-parent` is the default. + ---diff-merges=(off|none)::: ---no-diff-merges::: +The following formats are supported: ++ +-- +off, none:: Disable output of diffs for merge commits. Useful to override implied value. + ---diff-merges=on::: ---diff-merges=m::: --m::: - This option makes diff output for merge commits to be shown in - the default format. `-m` will produce the output only if `-p` - is given as well. The default format could be changed using - `log.diffMerges` configuration parameter, which default value +on, m:: + Make diff output for merge commits to be shown in the default + format. The default format can be changed using + `log.diffMerges` configuration variable, whose default value is `separate`. + ---diff-merges=first-parent::: ---diff-merges=1::: - This option makes merge commits show the full diff with - respect to the first parent only. +first-parent, 1:: + Show full diff with respect to first parent. This is the same + format as `--patch` produces for non-merge commits. ++ +separate:: + Show full diff with respect to each of parents. + Separate log entry and diff is generated for each parent. ++ +combined, c:: + Show differences from each of the parents to the merge + result simultaneously instead of showing pairwise diff between + a parent and the result one at a time. Furthermore, it lists + only files which were modified from all parents. + ---diff-merges=separate::: - This makes merge commits show the full diff with respect to - each of the parents. Separate log entry and diff is generated - for each parent. +dense-combined, cc:: + Further compress output produced by `--diff-merges=combined` + by omitting uninteresting hunks whose contents in the parents + have only two variants and the merge result picks one of them + without modification. + ---diff-merges=remerge::: ---diff-merges=r::: ---remerge-diff::: - With this option, two-parent merge commits are remerged to - create a temporary tree object -- potentially containing files - with conflict markers and such. A diff is then shown between - that temporary tree and the actual merge commit. +remerge, r:: + Remerge two-parent merge commits to create a temporary tree + object--potentially containing files with conflict markers + and such. A diff is then shown between that temporary tree + and the actual merge commit. + The output emitted when this option is used is subject to change, and so is its interaction with other options (unless explicitly documented). -+ ---diff-merges=combined::: ---diff-merges=c::: --c::: - With this option, diff output for a merge commit shows the - differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a - parent and the result one at a time. Furthermore, it lists - only files which were modified from all parents. `-c` implies - `-p`. -+ ---diff-merges=dense-combined::: ---diff-merges=cc::: ---cc::: - With this option the output produced by - `--diff-merges=combined` is further compressed by omitting - uninteresting hunks whose contents in the parents have only - two variants and the merge result picks one of them without - modification. `--cc` implies `-p`. +-- --combined-all-paths:: This flag causes combined diffs (used for merge commits) to @@ -201,14 +217,15 @@ have to use `--diff-algorithm=default` option. part. Maximum width defaults to terminal width, or 80 columns if not connected to a terminal, and can be overridden by `<width>`. The width of the filename part can be limited by - giving another width `<name-width>` after a comma. The width - of the graph part can be limited by using - `--stat-graph-width=<width>` (affects all commands generating - a stat graph) or by setting `diff.statGraphWidth=<width>` - (does not affect `git format-patch`). - By giving a third parameter `<count>`, you can limit the - output to the first `<count>` lines, followed by `...` if - there are more. + giving another width `<name-width>` after a comma or by setting + `diff.statNameWidth=<width>`. The width of the graph part can be + limited by using `--stat-graph-width=<width>` or by setting + `diff.statGraphWidth=<width>`. Using `--stat` or + `--stat-graph-width` affects all commands generating a stat graph, + while setting `diff.statNameWidth` or `diff.statGraphWidth` + does not affect `git format-patch`. + By giving a third parameter `<count>`, you can limit the output to + the first `<count>` lines, followed by `...` if there are more. + These parameters can also be set individually with `--stat-width=<width>`, `--stat-name-width=<name-width>` and `--stat-count=<count>`. @@ -282,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 @@ -297,7 +314,7 @@ ifndef::git-format-patch[] -z:: ifdef::git-log[] - Separate the commits with NULs instead of with new newlines. + Separate the commits with NULs instead of newlines. + Also, when `--raw` or `--numstat` has been given, do not munge pathnames and use NULs as output field terminators. @@ -729,7 +746,7 @@ matches "`fooasdfbar`" and "`foo/bar/baz/asdf`" but not "`foobarx`". --rotate-to=<file>:: Discard the files before the named <file> from the output (i.e. 'skip to'), or move them to the end of the output - (i.e. 'rotate to'). These were invented primarily for use + (i.e. 'rotate to'). These options were invented primarily for the use of the `git difftool` command, and may not be very useful otherwise. @@ -846,6 +863,12 @@ endif::git-format-patch[] --no-prefix:: Do not show any source or destination prefix. +--default-prefix:: + Use the default source and destination prefixes ("a/" and "b/"). + This overrides configuration variables such as `diff.noprefix`, + `diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix` + (see `git-config`(1)). + --line-prefix=<prefix>:: Prepend an additional prefix to every line of output. diff --git a/Documentation/doc-diff b/Documentation/doc-diff index 1694300..fb09e0a 100755 --- a/Documentation/doc-diff +++ b/Documentation/doc-diff @@ -153,7 +153,7 @@ render_tree () { make -j$parallel -C "$tmp/worktree" \ $makemanflags \ GIT_VERSION=omitted \ - SOURCE_DATE_EPOCH=0 \ + GIT_DATE=1970-01-01 \ DESTDIR="$tmp/installed/$dname+" \ install-man && mv "$tmp/installed/$dname+" "$tmp/installed/$dname" diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 622bd84..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:: @@ -43,7 +44,7 @@ the current repository has the same history as the source repository. --update-shallow:: By default when fetching from a shallow repository, `git fetch` refuses refs that require updating - .git/shallow. This option updates .git/shallow and accept such + .git/shallow. This option updates .git/shallow and accepts such refs. --negotiation-tip=<commit|glob>:: @@ -78,6 +79,13 @@ linkgit:git-config[1]. --dry-run:: Show what would be done, without making any changes. +--porcelain:: + Print the output to standard output in an easy-to-parse format for + scripts. See section OUTPUT in linkgit:git-fetch[1] for details. ++ +This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes +precedence over the `fetch.output` config option. + ifndef::git-pull[] --[no-]write-fetch-head:: Write the list of remote refs fetched in the `FETCH_HEAD` @@ -89,7 +97,7 @@ endif::git-pull[] -f:: --force:: - When 'git fetch' is used with `<src>:<dst>` refspec it may + When 'git fetch' is used with `<src>:<dst>` refspec, it may refuse to update the local branch as discussed ifdef::git-pull[] in the `<refspec>` part of the linkgit:git-fetch[1] @@ -194,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 new file mode 100644 index 0000000..f643585 --- /dev/null +++ b/Documentation/fsck-msgids.txt @@ -0,0 +1,180 @@ +`badDate`:: + (ERROR) Invalid date format in an author/committer line. + +`badDateOverflow`:: + (ERROR) Invalid date value in an author/committer line. + +`badEmail`:: + (ERROR) Invalid email format in an author/committer line. + +`badFilemode`:: + (INFO) A tree contains a bad filemode entry. + +`badName`:: + (ERROR) An author/committer name is empty. + +`badObjectSha1`:: + (ERROR) An object has a bad sha1. + +`badParentSha1`:: + (ERROR) A commit object has a bad parent sha1. + +`badTagName`:: + (INFO) A tag has an invalid format. + +`badTimezone`:: + (ERROR) Found an invalid time zone in an author/committer line. + +`badTree`:: + (ERROR) A tree cannot be parsed. + +`badTreeSha1`:: + (ERROR) A tree has an invalid format. + +`badType`:: + (ERROR) Found an invalid object type. + +`duplicateEntries`:: + (ERROR) A tree contains duplicate file entries. + +`emptyName`:: + (WARN) A path contains an empty name. + +`extraHeaderEntry`:: + (IGNORE) Extra headers found after `tagger`. + +`fullPathname`:: + (WARN) A path contains the full path starting with "/". + +`gitattributesBlob`:: + (ERROR) A non-blob found at `.gitattributes`. + +`gitattributesLarge`:: + (ERROR) The `.gitattributes` blob is too large. + +`gitattributesLineLength`:: + (ERROR) The `.gitattributes` blob contains too long lines. + +`gitattributesMissing`:: + (ERROR) Unable to read `.gitattributes` blob. + +`gitattributesSymlink`:: + (INFO) `.gitattributes` is a symlink. + +`gitignoreSymlink`:: + (INFO) `.gitignore` is a symlink. + +`gitmodulesBlob`:: + (ERROR) A non-blob found at `.gitmodules`. + +`gitmodulesLarge`:: + (ERROR) The `.gitmodules` file is too large to parse. + +`gitmodulesMissing`:: + (ERROR) Unable to read `.gitmodules` blob. + +`gitmodulesName`:: + (ERROR) A submodule name is invalid. + +`gitmodulesParse`:: + (INFO) Could not parse `.gitmodules` blob. + +`gitmodulesLarge`; + (ERROR) `.gitmodules` blob is too large to parse. + +`gitmodulesPath`:: + (ERROR) `.gitmodules` path is invalid. + +`gitmodulesSymlink`:: + (ERROR) `.gitmodules` is a symlink. + +`gitmodulesUpdate`:: + (ERROR) Found an invalid submodule update setting. + +`gitmodulesUrl`:: + (ERROR) Found an invalid submodule url. + +`hasDot`:: + (WARN) A tree contains an entry named `.`. + +`hasDotdot`:: + (WARN) A tree contains an entry named `..`. + +`hasDotgit`:: + (WARN) A tree contains an entry named `.git`. + +`largePathname`:: + (WARN) A tree contains an entry with a very long path name. If + the value of `fsck.largePathname` contains a colon, that value + is used as the maximum allowable length (e.g., "warn:10" would + complain about any path component of 11 or more bytes). The + default value is 4096. + +`mailmapSymlink`:: + (INFO) `.mailmap` is a symlink. + +`missingAuthor`:: + (ERROR) Author is missing. + +`missingCommitter`:: + (ERROR) Committer is missing. + +`missingEmail`:: + (ERROR) Email is missing in an author/committer line. + +`missingNameBeforeEmail`:: + (ERROR) Missing name before an email in an author/committer line. + +`missingObject`:: + (ERROR) Missing `object` line in tag object. + +`missingSpaceBeforeDate`:: + (ERROR) Missing space before date in an author/committer line. + +`missingSpaceBeforeEmail`:: + (ERROR) Missing space before the email in an author/committer line. + +`missingTag`:: + (ERROR) Unexpected end after `type` line in a tag object. + +`missingTagEntry`:: + (ERROR) Missing `tag` line in a tag object. + +`missingTaggerEntry`:: + (INFO) Missing `tagger` line in a tag object. + +`missingTree`:: + (ERROR) Missing `tree` line in a commit object. + +`missingType`:: + (ERROR) Invalid type value on the `type` line in a tag object. + +`missingTypeEntry`:: + (ERROR) Missing `type` line in a tag object. + +`multipleAuthors`:: + (ERROR) Multiple author lines found in a commit. + +`nulInCommit`:: + (WARN) Found a NUL byte in the commit object body. + +`nulInHeader`:: + (FATAL) NUL byte exists in the object header. + +`nullSha1`:: + (WARN) Tree contains entries pointing to a null sha1. + +`treeNotSorted`:: + (ERROR) A tree is not properly sorted. + +`unknownType`:: + (ERROR) Found an unknown object type. + +`unterminatedHeader`:: + (FATAL) Missing end-of-line in the object header. + +`zeroPaddedDate`:: + (ERROR) Found a zero padded date in an author/committer line. + +`zeroPaddedFilemode`:: + (WARN) Found a zero padded filemode in a tree. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 11eb70f..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:: @@ -188,7 +188,9 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. forcibly add them again to the index. This is useful after changing `core.autocrlf` configuration or the `text` attribute in order to correct files added with wrong CRLF/LF line endings. - This option implies `-u`. + This option implies `-u`. Lone CR characters are untouched, thus + while a CRLF cleans to LF, a CRCRLF sequence is only partially + cleaned to CRLF. --chmod=(+|-)x:: Override the executable bit of the added files. The executable @@ -196,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 @@ -272,7 +274,7 @@ status:: ------------ staged unstaged path 1: binary nothing foo.png - 2: +403/-35 +1/-1 git-add--interactive.perl + 2: +403/-35 +1/-1 add-interactive.c ------------ + It shows that foo.png has differences from HEAD (but that is @@ -280,7 +282,7 @@ binary so line count cannot be shown) and there is no difference between indexed copy and the working tree version (if the working tree version were also different, 'binary' would have been shown in place of 'nothing'). The -other file, git-add{litdd}interactive.perl, has 403 lines added +other file, add-interactive.c, has 403 lines added and 35 lines deleted if you commit what is in the index, but working tree file has further modifications (one addition and one deletion). @@ -301,7 +303,7 @@ like this: ------------ staged unstaged path 1: binary nothing foo.png -* 2: +403/-35 +1/-1 git-add--interactive.perl +* 2: +403/-35 +1/-1 add-interactive.c ------------ + To remove selection, prefix the input with `-` @@ -346,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 @@ -431,6 +434,13 @@ they will make the patch impossible to apply: * deleting context or removal lines * modifying the contents of context or removal lines +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/add.txt[] + SEE ALSO -------- linkgit:git-status[1] diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 09107fb..624a6e6 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,10 +9,10 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] +'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify] [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] - [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] + [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>] [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [--quoted-cr=<action>] @@ -22,9 +22,11 @@ SYNOPSIS DESCRIPTION ----------- -Splits mail messages in a mailbox into commit log message, -authorship information and patches, and applies them to the -current branch. +Splits mail messages in a mailbox into commit log messages, +authorship information, and patches, and applies them to the +current branch. You could think of it as a reverse operation +of linkgit:git-format-patch[1] run on a branch with a straight +history without merges. OPTIONS ------- @@ -64,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 into 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:: @@ -92,7 +100,7 @@ OPTIONS Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable - `i18n.commitEncoding` can be used to specify project's + `i18n.commitEncoding` can be used to specify the project's preferred encoding if it is not UTF-8). + This was optional in prior versions of git, but now it is the @@ -112,14 +120,11 @@ default. You can use `--no-utf8` to override this. am.threeWay configuration variable. For more information, see am.threeWay in linkgit:git-config[1]. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] --ignore-space-change:: --ignore-whitespace:: ---whitespace=<option>:: +--whitespace=<action>:: -C<n>:: -p<n>:: --directory=<dir>:: @@ -129,18 +134,27 @@ default. You can use `--no-utf8` to override this. 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 automatically. This option allows the user to bypass the automatic detection and specify the patch format that the patch(es) should be interpreted as. Valid formats are mbox, mboxrd, - stgit, stgit-series and hg. + stgit, stgit-series, and hg. -i:: --interactive:: Run interactively. +-n:: +--no-verify:: + By default, the pre-applypatch and applypatch-msg hooks are run. + When any of `--no-verify` or `-n` is given, these are bypassed. + See also linkgit:githooks[5]. + --committer-date-is-author-date:: By default the command records the date from the e-mail message as the commit author date, and uses the time of @@ -187,7 +201,7 @@ default. You can use `--no-utf8` to override this. --abort:: Restore the original branch and abort the patching operation. - Revert contents of files involved in the am operation to their + Revert the contents of files involved in the am operation to their pre-am state. --quit:: @@ -261,9 +275,17 @@ This command can run `applypatch-msg`, `pre-applypatch`, and `post-applypatch` hooks. See linkgit:githooks[5] for more information. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/am.txt[] + SEE ALSO -------- -linkgit:git-apply[1]. +linkgit:git-apply[1], +linkgit:git-format-patch[1]. GIT --- diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index e44a831..5ae8aab 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information SYNOPSIS -------- [verse] -'git annotate' [<options>] <file> [<revision>] +'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file> DESCRIPTION ----------- diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index b6d77f4..9cce68a 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -23,8 +23,8 @@ DESCRIPTION Reads the supplied diff output (i.e. "a patch") and applies it to files. When running from a subdirectory in a repository, patched paths outside the directory are ignored. -With the `--index` option the patch is also applied to the index, and -with the `--cached` option the patch is only applied to the index. +With the `--index` option, the patch is also applied to the index, and +with the `--cached` option, the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a Git repository. @@ -52,7 +52,7 @@ OPTIONS --summary:: Instead of applying the patch, output a condensed summary of information obtained from git diff extended - headers, such as creations, renames and mode changes. + headers, such as creations, renames, and mode changes. Turns off "apply". --check:: @@ -140,7 +140,7 @@ linkgit:git-config[1]). applying a diff generated with `--unified=0`. To bypass these checks use `--unidiff-zero`. + -Note, for the reasons stated above usage of context-free patches is +Note, for the reasons stated above, the usage of context-free patches is discouraged. --apply:: @@ -159,9 +159,9 @@ discouraged. --allow-binary-replacement:: --binary:: - Historically we did not allow binary patch applied + Historically we did not allow binary patch application without an explicit permission from the user, and this - flag was the way to do so. Currently we always allow binary + flag was the way to do so. Currently, we always allow binary patch application, so this is a no-op. --exclude=<path-pattern>:: @@ -208,7 +208,7 @@ behavior: * `warn` outputs warnings for a few such errors, but applies the patch as-is (default). * `fix` outputs warnings for a few such errors, and applies the - patch after fixing them (`strip` is a synonym --- the tool + patch after fixing them (`strip` is a synonym -- the tool used to consider only trailing whitespace characters as errors, and the fix involved 'stripping' them, but modern Gits do more). * `error` outputs warnings for a few such errors, and refuses @@ -257,19 +257,15 @@ the `--unsafe-paths` option to override this safety check. This option has no effect when `--index` or `--cached` is in use. --allow-empty:: - Don't return error for patches containing no diff. This includes + Don't return an error for patches containing no diff. This includes empty patches and patches with commit text only. CONFIGURATION ------------- -apply.ignoreWhitespace:: - Set to 'change' if you want changes in whitespace to be ignored by default. - Set to one of: no, none, never, false if you want changes in - whitespace to be significant. -apply.whitespace:: - When no `--whitespace` flag is given from the command - line, this configuration item is used as the default. +include::includes/cmd-config-section-all.txt[] + +include::config/apply.txt[] SUBMODULES ---------- diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 56989a2..98526f2 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -21,23 +21,25 @@ structure for the named tree, and writes it out to the standard output. If <prefix> is specified it is prepended to the filenames in the archive. -'git archive' behaves differently when given a tree ID versus when -given a commit ID or tag ID. In the first case the current time is -used as the modification time of each file in the archive. In the latter -case the commit time as recorded in the referenced commit object is -used instead. Additionally the commit ID is stored in a global -extended pax header if the tar format is used; it can be extracted -using 'git get-tar-commit-id'. In ZIP files it is stored as a file -comment. +'git archive' behaves differently when given a tree ID as opposed to a +commit ID or tag ID. When a tree ID is provided, the current time is +used as the modification time of each file in the archive. On the +other hand, when a commit ID or tag ID is provided, the commit time as +recorded in the referenced commit object is used instead. +Additionally the commit ID is stored in a global extended pax header +if the tar format is used; it can be extracted using 'git +get-tar-commit-id'. In ZIP files it is stored as a file comment. OPTIONS ------- --format=<fmt>:: - Format of the resulting archive: 'tar' or 'zip'. If this option + Format of the resulting archive. Possible values are `tar`, + `zip`, `tar.gz`, `tgz`, and any format defined using the + configuration option `tar.<format>.command`. If `--format` is not given, and the output file is specified, the format is - inferred from the filename if possible (e.g. writing to "foo.zip" - makes the output to be in the zip format). Otherwise the output + inferred from the filename if possible (e.g. writing to `foo.zip` + makes the output to be in the `zip` format). Otherwise the output format is `tar`. -l:: @@ -84,6 +86,11 @@ cases, write an untracked file and use `--add-file` instead. Look for attributes in .gitattributes files in the working tree as well (see <<ATTRIBUTES>>). +--mtime=<time>:: + Set modification time of archive entries. Without this option + the committer time is used if `<tree-ish>` is a commit or tag, + and the current time if it is a tree. + <extra>:: This can be any options that the archiver backend understands. See next section. @@ -143,17 +150,16 @@ tar.<format>.command:: is executed using the shell with the generated tar file on its standard input, and should produce the final output on its standard output. Any compression-level options will be passed - to the command (e.g., "-9"). An output file with the same - extension as `<format>` will be use this format if no other - format is given. + to the command (e.g., `-9`). + -The "tar.gz" and "tgz" formats are defined automatically and default to -`gzip -cn`. You may override them with custom commands. +The `tar.gz` and `tgz` formats are defined automatically and use the +magic command `git archive gzip` by default, which invokes an internal +implementation of gzip. tar.<format>.remote:: - If true, enable `<format>` for use by remote clients via + If true, enable the format for use by remote clients via linkgit:git-upload-archive[1]. Defaults to false for - user-defined formats, but true for the "tar.gz" and "tgz" + user-defined formats, but true for the `tar.gz` and `tgz` formats. [[ATTRIBUTES]] diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index f3d9566..0bc1657 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -1347,8 +1347,8 @@ author to given a talk and for publishing this paper. References ---------- -- [[[1]]] https://www.nist.gov/sites/default/files/documents/director/planning/report02-3.pdf['The Economic Impacts of Inadequate Infratructure for Software Testing'. Nist Planning Report 02-3], see Executive Summary and Chapter 8. -- [[[2]]] http://www.oracle.com/technetwork/java/codeconvtoc-136057.html['Code Conventions for the Java Programming Language'. Sun Microsystems.] +- [[[1]]] https://web.archive.org/web/20091206032101/http://www.nist.gov/public_affairs/releases/n02-10.htm['Software Errors Cost U.S. Economy $59.5 Billion Annually'. Nist News Release.] See also https://www.nist.gov/system/files/documents/director/planning/report02-3.pdf['The Economic Impacts of Inadequate Infratructure for Software Testing'. Nist Planning Report 02-3], Executive Summary and Chapter 8. +- [[[2]]] https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html['Code Conventions for the Java Programming Language: 1. Introduction'. Sun Microsystems.] - [[[3]]] https://en.wikipedia.org/wiki/Software_maintenance['Software maintenance'. Wikipedia.] - [[[4]]] https://lore.kernel.org/git/7vps5xsbwp.fsf_-_@assigned-by-dhcp.cox.net/[Junio C Hamano. 'Automated bisect success story'.] - [[[5]]] https://lwn.net/Articles/317154/[Christian Couder. 'Fully automated bisecting with "git bisect run"'. LWN.net.] diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index fbb39fb..82f944d 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,17 +16,17 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>] - [--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) git bisect replay <logfile> git bisect log - git bisect run <cmd>... + git bisect run <cmd> [<arg>...] git bisect help This command uses a binary search algorithm to find which commit in @@ -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 @@ -204,9 +206,14 @@ as an alternative to `visualize`): $ git bisect visualize ------------ -If the `DISPLAY` environment variable is not set, 'git log' is used -instead. You can also give command-line options such as `-p` and -`--stat`. +Git detects a graphical environment through various environment variables: +`DISPLAY`, which is set in X Window System environments on Unix systems. +`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions. +`MSYSTEM`, which is set under Msys2 and Git for Windows. +`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions. + +If none of these environment variables is set, 'git log' is used instead. +You can also give command-line options such as `-p` and `--stat`. ------------ $ git bisect visualize --stat @@ -294,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 @@ -357,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 d7a46cc..b1d7fb5 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -12,7 +12,7 @@ SYNOPSIS [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--ignore-rev <rev>] [--ignore-revs-file <file>] [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>] - [<rev> | --contents <file> | --reverse <rev>..<rev>] [--] <file> + [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <file> DESCRIPTION ----------- @@ -77,7 +77,7 @@ include::blame-options.txt[] -e:: --show-email:: - Show the author email instead of author name (Default: off). + Show the author email instead of the author name (Default: off). This can also be controlled via the `blame.showEmail` config option. @@ -100,7 +100,7 @@ When neither `--porcelain` nor `--incremental` option is specified, `git blame` will output annotation for each line with: - abbreviated object name for the commit the line came from; -- author ident (by default author name and date, unless `-s` or `-e` +- author ident (by default the author name and date, unless `-s` or `-e` is specified); and - line number @@ -128,7 +128,7 @@ at least once for each commit: - the filename in the commit that the line is attributed to. - the first line of the commit log message ("summary"). -The contents of the actual line is output after the above +The contents of the actual line are output after the above header, prefixed by a TAB. This is to allow adding more header elements later. @@ -170,7 +170,7 @@ which limits the annotation to the body of the `hello` subroutine. When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision -range specifiers similar to 'git rev-list': +range specifiers similar to 'git rev-list': git blame v2.6.18.. -- foo git blame --since=3.weeks -- foo @@ -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. @@ -241,6 +241,12 @@ MAPPING AUTHORS See linkgit:gitmailmap[5]. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/blame.txt[] SEE ALSO -------- diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index ae82378..0b08442 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -116,13 +116,17 @@ OPTIONS -f:: --force:: - Reset <branchname> to <startpoint>, even if <branchname> exists + Reset <branchname> to <start-point>, even if <branchname> exists already. Without `-f`, 'git branch' refuses to change an existing branch. In combination with `-d` (or `--delete`), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit. In combination with `-m` (or `--move`), allow renaming the branch even if the new branch name already exists, the same applies for `-c` (or `--copy`). ++ +Note that 'git branch -f <branchname> [<start-point>]', even with '-f', +refuses to change an existing branch `<branchname>` that is checked out +in another worktree linked to the same repository. -m:: --move:: @@ -152,6 +156,10 @@ OPTIONS --ignore-case:: Sorting and filtering branches are case insensitive. +--omit-empty:: + Do not print a newline after formatted refs where the format expands + to the empty string. + --column[=<options>]:: --no-column:: Display branch listing in columns. See configuration variable @@ -304,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 @@ -316,7 +325,7 @@ superproject's "origin/main", but tracks the submodule's "origin/main". multiple times, in which case the last key becomes the primary key. The keys supported are the same as those in `git for-each-ref`. Sort order defaults to the value configured for the - `branch.sort` variable if exists, or to sorting based on the + `branch.sort` variable if it exists, or to sorting based on the full refname (including `refs/...` prefix). This lists detached HEAD (if present) first, then local branches and finally remote-tracking branches. See linkgit:git-config[1]. @@ -336,6 +345,10 @@ CONFIGURATION `--list` is used or implied. The default is to use a pager. See linkgit:git-config[1]. +include::includes/cmd-config-section-rest.txt[] + +include::config/branch.txt[] + EXAMPLES -------- diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt index d8817bf..112658b 100644 --- a/Documentation/git-bugreport.txt +++ b/Documentation/git-bugreport.txt @@ -8,14 +8,17 @@ 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 ----------- -Captures information about the user's machine, Git client, and repository state, -as well as a form requesting information about the behavior the user observed, -into a single text file which the user can then share, for example to the Git -mailing list, in order to report an observed bug. +Collects information about the user's machine, Git client, and repository +state, in addition to a form requesting information about the behavior the +user observed, and stores it in a single text file which the user can then +share, for example to the Git mailing list, in order to report an observed +bug. The following information is requested from the user: @@ -31,6 +34,10 @@ The following information is captured automatically: - A list of enabled hooks - $SHELL +Additional information may be gathered into a separate zip archive using the +`--diagnose` option, and can be attached alongside the bugreport document to +provide additional context to readers. + This tool is invoked via the typical Git setup process, which means that in some cases, it might not be able to launch - for example, if a relevant config file is unreadable. In this kind of scenario, it may be helpful to manually gather @@ -45,9 +52,25 @@ 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>'. ++ +Without `mode` specified, the diagnostic archive will contain the default set of +statistics reported by `git diagnose`. An optional `mode` value may be specified +to change which information is included in the archive. See +linkgit:git-diagnose[1] for the list of valid values for `mode` and details +about their usage. GIT --- diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 7685b57..3ab42a1 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,7 +9,7 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] +'git bundle' create [-q | --quiet | --progress] [--version=<version>] <file> <git-rev-list-args> 'git bundle' verify [-q | --quiet] <file> 'git bundle' list-heads <file> [<refname>...] @@ -42,7 +42,7 @@ BUNDLE FORMAT Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a header indicating what references are contained within the bundle. -Like the the packed archive format itself bundles can either be +Like the packed archive format itself bundles can either be self-contained, or be created using exclusions. See the "OBJECT PREREQUISITES" section below. @@ -56,10 +56,8 @@ using "thin packs", bundles created using exclusions are smaller in size. That they're "thin" under the hood is merely noted here as a curiosity, and as a reference to other documentation. -See link:technical/bundle-format.html[the `bundle-format` -documentation] for more details and the discussion of "thin pack" in -link:technical/pack-format.html[the pack format documentation] for -further details. +See linkgit:gitformat-bundle[5] for more details and the discussion of +"thin pack" in linkgit:gitformat-pack[5] for further details. OPTIONS ------- @@ -68,7 +66,7 @@ create [options] <file> <git-rev-list-args>:: Used to create a bundle named 'file'. This requires the '<git-rev-list-args>' arguments to define the bundle contents. 'options' contains the options specific to the 'git bundle create' - subcommand. + subcommand. If 'file' is `-`, the bundle is written to stdout. verify <file>:: Used to check that a bundle file is valid and will apply @@ -77,14 +75,15 @@ verify <file>:: commits exist and are fully linked in the current repository. Then, 'git bundle' prints a list of missing commits, if any. Finally, information about additional capabilities, such as "object - filter", is printed. See "Capabilities" in link:technical/bundle-format.html + filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5] for more information. The exit code is zero for success, but will - be nonzero if the bundle file is invalid. + be nonzero if the bundle file is invalid. If 'file' is `-`, the + bundle is read from stdin. list-heads <file>:: Lists the references defined in the bundle. If followed by a list of references, only references matching those given are - printed out. + printed out. If 'file' is `-`, the bundle is read from stdin. unbundle <file>:: Passes the objects in the bundle to 'git index-pack' @@ -92,6 +91,7 @@ unbundle <file>:: defined references. If a list of references is given, only references matching those in the list are printed. This command is really plumbing, intended to be called only by 'git fetch'. + If 'file' is `-`, the bundle is read from stdin. <git-rev-list-args>:: A list of arguments, acceptable to 'git rev-parse' and @@ -117,22 +117,6 @@ unbundle <file>:: is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---all-progress:: - When --stdout is specified then progress report is - displayed during the object count and compression phases - but inhibited during the write-out phase. The reason is - that in some cases the output stream is directly linked - to another command which may wish to display progress - status of its own as it processes incoming pack data. - This flag is like --progress except that it forces progress - report for the write-out phase as well even if --stdout is - used. - ---all-progress-implied:: - This is used to imply --all-progress whenever progress display - is activated. Unlike --all-progress this flag doesn't actually - force any progress display by itself. - --version=<version>:: Specify the bundle version. Version 2 is the older format and can only be used with SHA-1 repositories; the newer version 3 contains capabilities that @@ -337,6 +321,11 @@ You can also see what references it offers: $ git ls-remote mybundle ---------------- +FILE FORMAT +----------- + +See linkgit:gitformat-bundle[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 24a811f..bd95a6c 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -3,8 +3,7 @@ git-cat-file(1) NAME ---- -git-cat-file - Provide content or type and size information for repository objects - +git-cat-file - Provide contents or details of repository objects SYNOPSIS -------- @@ -12,25 +11,24 @@ SYNOPSIS 'git cat-file' <type> <object> 'git cat-file' (-e | -p) <object> 'git cat-file' (-t | -s) [--allow-unknown-type] <object> -'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] - [--buffer] [--follow-symlinks] [--unordered] - [--textconv | --filters] 'git cat-file' (--textconv | --filters) [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] + [--buffer] [--follow-symlinks] [--unordered] + [--textconv | --filters] [-Z] DESCRIPTION ----------- -In its first form, the command provides the content or the type of an object in -the repository. The type is required unless `-t` or `-p` is used to find the -object type, or `-s` is used to find the object size, or `--textconv` or -`--filters` is used (which imply type "blob"). - -In the second form, a list of objects (separated by linefeeds) is provided on -stdin, and the SHA-1, type, and size of each object is printed on stdout. The -output format can be overridden using the optional `<format>` argument. If -either `--textconv` or `--filters` was specified, the input is expected to -list the object names followed by the path name, separated by a single -whitespace, so that the appropriate drivers can be determined. +Output the contents or other properties such as size, type or delta +information of one or more objects. + +This command can operate in two modes, depending on whether an option +from the `--batch` family is specified. + +In non-batch mode, the command provides information on an object +named on the command line. + +In batch mode, arguments are read from standard input. OPTIONS ------- @@ -45,12 +43,14 @@ OPTIONS -s:: Instead of the content, show the object size identified by - `<object>`. + `<object>`. If used with `--use-mailmap` option, will show + the size of updated object after replacing idents using the + mailmap mechanism. -e:: Exit with zero status if `<object>` exists and is a valid - object. If `<object>` is of an invalid format exit with non-zero and - emits an error on stderr. + object. If `<object>` is of an invalid format, exit with non-zero + status and emit an error on stderr. -p:: Pretty-print the contents of `<object>` based on its type. @@ -63,6 +63,12 @@ OPTIONS or to ask for a "blob" with `<object>` being a tag object that points at it. +--[no-]mailmap:: +--[no-]use-mailmap:: + Use mailmap file to map author, committer and tagger names + and email addresses to canonical real names and email addresses. + See linkgit:git-shortlog[1]. + --textconv:: Show the content as transformed by a textconv filter. In this case, `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>` in @@ -83,26 +89,54 @@ OPTIONS --batch:: --batch=<format>:: Print object information and contents for each object provided - on stdin. May not be combined with any other options or arguments - except `--textconv` or `--filters`, in which case the input lines - also need to specify the path, separated by whitespace. See the - section `BATCH OUTPUT` below for details. + on stdin. May not be combined with any other options or arguments + except `--textconv`, `--filters`, or `--use-mailmap`. ++ +-- + * When used with `--textconv` or `--filters`, the input lines + must specify the path, separated by whitespace. See the section + `BATCH OUTPUT` below for details. + + * When used with `--use-mailmap`, for commit and tag objects, the + contents part of the output shows the identities replaced using the + mailmap mechanism, while the information part of the output shows + the size of the object as if it actually recorded the replacement + identities. +-- --batch-check:: --batch-check=<format>:: - Print object information for each object provided on stdin. May - not be combined with any other options or arguments except - `--textconv` or `--filters`, in which case the input lines also - need to specify the path, separated by whitespace. See the - section `BATCH OUTPUT` below for details. + Print object information for each object provided on stdin. May not be + combined with any other options or arguments except `--textconv`, `--filters` + or `--use-mailmap`. ++ +-- + * When used with `--textconv` or `--filters`, the input lines must + specify the path, separated by whitespace. See the section + `BATCH OUTPUT` below for details. + + * When used with `--use-mailmap`, for commit and tag objects, the + printed object information shows the size of the object as if the + identities recorded in it were replaced by the mailmap mechanism. +-- --batch-command:: --batch-command=<format>:: Enter a command mode that reads commands and arguments from stdin. May - only be combined with `--buffer`, `--textconv` or `--filters`. In the - case of `--textconv` or `--filters`, the input lines also need to specify - the path, separated by whitespace. See the section `BATCH OUTPUT` below - for details. + only be combined with `--buffer`, `--textconv`, `--use-mailmap` or + `--filters`. ++ +-- + * When used with `--textconv` or `--filters`, the input lines must + specify the path, separated by whitespace. See the section + `BATCH OUTPUT` below for details. + + * When used with `--use-mailmap`, for commit and tag objects, the + `contents` command shows the identities replaced using the + mailmap mechanism, while the `info` command shows the size + of the object as if it actually recorded the replacement + identities. +-- + `--batch-command` recognizes the following commands: + @@ -207,6 +241,17 @@ respectively print: /etc/passwd -- +-Z:: + Only meaningful with `--batch`, `--batch-check`, or + `--batch-command`; input and output is NUL-delimited instead of + newline-delimited. + +-z:: + Only meaningful with `--batch`, `--batch-check`, or + `--batch-command`; input is NUL-delimited instead of + newline-delimited. This option is deprecated in favor of + `-Z` as the output can otherwise be ambiguous. + OUTPUT ------ @@ -343,6 +388,11 @@ notdir SP <size> LF is printed when, during symlink resolution, a file is used as a directory name. +Alternatively, when `-Z` is passed, the line feeds in any of the above examples +are replaced with NUL terminators. This ensures that output will be parsable if +the output itself would contain a linefeed and is thus recommended for +scripting purposes. + CAVEATS ------- diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 84f41a8..cb5a6c8 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -9,8 +9,8 @@ git-check-attr - Display gitattributes information SYNOPSIS -------- [verse] -'git check-attr' [-a | --all | <attr>...] [--] <pathname>... -'git check-attr' --stdin [-z] [-a | --all | <attr>...] +'git check-attr' [--source <tree-ish>] [-a | --all | <attr>...] [--] <pathname>... +'git check-attr' --stdin [-z] [--source <tree-ish>] [-a | --all | <attr>...] DESCRIPTION ----------- @@ -29,13 +29,18 @@ OPTIONS --stdin:: Read pathnames from the standard input, one per line, - instead of from the command-line. + instead of from the command line. -z:: The output format is modified to be machine-parsable. If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. +--source=<tree-ish>:: + Check attributes against the specified tree-ish. It is common to + specify the source tree by naming a commit, branch, or tag associated + with it. + \--:: Interpret all preceding arguments as attributes and all following arguments as path names. @@ -55,7 +60,7 @@ unless `-z` is in effect, in which case NUL is used as delimiter: <path> is the path of a file being queried, <attribute> is an attribute -being queried and <info> can be either: +being queried, and <info> can be either: 'unspecified';; when the attribute is not defined for the path. 'unset';; when the attribute is defined as false. diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 2892799..3e3b4e3 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -50,7 +50,7 @@ linkgit:gitignore[5]. with a NUL character instead of a linefeed character. -n, --non-matching:: - Show given paths which don't match any pattern. This only + Show given paths which don't match any pattern. This only makes sense when `--verbose` is enabled, otherwise it would not be possible to distinguish between paths which match a pattern and those which don't. diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index ee6a414..2aacfd1 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -48,7 +48,7 @@ Git imposes the following rules on how references are named: . They cannot begin or end with a slash `/` or contain multiple consecutive slashes (see the `--normalize` option below for an - exception to this rule) + exception to this rule). . They cannot end with a dot `.`. @@ -85,7 +85,7 @@ The rule `git check-ref-format --branch $name` implements may be stricter than what `git check-ref-format refs/heads/$name` says (e.g. a dash may appear at the beginning of a ref component, but it is explicitly forbidden at the beginning of a branch name). -When run with `--branch` option in a repository, the input is first +When run with the `--branch` option in a repository, the input is first expanded for the ``previous checkout syntax'' `@{-n}`. For example, `@{-1}` is a way to refer the last thing that was checked out using "git switch" or "git checkout" operation. diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 01dbd5c..faf8d6c 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -18,7 +18,7 @@ SYNOPSIS DESCRIPTION ----------- -Will copy all files listed from the index to the working directory +Copies all listed files from the index to the working directory (not overwriting existing files). OPTIONS @@ -53,11 +53,11 @@ OPTIONS --stage=<number>|all:: Instead of checking out unmerged entries, copy out the - files from named stage. <number> must be between 1 and 3. + files from the named stage. <number> must be between 1 and 3. Note: --stage=all automatically implies --temp. --temp:: - Instead of copying the files to the working directory + Instead of copying the files to the working directory, write the content to temporary files. The temporary name associations will be written to stdout. @@ -66,8 +66,8 @@ OPTIONS set. --stdin:: - Instead of taking list of paths from the command line, - read list of paths from the standard input. Paths are + Instead of taking a list of paths from the command line, + read the list of paths from the standard input. Paths are separated by LF (i.e. one path per line) by default. -z:: diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 9f37e22..8bdfa54 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -12,8 +12,10 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] --detach [<branch>] 'git checkout' [-q] [-f] [-m] [--detach] <commit> 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>... -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul] +'git checkout' [-f] <tree-ish> [--] <pathspec>... +'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul] +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>... +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] DESCRIPTION @@ -41,7 +43,7 @@ $ git checkout -b <branch> --track <remote>/<branch> You could omit `<branch>`, in which case the command degenerates to "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, -if exists, for the current branch. +if it exists, for the current branch. 'git checkout' -b|-B <new-branch> [<start-point>]:: @@ -61,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>:: @@ -146,14 +150,16 @@ on your side branch as `theirs` (i.e. "one contributor's work on top of it"). -b <new-branch>:: - Create a new branch named `<new-branch>` and start it at - `<start-point>`; see linkgit:git-branch[1] for details. + Create a new branch named `<new-branch>`, start it at + `<start-point>`, and check the resulting branch out; + see linkgit:git-branch[1] for details. -B <new-branch>:: - Creates the branch `<new-branch>` and start it at `<start-point>`; - if it already exists, then reset it to `<start-point>`. This is - equivalent to running "git branch" with "-f"; see - linkgit:git-branch[1] for details. + Creates the branch `<new-branch>`, start it at `<start-point>`; + if it already exists, then reset it to `<start-point>`. And then + check the resulting branch out. This is equivalent to running + "git branch" with "-f" followed by "git checkout" of that branch; + see linkgit:git-branch[1] for details. -t:: --track[=(direct|inherit)]:: @@ -211,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 @@ -258,7 +264,8 @@ and mark the resolved paths with `git add` (or `git rm` if the merge should result in deletion of the path). + When checking out paths from the index, this option lets you recreate -the conflicted merge in the specified paths. +the conflicted merge in the specified paths. This option cannot be +used when checking out paths from a tree-ish. + When switching branches with `--merge`, staged changes may be lost. @@ -477,18 +484,15 @@ before that happens. If we have not yet moved away from commit `f`, any of these will create a reference to it: ------------ -$ git checkout -b foo <1> -$ git branch foo <2> -$ git tag foo <3> +$ git checkout -b foo # or "git switch -c foo" <1> +$ git branch foo <2> +$ git tag foo <3> ------------ - <1> creates a new branch `foo`, which refers to commit `f`, and then updates `HEAD` to refer to branch `foo`. In other words, we'll no longer be in detached `HEAD` state after this command. - <2> similarly creates a new branch `foo`, which refers to commit `f`, but leaves `HEAD` detached. - <3> creates a new tag `foo`, which refers to commit `f`, leaving `HEAD` detached. @@ -517,89 +521,101 @@ to checkout these paths out of the index. EXAMPLES -------- -. The following sequence checks out the `master` branch, reverts - the `Makefile` to two revisions back, deletes `hello.c` by - mistake, and gets it back from the index. -+ +=== 1. Paths + +The following sequence checks out the `master` branch, reverts +the `Makefile` to two revisions back, deletes `hello.c` by +mistake, and gets it back from the index. + ------------ $ git checkout master <1> $ git checkout master~2 Makefile <2> $ rm -f hello.c $ git checkout hello.c <3> ------------ -+ <1> switch branch <2> take a file out of another commit <3> restore `hello.c` from the index -+ + If you want to check out _all_ C source files out of the index, you can say -+ + ------------ $ git checkout -- '*.c' ------------ -+ + Note the quotes around `*.c`. The file `hello.c` will also be checked out, even though it is no longer in the working tree, because the file globbing is used to match entries in the index (not in the working tree by the shell). -+ + If you have an unfortunate branch that is named `hello.c`, this step would be confused as an instruction to switch to that branch. You should instead write: -+ + ------------ $ git checkout -- hello.c ------------ -. After working in the wrong branch, switching to the correct - branch would be done using: -+ +=== 2. Merge + +After working in the wrong branch, switching to the correct +branch would be done using: + ------------ $ git checkout mytopic ------------ -+ + However, your "wrong" branch and correct `mytopic` branch may differ in files that you have modified locally, in which case the above checkout would fail like this: -+ + ------------ $ git checkout mytopic error: You have local changes to 'frotz'; not switching branches. ------------ -+ + You can give the `-m` flag to the command, which would try a three-way merge: -+ + ------------ $ git checkout -m mytopic Auto-merging frotz ------------ -+ + After this three-way merge, the local modifications are _not_ registered in your index file, so `git diff` would show you what changes you made since the tip of the new branch. -. When a merge conflict happens during switching branches with - the `-m` option, you would see something like this: -+ +=== 3. Merge conflict + +When a merge conflict happens during switching branches with +the `-m` option, you would see something like this: + ------------ $ git checkout -m mytopic Auto-merging frotz ERROR: Merge conflict in frotz fatal: merge program failed ------------ -+ + At this point, `git diff` shows the changes cleanly merged as in the previous example, as well as the changes in the conflicted files. Edit and resolve the conflict and mark it resolved with `git add` as usual: -+ + ------------ $ edit frotz $ git add frotz ------------ +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/checkout.txt[] + SEE ALSO -------- linkgit:git-switch[1], diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 78dcc91..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. @@ -156,10 +172,7 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] SEQUENCER SUBCOMMANDS --------------------- @@ -222,7 +235,7 @@ again, this time exercising more care about matching up context lines. ------------ $ git cherry-pick topic^ <1> $ git diff <2> -$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick --abort <3> $ git cherry-pick -Xpatience topic^ <4> ------------ <1> apply the change that would be shown by `git show topic^`. diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index a7f309d..fd17165 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...] DESCRIPTION ----------- @@ -20,16 +20,16 @@ Normally, only files unknown to Git are removed, but if the `-x` option is specified, ignored files are also removed. This can, for example, be useful to remove all build products. -If any optional `<path>...` arguments are given, only those paths -are affected. +If any optional `<pathspec>...` arguments are given, only those paths +that match the pathspec are affected. OPTIONS ------- -d:: - Normally, when no <path> is specified, git clean will not + Normally, when no <pathspec> is specified, git clean will not recurse into untracked directories to avoid removing too much. Specify -d to have it recurse into such directories as well. - If any paths are specified, -d is irrelevant; all untracked + If a <pathspec> is specified, -d is irrelevant; all untracked files matching the specified paths (with exceptions for nested git directories mentioned under `--force`) will be removed. @@ -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:: @@ -103,7 +107,7 @@ filter by pattern:: This shows the files and directories to be deleted and issues an "Input ignore patterns>>" prompt. You can input space-separated patterns to exclude files and directories from deletion. - E.g. "*.c *.h" will excludes files end with ".c" and ".h" from + E.g. "*.c *.h" will exclude files ending with ".c" and ".h" from deletion. When you are satisfied with the filtered result, press ENTER (empty) back to the main menu. @@ -127,12 +131,19 @@ ask each:: quit:: - This lets you quit without do cleaning. + This lets you quit without doing any cleaning. help:: Show brief usage of interactive git-clean. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/clean.txt[] + SEE ALSO -------- linkgit:gitignore[5] diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 632bd13..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. + @@ -58,18 +58,23 @@ never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular Git transport instead. + +If the repository's `$GIT_DIR/objects` has symbolic links or is a +symbolic link, the clone will fail. This is a security measure to +prevent the unintentional copying of files by dereferencing the symbolic +links. ++ *NOTE*: this operation can race with concurrent modification to the 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 @@ -96,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. @@ -110,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 @@ -121,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 @@ -166,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 @@ -195,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 @@ -234,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 @@ -274,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 @@ -290,39 +295,52 @@ 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=`{empty}__<uri>__:: + Before fetching from the remote, fetch a bundle from the given + _<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`. + :git-clone: 1 include::urls.txt[] @@ -363,6 +381,15 @@ $ cd my-linux $ git clone --bare -l /home/proj/.git /pub/scm/proj.git ------------ +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/init.txt[] + +include::config/clone.txt[] + GIT --- diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index 6cea9ab..1843164 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7 v2.4.8 v2.4.9 ------------ +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/column.txt[] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index e1f48c9..903b168 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -10,7 +10,10 @@ SYNOPSIS -------- [verse] 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress] -'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress] +'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> DESCRIPTION @@ -142,6 +145,18 @@ $ git show-ref -s | git commit-graph write --stdin-commits $ git rev-parse HEAD | git commit-graph write --stdin-commits --append ------------------------------------------------ +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/commitgraph.txt[] + + +FILE FORMAT +----------- + +see linkgit:gitformat-commit-graph[5]. GIT --- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 6c60bf9..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]. -- @@ -541,7 +543,7 @@ DISCUSSION ---------- Though not required, it's a good idea to begin the commit message -with a single short (less than 50 character) line summarizing the +with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. @@ -557,6 +559,10 @@ The editor used to edit the commit log message will be chosen from the `VISUAL` environment variable, or the `EDITOR` environment variable (in that order). See linkgit:git-var[1] for details. +include::includes/cmd-config-section-rest.txt[] + +include::config/commit.txt[] + HOOKS ----- This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 9376e39..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:: @@ -201,7 +213,7 @@ Valid `<type>`'s include: 1073741824 upon input. - 'bool-or-int': canonicalize according to either 'bool' or 'int', as described above. -- 'path': canonicalize by adding a leading `~` to the value of `$HOME` and +- 'path': canonicalize by expanding a leading `~` to the value of `$HOME` and `~user` to the home directory for the specified user. This specifier has no effect when setting the value (but you can use `git config section.variable ~/` from the command line to let your shell do the expansion.) @@ -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 ------------- @@ -297,23 +310,20 @@ The default is to use a pager. FILES ----- -If not set explicitly with `--file`, there are four files where -'git config' will search for configuration options: +By default, 'git config' will read configuration options from multiple +files: $(prefix)/etc/gitconfig:: System-wide configuration file. $XDG_CONFIG_HOME/git/config:: - Second user-specific configuration file. If $XDG_CONFIG_HOME is not set - or empty, `$HOME/.config/git/config` will be used. Any single-valued - variable set in this file will be overwritten by whatever is in - `~/.gitconfig`. It is a good idea not to create this file if - you sometimes use older versions of Git, as support for this - file was added fairly recently. - ~/.gitconfig:: - User-specific configuration file. Also called "global" - configuration file. + User-specific configuration files. When the XDG_CONFIG_HOME environment + variable is not set or empty, $HOME/.config/ is used as + $XDG_CONFIG_HOME. ++ +These are also called "global" configuration files. If both files exist, both +files are read in the order given above. $GIT_DIR/config:: Repository specific configuration file. @@ -322,28 +332,80 @@ $GIT_DIR/config.worktree:: This is optional and is only searched when `extensions.worktreeConfig` is present in $GIT_DIR/config. -If no further options are given, all reading options will read all of these -files that are available. If the global or the system-wide configuration -file are not available they will be ignored. If the repository configuration -file is not available or readable, 'git config' will exit with a non-zero -error code. However, in neither case will an error message be issued. +You may also provide additional configuration parameters when running any +git command by using the `-c` option. See linkgit:git[1] for details. + +Options will be read from all of these files that are available. If the +global or the system-wide configuration files are missing or unreadable they +will be ignored. If the repository configuration file is missing or unreadable, +'git config' will exit with a non-zero error code. An error message is produced +if the file is unreadable, but not if it is missing. The files are read in the order given above, with last value found taking precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. -You may override individual configuration parameters when running any git -command by using the `-c` option. See linkgit:git[1] for details. - -All writing options will per default write to the repository specific +By default, options are only written to the repository specific configuration file. Note that this also affects options like `--replace-all` and `--unset`. *'git config' will only ever change one file at a time*. -You can override these rules using the `--global`, `--system`, -`--local`, `--worktree`, and `--file` command-line options; see -<<OPTIONS>> above. +You can limit which configuration sources are read from or written to by +specifying the path of a file with the `--file` option, or by specifying a +configuration scope with `--system`, `--global`, `--local`, or `--worktree`. +For more, see <<OPTIONS>> above. + +[[SCOPES]] +SCOPES +------ + +Each configuration source falls within a configuration scope. The scopes +are: + +system:: + $(prefix)/etc/gitconfig + +global:: + $XDG_CONFIG_HOME/git/config ++ +~/.gitconfig + +local:: + $GIT_DIR/config + +worktree:: + $GIT_DIR/config.worktree + +command:: + GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>> + below) ++ +the `-c` option + +With the exception of 'command', each scope corresponds to a command line +option: `--system`, `--global`, `--local`, `--worktree`. + +When reading options, specifying a scope will only read options from the +files within that scope. When writing options, specifying a scope will write +to the files within that scope (instead of the repository specific +configuration file). See <<OPTIONS>> above for a complete description. + +Most configuration options are respected regardless of the scope it is +defined in, but some options are only respected in certain scopes. See the +respective option's documentation for the full details. + +Protected configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +Protected configuration refers to the 'system', 'global', and 'command' scopes. +For security reasons, certain options are only respected when they are +specified in protected configuration, and ignored otherwise. +Git treats these scopes as if they are controlled by the user or a trusted +administrator. This is because an attacker who controls these scopes can do +substantial harm without using Git, so it is assumed that the user's environment +protects these scopes against attackers. +[[ENVIRONMENT]] ENVIRONMENT ----------- diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index cb9b4d2..97f9f12 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -This counts the number of unpacked object files and disk space consumed by +Counts the number of unpacked object files and disk space consumed by them, to help you decide when it is a good time to repack. @@ -20,7 +20,7 @@ OPTIONS ------- -v:: --verbose:: - Report in more detail: + Provide more detailed reports: + count: the number of loose objects + @@ -33,7 +33,7 @@ size-pack: disk space consumed by the packs, in KiB (unless -H is specified) prune-packable: the number of loose objects that are also present in the packs. These objects could be pruned using `git prune-packed`. + -garbage: the number of files in object database that are neither valid loose +garbage: the number of files in the object database that are neither valid loose objects nor valid packs + size-garbage: disk space consumed by garbage files, in KiB (unless -H is diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 01e1c21..650a15a 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- [verse] -'git credential-cache{litdd}daemon' [--debug] <socket> +'git credential-cache{litdd}daemon' [--debug] <socket-path> DESCRIPTION ----------- @@ -16,7 +16,7 @@ DESCRIPTION NOTE: You probably don't want to invoke this command yourself; it is started automatically when you use linkgit:git-credential-cache[1]. -This command listens on the Unix domain socket specified by `<socket>` +This command listens on the Unix domain socket specified by `<socket-path>` for `git-credential-cache` clients. Clients may store and retrieve credentials. Each credential is held for a timeout specified by the client; once no credentials are held, the daemon exits. diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index 0216c18..487cc55 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -14,10 +14,13 @@ git config credential.helper 'cache [<options>]' DESCRIPTION ----------- -This command caches credentials in memory for use by future Git -programs. The stored credentials never touch the disk, and are forgotten -after a configurable timeout. The cache is accessible over a Unix -domain socket, restricted to the current user by filesystem permissions. +This command caches credentials for use by future Git programs. +The stored credentials are kept in memory of the cache-daemon +process (instead of being written to a file) and are forgotten after a +configurable timeout. Credentials are forgotten sooner if the +cache-daemon dies, for example if the system restarts. The cache +is accessible over a Unix domain socket, restricted to the current +user by filesystem permissions. You probably don't want to invoke this command directly; it is meant to be used as a credential helper by other parts of Git. See @@ -69,10 +72,10 @@ $ git push http://example.com/repo.git ------------------------------------ You can provide options via the credential.helper configuration -variable (this example drops the cache time to 5 minutes): +variable (this example increases the cache time to 1 hour): ------------------------------------------------------- -$ git config credential.helper 'cache --timeout=300' +$ git config credential.helper 'cache --timeout=3600' ------------------------------------------------------- GIT diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 76b0798..71864a8 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -33,7 +33,7 @@ OPTIONS Use `<path>` to lookup and store credentials. The file will have its filesystem permissions set to prevent other users on the system - from reading it, but will not be encrypted or otherwise + from reading it, but it will not be encrypted or otherwise protected. If not specified, credentials will be searched for from `~/.git-credentials` and `$XDG_CONFIG_HOME/git/credentials`, and credentials will be written to `~/.git-credentials` if it exists, or diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index f186730..918a0aa 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -39,7 +39,7 @@ for later use. If the action is `reject`, git-credential will send the description to any configured credential helpers, which may erase any stored -credential matching the description. +credentials matching the description. If the action is `approve` or `reject`, no output should be emitted. @@ -94,7 +94,7 @@ unlocked) before it returned `password=secr3t`. that `git credential` will ask for a new password in its next invocation. In either case, `git credential` should be fed with the credential description obtained from step (2) (which also - contain the ones provided in step (1)). + contains the fields provided in step (1)). [[IOFMT]] INPUT/OUTPUT FORMAT @@ -113,7 +113,13 @@ separated by an `=` (equals) sign, followed by a newline. The key may contain any bytes except `=`, newline, or NUL. The value may contain any bytes except newline or NUL. -In both cases, all bytes are treated as-is (i.e., there is no quoting, +Attributes with keys that end with C-style array brackets `[]` can have +multiple values. Each instance of a multi-valued attribute forms an +ordered list of values - the order of the repeated attributes defines +the order of the values. An empty multi-valued attribute (`key[]=\n`) +acts to clear any previous entries and reset the list. + +In all cases, all bytes are treated as-is (i.e., there is no quoting, and one cannot transmit a value with newline or NUL in it). The list of attributes is terminated by a blank line or end-of-file. @@ -144,6 +150,18 @@ Git understands the following attributes: The credential's password, if we are asking it to be stored. +`password_expiry_utc`:: + + Generated passwords such as an OAuth access token may have an expiry date. + When reading credentials from helpers, `git credential fill` ignores expired + passwords. Represented as Unix time UTC, seconds since 1970. + +`oauth_refresh_token`:: + + An OAuth refresh token may accompany a password that is an OAuth access + token. Helpers must treat this attribute as confidential like the password + attribute. Git itself has no special behaviour for this attribute. + `url`:: When this special attribute is read by `git credential`, the @@ -160,6 +178,19 @@ empty string. Components which are missing from the URL (e.g., there is no username in the example above) will be left unset. +`wwwauth[]`:: + + When an HTTP response is received by Git that includes one or more + 'WWW-Authenticate' authentication headers, these will be passed by Git + to credential helpers. ++ +Each 'WWW-Authenticate' header value is passed as a multi-valued +attribute 'wwwauth[]', where the order of the attributes is the same as +they appear in the HTTP response. This attribute is 'one-way' from Git +to pass additional information to credential helpers. + +Unrecognised attributes are silently discarded. + GIT --- Part of the linkgit:git[1] suite 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 4dc57ed..4c475ef 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -63,11 +63,10 @@ Print version information and exit Print usage information and exit <directory>:: -You can specify a list of allowed directories. If no directories -are given, all are allowed. This is an additional restriction, gitcvs -access still needs to be enabled by the `gitcvs.enabled` config option -unless `--export-all` was given, too. - +The remaining arguments provide a list of directories. If no directories +are given, then all are allowed. Repositories within these directories +still require the `gitcvs.enabled` config option, unless `--export-all` +is specified. LIMITATIONS ----------- @@ -119,7 +118,7 @@ for example: myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3 ------ You can use the 'htpasswd' facility that comes with Apache to make these -files, but only with the -d option (or -B if your system suports it). +files, but only with the -d option (or -B if your system supports it). Preferably use the system specific utility that manages password hash creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or @@ -198,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: + ------ @@ -225,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 @@ -311,11 +310,13 @@ ENVIRONMENT These variables obviate the need for command-line options in some circumstances, allowing easier restricted usage through git-shell. -GIT_CVSSERVER_BASE_PATH takes the place of the argument to --base-path. +GIT_CVSSERVER_BASE_PATH:: + This variable replaces the argument to --base-path. -GIT_CVSSERVER_ROOT specifies a single-directory whitelist. The -repository must still be configured to allow access through -git-cvsserver, as described above. +GIT_CVSSERVER_ROOT:: + This variable specifies a single directory, replacing the + `<directory>...` argument list. The repository still requires the + `gitcvs.enabled` config option, unless `--export-all` is specified. When these environment variables are set, the corresponding command-line arguments may not be used. diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index fdc28c0..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>...] @@ -32,8 +32,8 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, you can further restrict -the offers to a whitelist comprising of those. +pass some directory paths as 'git daemon' arguments, the offers are limited to +repositories within those directories. By default, only `upload-pack` service is enabled, which serves 'git fetch-pack' and 'git ls-remote' clients, which are invoked @@ -50,7 +50,7 @@ OPTIONS Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. 'git daemon' will refuse to start when this option is enabled and no - whitelist is specified. + directory arguments are provided. --base-path=<path>:: Remap all the path requests as relative to the given path. @@ -73,7 +73,7 @@ OPTIONS %IP for the server's IP address, %P for the port number, and %D for the absolute path of the named repository. After interpolation, the path is validated against the directory - whitelist. + list. --export-all:: Allow pulling from all directories that look like Git repositories @@ -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. @@ -138,11 +138,11 @@ otherwise `stderr`. --user-path:: --user-path=<path>:: Allow {tilde}user notation to be used in requests. When - specified with no parameter, requests to + 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:: @@ -218,9 +218,11 @@ standard output to be sent to the requestor as an error message when it declines the service. <directory>:: - A directory to add to the whitelist of allowed directories. Unless - --strict-paths is specified this will also include subdirectories - of each named directory. + The remaining arguments provide a list of directories. If any + directories are specified, then the `git-daemon` process will + serve a requested directory only if it is contained in one of + these directories. If `--strict-paths` is specified, then the + requested directory must match one of these directories exactly. SERVICES -------- @@ -264,9 +266,8 @@ git 9418/tcp # Git Version Control System 'git daemon' as inetd server:: To set up 'git daemon' as an inetd service that handles any - repository under the whitelisted set of directories, /pub/foo - and /pub/bar, place an entry like the following into - /etc/inetd all on one line: + repository within `/pub/foo` or `/pub/bar`, place an entry like + the following into `/etc/inetd` all on one line: + ------------------------------------------------ git stream tcp nowait nobody /usr/bin/git diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c6a79c2..08ff715 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -140,7 +140,7 @@ at the end. The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + an unambigous abbreviation for the tip commit +The hash suffix is "-g" + an unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The length of the abbreviation scales as the repository grows, using the approximate number of objects in the repository and a bit of math @@ -203,7 +203,7 @@ BUGS Tree objects as well as tag objects not pointing at commits, cannot be described. When describing blobs, the lightweight tags pointing at blobs are ignored, -but the blob is still described as <committ-ish>:<path> despite the lightweight +but the blob is still described as <commit-ish>:<path> despite the lightweight tag being favorable. GIT diff --git a/Documentation/git-diagnose.txt b/Documentation/git-diagnose.txt new file mode 100644 index 0000000..0711959 --- /dev/null +++ b/Documentation/git-diagnose.txt @@ -0,0 +1,65 @@ +git-diagnose(1) +================ + +NAME +---- +git-diagnose - Generate a zip archive of diagnostic information + +SYNOPSIS +-------- +[verse] +'git diagnose' [(-o | --output-directory) <path>] [(-s | --suffix) <format>] + [--mode=<mode>] + +DESCRIPTION +----------- +Collects detailed information about the user's machine, Git client, and +repository state and packages that information into a zip archive. The +generated archive can then, for example, be shared with the Git mailing list to +help debug an issue or serve as a reference for independent debugging. + +By default, the following information is captured in the archive: + + * 'git version --build-options' + * The path to the repository root + * The available disk space on the filesystem + * The name and size of each packfile, including those in alternate object + stores + * The total count of loose objects, as well as counts broken down by + `.git/objects` subdirectory + +Additional information can be collected by selecting a different diagnostic mode +using the `--mode` option. + +This tool differs from linkgit:git-bugreport[1] in that it collects much more +detailed information with a greater focus on reporting the size and data shape +of repository contents. + +OPTIONS +------- +-o <path>:: +--output-directory <path>:: + Place the resulting diagnostics archive in `<path>` instead of the + current directory. + +-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 + form of a strftime(3) format string; the current local time will be + used. + +--mode=(stats|all):: + Specify the type of diagnostics that should be collected. The default behavior + of 'git diagnose' is equivalent to `--mode=stats`. ++ +The `--mode=all` option collects everything included in `--mode=stats`, as well +as copies of `.git`, `.git/hooks`, `.git/info`, `.git/logs`, and +`.git/objects/info` directories. This additional information may be sensitive, +as it can be used to reconstruct the full contents of the diagnosed repository. +Users should exercise caution when sharing an archive generated with +`--mode=all`. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index bf1febb..bf78e31 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- [verse] -'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...] +'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...] DESCRIPTION ----------- @@ -26,7 +26,7 @@ include::diff-options.txt[] -2 --ours:: -3 --theirs:: -0:: - Diff against the "base" version, "our branch" or "their + Diff against the "base" version, "our branch", or "their branch" respectively. With these options, diffs for merged entries are not shown. + @@ -37,12 +37,12 @@ omit diff output for unmerged entries and just show "Unmerged". -c:: --cc:: This compares stage 2 (our branch), stage 3 (their - branch) and the working tree file and outputs a combined + branch), and the working tree file and outputs a combined diff, similar to the way 'diff-tree' shows a merge commit with these flags. -q:: - Remain silent even on nonexistent files + Remain silent even for nonexistent files include::diff-format.txt[] diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 679cae2..4de1d4c 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -13,10 +13,10 @@ SYNOPSIS DESCRIPTION ----------- -Compares the content and mode of the blobs found in a tree object +Compare the content and mode of the blobs found in a tree object with the corresponding tracked files in the working tree, or with the corresponding paths in the index. When <path> arguments are present, -compares only paths matching those patterns. Otherwise all tracked +compare only paths matching those patterns. Otherwise all tracked files are compared. OPTIONS @@ -69,8 +69,8 @@ done an `update-index` to make that effective in the index file. matches my working directory. But doing a 'git diff-index' does: torvalds@ppc970:~/git> git diff-index --cached HEAD - -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c - +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c + :100644 000000 4161aecc6700a2eb579e842af0b7f22b98443f74 0000000000000000000000000000000000000000 D commit.c + :000000 100644 0000000000000000000000000000000000000000 4161aecc6700a2eb579e842af0b7f22b98443f74 A git-commit.c You can see easily that the above is a rename. @@ -103,7 +103,7 @@ have not actually done a 'git update-index' on it yet - there is no "object" associated with the new state, and you get: torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD - :100644 100664 7476bb... 000000... kernel/sched.c + :100644 100644 7476bb5ba 000000000 M kernel/sched.c i.e., it shows that the tree has changed, and that `kernel/sched.c` is not up to date and may contain new stuff. The all-zero sha1 means that to diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 274d5ea..143318c 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- -Compares the content and mode of the blobs found via two tree objects. +Compare the content and mode of blobs found via two tree objects. If there is only one <tree-ish> given, the commit is compared with its parents (see --stdin below). @@ -34,10 +34,10 @@ include::diff-options.txt[] matching one of the provided pathspecs. -r:: - recurse into sub-trees + Recurse into sub-trees. -t:: - show tree entry itself as well as subtrees. Implies -r. + Show tree entry itself as well as subtrees. Implies -r. --root:: When `--root` is specified the initial commit will be shown as a big @@ -78,7 +78,7 @@ commits (but not trees). By default, 'git diff-tree --stdin' shows differences, either in machine-readable form (without `-p`) or in patch form (with `-p`). This output can be suppressed. It is - only useful with `-v` flag. + only useful with the `-v` flag. -v:: This flag causes 'git diff-tree --stdin' to also show @@ -104,10 +104,10 @@ include::pretty-options.txt[] This flag changes the way a merge commit patch is displayed, in a similar way to the `-c` option. It implies the `-c` and `-p` options and further compresses the patch output - by omitting uninteresting hunks whose the contents in the parents + by omitting uninteresting hunks whose contents in the parents have only two variants and the merge result picks one of them without modification. When all hunks are uninteresting, the commit - itself and the commit log message is not shown, just like in any other + itself and the commit log message are not shown, just like in any other "empty diff" case. --combined-all-paths:: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 6236c75..c065f02 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -79,10 +79,10 @@ If --merge-base is given, use the merge base of the two commits for the This form is to view the results of a merge commit. The first listed <commit> must be the merge itself; the remaining two or - more commits should be its parents. A convenient way to produce - the desired set of revisions is to use the `^@` suffix. - For instance, if `master` names a merge commit, `git diff master - master^@` gives the same combined diff as `git show master`. + more commits should be its parents. Convenient ways to produce + the desired set of revisions are to use the suffixes `^@` and + `^!`. If A is a merge commit, then `git diff A A^@`, + `git diff A^!` and `git show A` all give the same combined diff. 'git diff' [<options>] <commit>..<commit> [--] [<path>...]:: @@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the 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>. +notations, can be any <tree>. A tree of interest is the one pointed to +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). For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. @@ -152,6 +156,7 @@ Various ways to check your working tree:: $ git diff <1> $ git diff --cached <2> $ git diff HEAD <3> +$ git diff AUTO_MERGE <4> ------------ + <1> Changes in the working tree not yet staged for the next commit. @@ -159,6 +164,8 @@ $ git diff HEAD <3> would be committing if you run `git commit` without `-a` option. <3> Changes in the working tree since your last commit; what you would be committing if you run `git commit -a` +<4> Changes in the working tree you've made to resolve textual + conflicts so far. Comparing with arbitrary commits:: + @@ -213,6 +220,13 @@ $ git diff -R <2> rewrites (very expensive). <2> Output diff in reverse. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/diff.txt[] + SEE ALSO -------- diff(1), diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 143b0c4..a616f8b 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -36,7 +36,7 @@ OPTIONS --rotate-to=<file>:: Start showing the diff for the given path, - the paths before it will move to end and output. + the paths before it will move to the end and output. --skip-to=<file>:: Start showing the diff for the given path, skipping all @@ -78,7 +78,7 @@ with custom merge tool commands and has the same value as `$MERGED`. Print a list of diff tools that may be used with `--tool`. --[no-]symlinks:: - 'git difftool''s default behavior is create symlinks to the + 'git difftool''s default behavior is to create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in the working tree. @@ -90,20 +90,21 @@ 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:: --[no-]gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured - `diff.guitool` variable instead of `diff.tool`. The `--no-gui` - option can be used to override this setting. If `diff.guitool` - is not set, we will fallback in the order of `merge.guitool`, - `diff.tool`, `merge.tool` until a tool is found. + `diff.guitool` variable instead of `diff.tool`. This may be + selected automatically using the configuration variable + `difftool.guiDefault`. The `--no-gui` option can be used to + override these settings. If `diff.guitool` is not set, we will + fallback in the order of `merge.guitool`, `diff.tool`, + `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. @@ -113,33 +114,14 @@ instead. `--no-symlinks` is the default on Windows. See linkgit:git-diff[1] for the full list of supported options. -CONFIG VARIABLES ----------------- +CONFIGURATION +------------- 'git difftool' falls back to 'git mergetool' config variables when the difftool equivalents have not been defined. -diff.tool:: - The default diff tool to use. +include::includes/cmd-config-section-rest.txt[] -diff.guitool:: - The default diff tool to use when `--gui` is specified. - -difftool.<tool>.path:: - Override the path for the given tool. This is useful in case - your tool is not in the PATH. - -difftool.<tool>.cmd:: - Specify the command to invoke the specified diff tool. -+ -See the `--tool=<tool>` option above for more details. - -difftool.prompt:: - Prompt before each invocation of the diff tool. - -difftool.trustExitCode:: - Exit difftool if the invoked diff tool returns a non-zero exit status. -+ -See the `--trust-exit-code` option above for more details. +include::config/difftool.txt[] SEE ALSO -------- diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 1978dbd..752e4b9 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export [<options>]' | 'git fast-import' +'git fast-export' [<options>] | 'git fast-import' DESCRIPTION ----------- @@ -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 39cfa05..b260736 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -622,7 +622,7 @@ in octal. Git only supports the following modes: * `100755` or `755`: A normal, but executable, file. * `120000`: A symlink, the content of the file will be the link target. * `160000`: A gitlink, SHA-1 of the object refers to a commit in - another repository. Git links can only be specified by SHA or through + another repository. Git links can only be specified either by SHA or through a commit mark. They are used to implement submodules. * `040000`: A subdirectory. Subdirectories can only be specified by SHA or through a tree mark set with `--import-marks`. @@ -745,11 +745,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. @@ -1353,7 +1353,7 @@ the marks back to the source repository, it is easy to verify the accuracy and completeness of the import by comparing each Git commit to the corresponding source revision. -Coming from a system such as Perforce or Subversion this should be +Coming from a system such as Perforce or Subversion, this should be quite simple, as the fast-import mark can also be the Perforce changeset number or the Subversion revision number. @@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an import in progress, at the cost of some added running time and worse compression. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/fastimport.txt[] + SEE ALSO -------- linkgit:git-fast-export[1] diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 46747d5..b346766 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -69,7 +69,7 @@ be in a separate packet, and the list must end with a flush packet. --upload-pack=<git-upload-pack>:: Use this to specify the path to 'git-upload-pack' on the - remote side, if is not found on your $PATH. + remote side, if it is not found on your $PATH. Installations of sshd ignores the user's environment setup scripts for login shells (e.g. .bash_profile) and your privately installed git may not be found on the system diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index e9d3646..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 @@ -204,6 +204,15 @@ representing the status of a single ref. Each line is of the form: <flag> <summary> <from> -> <to> [<reason>] ------------------------------- +When using `--porcelain`, the output format is intended to be +machine-parseable. In contrast to the human-readable output formats it +thus prints to standard output instead of standard error. Each line is +of the form: + +------------------------------- +<flag> <old-object-id> <new-object-id> <local-reference> +------------------------------- + The status of up-to-date refs is shown only if the --verbose option is used. @@ -251,10 +260,10 @@ EXAMPLES $ git fetch origin ------------------------------------------------ + -The above command copies all branches from the remote refs/heads/ -namespace and stores them to the local refs/remotes/origin/ namespace, -unless the branch.<name>.fetch option is used to specify a non-default -refspec. +The above command copies all branches from the remote `refs/heads/` +namespace and stores them to the local `refs/remotes/origin/` namespace, +unless the `remote.<repository>.fetch` option is used to specify a +non-default refspec. * Using refspecs explicitly: + @@ -285,6 +294,13 @@ linkgit:git-gc[1]). include::transfer-data-leaks.txt[] +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/fetch.txt[] + BUGS ---- Using --recurse-submodules can only fetch new commits in submodules that are 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 6da899c..c1dd12b 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -9,10 +9,12 @@ SYNOPSIS -------- [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] - [(--sort=<key>)...] [--format=<format>] [<pattern>...] + [(--sort=<key>)...] [--format=<format>] + [--include-root-refs] [ --stdin | <pattern>... ] [--points-at=<object>] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] + [--exclude=<pattern> ...] DESCRIPTION ----------- @@ -32,6 +34,10 @@ OPTIONS literally, in the latter case matching completely or from the beginning up to a slash. +--stdin:: + If `--stdin` is supplied, then the list of patterns is read from + standard input instead of from the argument list. + --count=<count>:: By default the command shows all refs that match `<pattern>`. This option makes it stop after showing @@ -45,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 @@ -93,6 +96,18 @@ OPTIONS --ignore-case:: Sorting and filtering refs are case insensitive. +--omit-empty:: + Do not print a newline after formatted refs where the format expands + to the empty string. + +--exclude=<pattern>:: + If one or more patterns are given, only refs which do not match + 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 ----------- @@ -212,11 +227,66 @@ symref:: `:lstrip` and `:rstrip` options in the same way as `refname` above. +signature:: + The GPG signature of a commit. + +signature:grade:: + Show "G" for a good (valid) signature, "B" for a bad + signature, "U" for a good signature with unknown validity, "X" + for a good signature that has expired, "Y" for a good + signature made by an expired key, "R" for a good signature + made by a revoked key, "E" if the signature cannot be + checked (e.g. missing key) and "N" for no signature. + +signature:signer:: + The signer of the GPG signature of a commit. + +signature:key:: + The key of the GPG signature of a commit. + +signature:fingerprint:: + The fingerprint of the GPG signature of a commit. + +signature:primarykeyfingerprint:: + The primary key fingerprint of the GPG signature of a commit. + +signature:trustlevel:: + The trust level of the GPG signature of a commit. Possible + outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. + worktreepath:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string otherwise. +ahead-behind:<committish>:: + Two integers, separated by a space, demonstrating the number of + commits ahead and behind, respectively, when comparing the output + ref to the `<committish>` specified in the format. + +describe[:options]:: + A human-readable name, like linkgit:git-describe[1]; + empty string for undescribable commits. The `describe` string may + be followed by a colon and one or more comma-separated options. ++ +-- +tags=<bool-value>;; + Instead of only considering annotated tags, consider + lightweight tags as well; see the corresponding option in + linkgit:git-describe[1] for details. +abbrev=<number>;; + Use at least <number> hexadecimal digits; see the corresponding + option in linkgit:git-describe[1] for details. +match=<pattern>;; + Only consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix; see the corresponding option + in linkgit:git-describe[1] for details. +exclude=<pattern>;; + Do not consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix; see the corresponding option + in linkgit:git-describe[1] for details. +-- + In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. @@ -228,12 +298,20 @@ 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`, `committeremail` and `taggeremail`), `:trim` can be appended to get the email without angle brackets, and `:localpart` to get the part before the `@` symbol -out of the trimmed email. +out of the trimmed email. In addition to these, the `:mailmap` option and the +corresponding `:mailmap,trim` and `:mailmap,localpart` can be used (order does +not matter) to get values of the name and email according to the .mailmap file +or according to the file set in the mailmap.file or mailmap.blob configuration +variable (see linkgit:gitmailmap[5]). The raw data in an object is `raw`. @@ -284,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 be797d7..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 ----------- @@ -55,7 +55,7 @@ A "message" generated by the command consists of three parts: * The "patch", which is the "diff -p --stat" output (see linkgit:git-diff[1]) between the commit and its parent. -The log message and the patch is separated by a line with a +The log message and the patch are separated by a line with a three-dash line. There are two ways to specify which commits to operate on. @@ -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. @@ -99,7 +99,7 @@ To omit patch numbers from the subject, use `-N`. If given `--thread`, `git-format-patch` will generate `In-Reply-To` and `References` headers to make the second and subsequent patch mails appear -as replies to the first mail; this also generates a `Message-Id` header to +as replies to the first mail; this also generates a `Message-ID` header to reference. OPTIONS @@ -163,7 +163,7 @@ include::diff-options.txt[] --no-thread:: Controls addition of `In-Reply-To` and `References` headers to make the second and subsequent mails appear as replies to the - first. Also controls generation of the `Message-Id` header to + first. Also controls generation of the `Message-ID` header to reference. + The optional <style> argument can be either `shallow` or `deep`. @@ -173,16 +173,15 @@ series, where the head is chosen from the cover letter, the threading makes every mail a reply to the previous one. + The default is `--no-thread`, unless the `format.thread` configuration -is set. If `--thread` is specified without a style, it defaults to the -style specified by `format.thread` if any, or else `shallow`. +is set. `--thread` without an argument is equivalent to `--thread=shallow`. + 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:: @@ -216,11 +215,21 @@ is greater than 100 bytes, then the mode will be `message`, otherwise If `<mode>` is `none`, both the cover letter subject and body will be populated with placeholder text. ---subject-prefix=<subject prefix>:: +--description-file=<file>:: + Use the contents of <file> instead of the branch's description + for generating the cover letter. + +--subject-prefix=<subject-prefix>:: Instead of the standard '[PATCH]' prefix in the subject - line, instead use '[<subject prefix>]'. This - allows for useful naming of a patch series, and can be - combined with the `--numbered` option. + line, instead use '[<subject-prefix>]'. This can be used + to name a patch series, and can be combined with the + `--numbered` option. ++ +The configuration variable `format.subjectPrefix` may also be used +to configure a subject prefix to apply to a given repository for +all patches. This is often useful on mailing lists which receive +patches for several repositories and can be used to disambiguate +the patches (with a value of e.g. "PATCH my-project"). --filename-max-length=<n>:: Instead of the standard 64 bytes, chomp the generated output @@ -230,9 +239,9 @@ populated with placeholder text. variable, or 64 if unconfigured. --rfc:: - Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For - Comments"; use this when sending an experimental patch for - discussion rather than application. + Prepends "RFC" to the subject prefix (producing "RFC PATCH" by + default). RFC means "Request For Comments"; use this when sending + an experimental patch for discussion rather than application. -v <n>:: --reroll-count=<n>:: @@ -246,7 +255,7 @@ populated with placeholder text. or "--reroll-count=4rev2" are allowed), but the downside of using such a reroll-count is that the range-diff/interdiff with the previous version does not state exactly which - version the new interation is compared against. + version the new iteration is compared against. --to=<email>:: Add a `To:` header to the email headers. This is in addition @@ -275,6 +284,17 @@ header). Note also that `git send-email` already handles this transformation for you, and this option should not be used if you are feeding the result to `git send-email`. +--[no-]force-in-body-from:: + With the e-mail sender specified via the `--from` option, by + default, an in-body "From:" to identify the real author of + the commit is added at the top of the commit log message if + the sender is different from the author. With this option, + the in-body "From:" is added even when the sender and the + author have the same name and address, which may help if the + mailing list software mangles the sender's identity. + Defaults to the value of the `format.forceInBodyFrom` + configuration variable. + --add-header=<header>:: Add an arbitrary header to the email headers. This is in addition to any configured headers, and may be used multiple times. @@ -383,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 @@ -590,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-fsck.txt b/Documentation/git-fsck.txt index 5088783..5b82e46 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -24,7 +24,7 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA-1 references in `refs` namespace, and all reflogs +index file, all SHA-1 references in the `refs` namespace, and all reflogs (unless --no-reflogs is given) as heads. --unreachable:: @@ -64,7 +64,7 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs --connectivity-only:: Check only the connectivity of reachable objects, making sure that any objects referenced by a reachable tag, commit, or tree - is present. This speeds up the operation by avoiding reading + are present. This speeds up the operation by avoiding reading blobs entirely (though it does still check that referenced blobs exist). This will detect corruption in commits and trees, but not do any semantic checks (e.g., for format errors). Corruption @@ -79,7 +79,7 @@ care about this output and want to speed it up further. recorded with g+w bit set, which was created by older versions of Git. Existing repositories, including the Linux kernel, Git itself, and sparse repository have old - objects that triggers this check, but it is recommended + objects that trigger this check, but it is recommended to check new projects with this flag. --verbose:: @@ -107,6 +107,8 @@ care about this output and want to speed it up further. CONFIGURATION ------------- +include::includes/cmd-config-section-all.txt[] + include::config/fsck.txt[] DISCUSSION @@ -150,6 +152,18 @@ hash mismatch <object>:: object database value. This indicates a serious data integrity problem. + +FSCK MESSAGES +------------- + +The following lists the types of errors `git fsck` detects and what +each error means, with their default severity. The severity of the +error, other than those that are marked as "(FATAL)", can be tweaked +by setting the corresponding `fsck.<msg-id>` configuration variable. + +include::fsck-msgids.txt[] + + Environment Variables --------------------- diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt index cc142fb..8585d19 100644 --- a/Documentation/git-fsmonitor--daemon.txt +++ b/Documentation/git-fsmonitor--daemon.txt @@ -3,7 +3,7 @@ git-fsmonitor{litdd}daemon(1) NAME ---- -git-fsmonitor--daemon - A Built-in File System Monitor +git-fsmonitor--daemon - A Built-in Filesystem Monitor SYNOPSIS -------- @@ -17,7 +17,7 @@ DESCRIPTION ----------- A daemon to watch the working directory for file and directory -changes using platform-specific file system notification facilities. +changes using platform-specific filesystem notification facilities. This daemon communicates directly with commands like `git status` using the link:technical/api-simple-ipc.html[simple IPC] interface @@ -63,13 +63,44 @@ CAVEATS ------- The fsmonitor daemon does not currently know about submodules and does -not know to filter out file system events that happen within a +not know to filter out filesystem events that happen within a submodule. If fsmonitor daemon is watching a super repo and a file is modified within the working directory of a submodule, it will report the change (as happening against the super repo). However, the client will properly ignore these extra events, so performance may be affected but it will not cause an incorrect result. +By default, the fsmonitor daemon refuses to work with network-mounted +repositories; this may be overridden by setting `fsmonitor.allowRemote` to +`true`. Note, however, that the fsmonitor daemon is not guaranteed to work +correctly with all network-mounted repositories, so such use is considered +experimental. + +On Mac OS, the inter-process communication (IPC) between various Git +commands and the fsmonitor daemon is done via a Unix domain socket (UDS) -- a +special type of file -- which is supported by native Mac OS filesystems, +but not on network-mounted filesystems, NTFS, or FAT32. Other filesystems +may or may not have the needed support; the fsmonitor daemon is not guaranteed +to work with these filesystems and such use is considered experimental. + +By default, the socket is created in the `.git` directory. However, if the +`.git` directory is on a network-mounted filesystem, it will instead be +created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a +network-mounted filesystem, in which case you must set the configuration +variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native +filesystem in which to create the socket file. + +If none of the above directories (`.git`, `$HOME`, or `fsmonitor.socketDir`) +is on a native Mac OS file filesystem the fsmonitor daemon will report an +error that will cause the daemon and the currently running command to exit. + +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/fsmonitor--daemon.txt[] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 0af7540..b5561c4 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -54,9 +54,17 @@ other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. ---cruft:: +--[no-]cruft:: When expiring unreachable objects, pack them separately into a - cruft pack instead of storing them as loose objects. + cruft pack instead of storing them as loose objects. `--cruft` + is on by default. + +--max-cruft-size=<n>:: + When packing unreachable objects into a cruft pack, limit the + size of new cruft packs to be at most `<n>` bytes. Overrides any + value specified via the `gc.maxCruftSize` configuration. See + the `--max-cruft-size` option of linkgit:git-repack[1] for + more. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, @@ -77,9 +85,10 @@ be performed as well. instance running on this repository. --keep-largest-pack:: - All packs except the largest pack and those marked with a - `.keep` files are consolidated into a single pack. When this - option is used, `gc.bigPackThreshold` is ignored. + All packs except the largest non-cruft pack, any packs marked + with a `.keep` file, and any cruft pack(s) are consolidated into + a single pack. When this option is used, `gc.bigPackThreshold` + is ignored. AGGRESSIVE ---------- @@ -110,8 +119,7 @@ users and their repositories. CONFIGURATION ------------- -The below documentation is the same as what's found in -linkgit:git-config[1]: +include::includes/cmd-config-section-all.txt[] include::config/gc.txt[] diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index ac44d85..b537bb4 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -20,7 +20,7 @@ and extract the commit ID stored in it. It reads only the first 1024 bytes of input, thus its runtime is not influenced by the size of the tar archive very much. -If no commit ID is found, 'git get-tar-commit-id' quietly exists with a +If no commit ID is found, 'git get-tar-commit-id' quietly exits with a return code of 1. This can happen if the archive had not been created using 'git archive' or if the first parameter of 'git archive' had been a tree ID instead of a commit ID or tag. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 3d393fb..1e6d7b6 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -23,11 +23,12 @@ SYNOPSIS [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] [-W | --function-context] + [(-m | --max-count) <num>] [--threads <num>] [-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 @@ -44,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`. @@ -63,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:: @@ -177,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:: @@ -238,9 +247,17 @@ providing this option will cause it to die. `git diff` works out patch hunk headers (see 'Defining a custom hunk-header' in linkgit:gitattributes[5]). +-m <num>:: +--max-count <num>:: + Limit the amount of matches per file. When using the `-v` or + `--invert-match` option, the search stops after the specified + number of non-matches. A value of -1 will return unlimited + results (the default). A value of 0 will exit immediately with + 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. @@ -323,45 +340,20 @@ 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're 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 ------------- -grep.lineNumber:: - If set to true, enable `-n` option by default. - -grep.column:: - If set to true, enable the `--column` option by default. - -grep.patternType:: - Set the default matching behavior. Using a value of 'basic', 'extended', - 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, - `--fixed-strings`, or `--perl-regexp` option accordingly, while the - value 'default' will return to the default matching behavior. - -grep.extendedRegexp:: - If set to true, enable `--extended-regexp` option by default. This - option is ignored when the `grep.patternType` option is set to a value - other than 'default'. - -grep.threads:: - Number of grep worker threads to use. If unset (or set to 0), Git will - use as many threads as the number of logical cores available. - -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 - is executed outside of a git repository. Defaults to false. +include::includes/cmd-config-section-all.txt[] +include::config/grep.txt[] GIT --- diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index df9e2c5..ef4719a 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -3,13 +3,14 @@ git-hash-object(1) NAME ---- -git-hash-object - Compute object ID and optionally creates a blob from a file +git-hash-object - Compute object ID and optionally create an object from a file SYNOPSIS -------- [verse] -'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>... +'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters] + [--stdin [--literally]] [--] <file>... 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] DESCRIPTION @@ -24,7 +25,8 @@ OPTIONS ------- -t <type>:: - Specify the type (default: "blob"). + Specify the type of object to be created (default: "blob"). Possible + values are `commit`, `tree`, `blob`, and `tag`. -w:: Actually write the object into the object database. @@ -37,10 +39,10 @@ OPTIONS of from the command-line. --path:: - Hash object as it were located at the given path. The location of - file does not directly influence on the hash value, but path is - used to determine what Git filters should be applied to the object - before it can be placed to the object database, and, as result of + Hash object as if it were located at the given path. The location of + the file does not directly influence the hash value, but the path is + used to determine which Git filters should be applied to the object + before it can be placed in the object database. As a result of applying filters, the actual blob put into the object database may differ from the given file. This option is mainly useful for hashing temporary files located outside of the working directory or files diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 239c68d..f0bedc1 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,16 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] -'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>] 'git help' [-g|--guides] 'git help' [-c|--config] +'git help' [--user-interfaces] +'git help' [--developer-interfaces] DESCRIPTION ----------- -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git' +With no options and no '<command>' or '<doc>' given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. @@ -26,8 +28,8 @@ printed on the standard output. If the option `--guides` or `-g` is given, a list of the Git concept guides is also printed on the standard output. -If a command, or a guide, is given, a manual page for that command or -guide is brought up. The 'man' program is used by default for this +If a command or other documentation is given, the relevant manual page +will be brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. @@ -40,13 +42,13 @@ former is internally converted into the latter. To display the linkgit:git[1] man page, use `git help git`. -This page can be displayed with 'git help help' or `git help --help` +This page can be displayed with 'git help help' or `git help --help`. OPTIONS ------- -a:: --all:: - Prints all the available commands on the standard output. + Print all the available commands on the standard output. --no-external-commands:: When used with `--all`, exclude the listing of external "git-*" @@ -57,7 +59,7 @@ OPTIONS aliases. --verbose:: - When used with `--all` print description for all recognized + When used with `--all`, print description for all recognized commands. This is the default. -c:: @@ -67,7 +69,24 @@ OPTIONS -g:: --guides:: - Prints a list of the Git concept guides on the standard output. + Print a list of the Git concept guides on the standard output. + +--user-interfaces:: + Print a list of the repository, command and file interfaces + documentation on the standard output. ++ +In-repository file interfaces such as `.git/info/exclude` are +documented here (see linkgit:gitrepository-layout[5]), as well as +in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]). ++ +This section of the documentation also covers general or widespread +user-interface conventions (e.g. linkgit:gitcli[7]), and +pseudo-configuration such as the file-based `.git/hooks/*` interface +described in linkgit:githooks[5]. + +--developer-interfaces:: + Print a list of file formats, protocols and other developer + interfaces documentation on the standard output. -i:: --info:: @@ -90,7 +109,7 @@ other display programs (see below). format. A web browser will be used for that purpose. + The web browser can be specified using the configuration variable -`help.browser`, or `web.browser` if the former is not set. If none of +`help.browser`, or `web.browser` if the former is not set. If neither of these config variables is set, the 'git web{litdd}browse' helper script (called by 'git help') will pick a suitable default. See linkgit:git-web{litdd}browse[1] for more information about this. @@ -110,8 +129,8 @@ line option: * "info" corresponds to '-i|--info', * "web" or "html" correspond to '-w|--web'. -help.browser, web.browser and browser.<tool>.path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +help.browser, web.browser, and browser.<tool>.path +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `help.browser`, `web.browser` and `browser.<tool>.path` will also be checked if the 'web' format is chosen (either by command-line diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.txt index 77c3a8a..f6cc72d 100644 --- a/Documentation/git-hook.txt +++ b/Documentation/git-hook.txt @@ -8,12 +8,12 @@ git-hook - Run git hooks SYNOPSIS -------- [verse] -'git hook' run [--ignore-missing] <hook-name> [-- <hook-args>] +'git hook' run [--ignore-missing] [--to-stdin=<path>] <hook-name> [-- <hook-args>] DESCRIPTION ----------- -A command interface to running git hooks (see linkgit:githooks[5]), +A command interface for running git hooks (see linkgit:githooks[5]), for use by other scripted git commands. SUBCOMMANDS @@ -31,6 +31,11 @@ linkgit:githooks[5] for arguments hooks might expect (if any). OPTIONS ------- +--to-stdin:: + For "run"; specify a file which will be streamed into the + hook's stdin. The hook will receive the entire file from + beginning to EOF. + --ignore-missing:: Ignore any missing hook by quietly returning zero. Used for tools that want to do a blind one-shot run of a hook that may diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 0c5c0dd..f37ddad 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -23,7 +23,7 @@ discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the -`GIT_HTTP_EXPORT_ALL` environmental variable is set). +`GIT_HTTP_EXPORT_ALL` environment variable is set). By default, only the `upload-pack` service is enabled, which serves 'git fetch-pack' and 'git ls-remote' clients, which are invoked from @@ -42,12 +42,12 @@ http.getanyfile:: any file within the repository, including objects that are no longer reachable from a branch but are still present. It is enabled by default, but a repository can disable it - by setting this configuration item to `false`. + by setting this configuration value to `false`. http.uploadpack:: This serves 'git fetch-pack' and 'git ls-remote' clients. It is enabled by default, but a repository can disable it - by setting this configuration item to `false`. + by setting this configuration value to `false`. http.receivepack:: This serves 'git send-pack' clients, allowing push. It is @@ -265,12 +265,12 @@ by the invoking web server, including: * QUERY_STRING * REQUEST_METHOD -The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to +The `GIT_HTTP_EXPORT_ALL` environment variable may be passed to 'git-http-backend' to bypass the check for the "git-daemon-export-ok" file in each repository before allowing export of that repository. The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the -`http.maxRequestBuffer` config variable) may be set to change the +`http.maxRequestBuffer` config option) may be set to change the largest ref negotiation request that git will handle during a fetch; any fetch requiring a larger buffer will not succeed. This value should not normally need to be changed, but may be helpful if you are fetching from diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 319062c..4ec7c68 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -31,7 +31,7 @@ commit-id:: Report what is downloaded. -w <filename>:: - Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on + Writes the commit-id into the specified filename under $GIT_DIR/refs/<filename> on the local end after the transfer is complete. --stdin:: diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 7c6a6dd..ce0d808 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -13,12 +13,12 @@ SYNOPSIS DESCRIPTION ----------- -Sends missing objects to remote repository, and updates the +Sends missing objects to the remote repository, and updates the remote branch. *NOTE*: This command is temporarily disabled if your libcurl is older than 7.16, as the combination has been reported -not to work and sometimes corrupts repository. +not to work and sometimes corrupts the repository. OPTIONS ------- @@ -44,7 +44,7 @@ OPTIONS -d:: -D:: Remove <ref> from remote repository. The specified branch - cannot be the remote HEAD. If -d is specified the following + cannot be the remote HEAD. If -d is specified, the following other conditions must also be met: - Remote HEAD must resolve to an object that exists locally @@ -83,8 +83,8 @@ and where it is pushed is determined by using the destination side. Without `--force`, the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an ancestor) of <src>. This check, known as "fast-forward check", -is performed in order to avoid accidentally overwriting the -remote ref and lose other peoples' commits from there. +is performed to avoid accidentally overwriting the +remote ref and losing other peoples' commits from there. With `--force`, the fast-forward check is disabled for all refs. diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 63cf498..c8a89d7 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -54,6 +54,8 @@ CONFIGURATION To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set to appropriate values. +include::includes/cmd-config-section-rest.txt[] + include::config/imap.txt[] EXAMPLES @@ -133,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 4e71c25..5a20dee 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -16,10 +16,10 @@ SYNOPSIS DESCRIPTION ----------- -Reads a packed archive (.pack) from the specified file, and -builds a pack index file (.idx) for it. Optionally writes a +Reads a packed archive (.pack) from the specified file, +builds a pack index file (.idx) for it, and optionally writes a reverse-index (.rev) for the specified pack. The packed -archive together with the pack index can then be placed in +archive, together with the pack index, can then be placed in the objects/pack/ directory of a Git repository. @@ -68,8 +68,8 @@ OPTIONS updated to use objects contained in the pack. --keep=<msg>:: - Like --keep create a .keep file before moving the index into - its final destination, but rather than creating an empty file + Like --keep, create a .keep file before moving the index into + its final destination. However, instead of creating an empty file place '<msg>' followed by an LF into the .keep file. The '<msg>' message can later be searched for within all .keep files to locate any which have outlived their usefulness. @@ -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 ad921fe..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 @@ -29,94 +30,104 @@ to use instead of `./.git` for the base of the repository. If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories -are created underneath - otherwise the default `$GIT_DIR/objects` +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 -repository. This file acts as filesystem-agnostic Git symbolic link to the +repository. This file acts as a filesystem-agnostic Git symbolic link to the repository. + -If this is reinitialization, the repository will be moved to the specified path. +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 be not +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' -does). '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,10 +176,19 @@ $ 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. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +:git-init: + +include::config/init.txt[] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 956a01d..d9dfb75 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -8,66 +8,106 @@ git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- [verse] -'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...] -'git interpret-trailers' [<options>] [--parse] [<file>...] +'git interpret-trailers' [--in-place] [--trim-empty] + [(--trailer (<key>|<key-alias>)[(=|:)<value>])...] + [--parse] [<file>...] DESCRIPTION ----------- -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail +Add or parse 'trailer' lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit -message. +message. For example, in the following commit message -This command reads some patches or commit messages from either the -<file> arguments or the standard input if no <file> is specified. If -`--parse` is specified, the output consists of the parsed trailers. +------------------------------------------------ +subject + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. -Otherwise, this command applies the arguments passed using the -`--trailer` option, if any, to the commit message part of each input -file. The result is emitted on the standard output. +Signed-off-by: Alice <alice@example.com> +Signed-off-by: Bob <bob@example.com> +------------------------------------------------ + +the last two lines starting with "Signed-off-by" are trailers. + +This command reads commit messages from either the +<file> arguments or the standard input if no <file> is specified. +If `--parse` is specified, the output consists of the parsed trailers +coming from the input, without influencing them with any command line +options or configuration variables. + +Otherwise, this command applies `trailer.*` configuration variables +(which could potentially add new trailers, as well as reposition them), +as well as any command line arguments that can override configuration +variables (such as `--trailer=...` which could also add new trailers), +to each input file. The result is emitted on the standard output. + +This command can also operate on the output of linkgit:git-format-patch[1], +which is more elaborate than a plain commit message. Namely, such output +includes a commit message (as above), a "---" divider line, and a patch part. +For these inputs, the divider and patch parts are not modified by +this command and are emitted as is on the output, unless +`--no-divider` is specified. Some configuration variables control the way the `--trailer` arguments -are applied to each commit message and the way any existing trailer in -the commit message is changed. They also make it possible to +are applied to each input and the way any existing trailer in +the input is changed. They also make it possible to automatically add some trailers. -By default, a '<token>=<value>' or '<token>:<value>' argument given +By default, a '<key>=<value>' or '<key>:<value>' argument given using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (<token>, <value>) pair (or if there -is no existing trailer). The <token> and <value> parts will be trimmed +the last trailer has a different (<key>, <value>) pair (or if there +is no existing trailer). The <key> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed -<token> and <value> will appear in the message like this: +<key> and <value> will appear in the output like this: ------------------------------------------------ -token: value +key: value ------------------------------------------------ -This means that the trimmed <token> and <value> will be separated by +This means that the trimmed <key> and <value> will be separated by `': '` (one colon followed by one space). +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.<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 + +------------------------------------------------ +trailer.sign.key "Signed-off-by: " +------------------------------------------------ + +in your configuration, you only need to specify `--trailer="sign: foo"` +on the command line instead of `--trailer="Signed-off-by: foo"`. + By default the new trailer will appear at the end of all the existing trailers. If there is no existing trailer, the new trailer will appear -after the commit message part of the output, and, if there is no line -with only spaces at the end of the commit message part, one blank line -will be added before the new trailer. +at the end of the input. A blank line will be added before the new +trailer if there isn't one already. -Existing trailers are extracted from the input message by looking for +Existing trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or user-configured trailer and consists of at least 25% trailers. The group must be preceded by one or more empty (or whitespace-only) lines. -The group must either be at the end of the message or be the last +The group must either be at the end of the input or be the last non-whitespace lines before a line that starts with '---' (followed by a -space or the end of the line). Such three minus signs start the patch -part of the message. See also `--no-divider` below. +space or the end of the line). -When reading trailers, there can be whitespaces after the -token, the separator and the value. There can also be whitespaces -inside the token and the value. The value may be split over multiple lines with -each subsequent line starting with whitespace, like the "folding" in RFC 822. +When reading trailers, there can be no whitespace before or inside the +<key>, but any number of regular space and tab characters are allowed +between the <key> and the separator. There can be whitespaces before, +inside or after the <value>. The <value> may be split over multiple lines +with each subsequent line starting with at least one whitespace, like +the "folding" in RFC 822. Example: -Note that 'trailers' do not follow and are not intended to follow many -rules for RFC 822 headers. For example they do not follow -the encoding rules and probably many other rules. +------------------------------------------------ +key: This is a very long value, with spaces and + newlines in it. +------------------------------------------------ + +Note that trailers do not follow (nor are they intended to follow) many of the +rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- @@ -76,38 +116,47 @@ OPTIONS --trim-empty:: If the <value> part of any trailer contains only whitespace, - the whole trailer will be removed from the resulting message. + the whole trailer will be removed from the output. This applies to existing trailers as well as new trailers. ---trailer <token>[(=|:)<value>]:: - Specify a (<token>, <value>) pair that should be applied as a - trailer to the input messages. See the description of this +--trailer <key>[(=|:)<value>]:: + Specify a (<key>, <value>) pair that should be applied as a + trailer to the inputs. See the description of this command. --where <placement>:: --no-where:: Specify where all new trailers will be added. A setting - provided with '--where' overrides all configuration variables + provided with '--where' overrides the `trailer.where` and any + applicable `trailer.<keyAlias>.where` configuration variables and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Possible values are `after`, `before`, - `end` or `start`. + '--where' or '--no-where'. Upon encountering '--no-where', clear the + effect of any previous use of '--where', such that the relevant configuration + variables are no longer overridden. Possible placements are `after`, + `before`, `end` or `start`. --if-exists <action>:: --no-if-exists:: Specify what action will be performed when there is already at - least one trailer with the same <token> in the message. A setting - provided with '--if-exists' overrides all configuration variables + least one trailer with the same <key> in the input. A setting + provided with '--if-exists' overrides the `trailer.ifExists` and any + applicable `trailer.<keyAlias>.ifExists` configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, + '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists, clear the + effect of any previous use of '--if-exists, such that the relevant configuration + variables are no longer overridden. Possible actions are `addIfDifferent`, `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. --if-missing <action>:: --no-if-missing:: Specify what action will be performed when there is no other - trailer with the same <token> in the message. A setting - provided with '--if-missing' overrides all configuration variables + trailer with the same <key> in the input. A setting + provided with '--if-missing' overrides the `trailer.ifMissing` and any + applicable `trailer.<keyAlias>.ifMissing` configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` + '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing, + clear the effect of any previous use of '--if-missing, such that the relevant + configuration variables are no longer overridden. Possible actions are `doNothing` or `add`. --only-trailers:: @@ -115,16 +164,19 @@ OPTIONS --only-input:: Output only trailers that exist in the input; do not add any - from the command-line or by following configured `trailer.*` - rules. + from the command-line or by applying `trailer.*` configuration + variables. --unfold:: - Remove any whitespace-continuation in trailers, so that each - trailer appears on a line by itself with its full content. + If a trailer has a value that runs over multiple lines (aka "folded"), + reformat the value into a single line. --parse:: A convenience alias for `--only-trailers --only-input - --unfold`. + --unfold`. This makes it easier to only see the trailers coming from the + input without influencing them with any command line options or + configuration variables, while also making the output machine-friendly with + --unfold. --no-divider:: Do not treat `---` as the end of the commit message. Use this @@ -145,11 +197,11 @@ used when another separator is not specified in the config for this trailer. + For example, if the value for this option is "%=$", then only lines -using the format '<token><sep><value>' with <sep> containing '%', '=' +using the format '<key><sep><value>' with <sep> containing '%', '=' or '$' and then spaces will be considered trailers. And '%' will be the default separator used, so by default trailers will appear like: -'<token>% <value>' (one percent sign and one space will appear between -the token and the value). +'<key>% <value>' (one percent sign and one space will appear between +the key and the value). trailer.where:: This option tells where a new trailer will be added. @@ -163,41 +215,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same <token>. +last trailer with the same <key>. + If it is `before`, then each new trailer will appear just before the -first trailer with the same <token>. +first trailer with the same <key>. trailer.ifexists:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same <token> in the message. + same <key> in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (<token>, <value>) pair is above or below the line +trailer with the same (<key>, <value>) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (<token>, <value>) pair is already in the message. +with the same (<key>, <value>) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (<token>, <value>) pair are already in the message. +the same (<key>, <value>) pair are already in the input. + -With `replace`, an existing trailer with the same <token> will be +With `replace`, an existing trailer with the same <key> will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <token>) to the place where the new one +the closest one (with the same <key>) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same <token> in the message. +added if there is already one with the same <key> in the input. trailer.ifmissing:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - <token> in the message. + <key> in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`. @@ -206,100 +258,106 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer.<token>.key:: - This `key` will be used instead of <token> in the trailer. At - the end of this key, a separator can appear and then some - space characters. By default the only valid separator is ':', - but this can be changed using the `trailer.separators` config - variable. +trailer.<keyAlias>.key:: + Defines a <keyAlias> for the <key>. The <keyAlias> must be a + prefix (case does not matter) of the <key>. For example, in `git + config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and + the "ack" is the <keyAlias>. This configuration allows the shorter + `--trailer "ack:..."` invocation on the command line using the "ack" + <keyAlias> instead of the longer `--trailer "Acked-by:..."`. ++ +At the end of the <key>, a separator can appear and then some +space characters. By default the only valid separator is ':', +but this can be changed using the `trailer.separators` config +variable. + -If there is a separator, then the key will be used instead of both the -<token> and the default separator when adding the trailer. +If there is a separator in the key, then it overrides the default +separator when adding the trailer. -trailer.<token>.where:: +trailer.<keyAlias>.where:: This option takes the same values as the 'trailer.where' configuration variable and it overrides what is specified by - that option for trailers with the specified <token>. + that option for trailers with the specified <keyAlias>. -trailer.<token>.ifexists:: +trailer.<keyAlias>.ifexists:: This option takes the same values as the 'trailer.ifexists' configuration variable and it overrides what is specified by - that option for trailers with the specified <token>. + that option for trailers with the specified <keyAlias>. -trailer.<token>.ifmissing:: +trailer.<keyAlias>.ifmissing:: This option takes the same values as the 'trailer.ifmissing' configuration variable and it overrides what is specified by - that option for trailers with the specified <token>. + that option for trailers with the specified <keyAlias>. -trailer.<token>.command:: - This option behaves in the same way as 'trailer.<token>.cmd', except +trailer.<keyAlias>.command:: + Deprecated in favor of 'trailer.<keyAlias>.cmd'. + This option behaves in the same way as 'trailer.<keyAlias>.cmd', except that it doesn't pass anything as argument to the specified command. Instead the first occurrence of substring $ARG is replaced by the - value that would be passed as argument. + <value> that would be passed as argument. + -The 'trailer.<token>.command' option has been deprecated in favor of -'trailer.<token>.cmd' due to the fact that $ARG in the user's command is +Note that $ARG in the user's command is only replaced once and that the original way of replacing $ARG is not safe. + -When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given -for the same <token>, 'trailer.<token>.cmd' is used and -'trailer.<token>.command' is ignored. - -trailer.<token>.cmd:: - This option can be used to specify a shell command that will be called: - once to automatically add a trailer with the specified <token>, and then - each time a '--trailer <token>=<value>' argument to modify the <value> of - the trailer that this option would produce. +When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given +for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and +'trailer.<keyAlias>.command' is ignored. + +trailer.<keyAlias>.cmd:: + This option can be used to specify a shell command that will be called + once to automatically add a trailer with the specified <keyAlias>, and then + called each time a '--trailer <keyAlias>=<value>' argument is specified to + modify the <value> of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified <token>, the behavior is as if a special -'--trailer <token>=<value>' argument was added at the beginning +with the specified <keyAlias>, the behavior is as if a special +'--trailer <keyAlias>=<value>' argument was added at the beginning of the "git interpret-trailers" command, where <value> is taken to be the standard output of the command with any leading and trailing whitespace trimmed off. + -If some '--trailer <token>=<value>' arguments are also passed +If some '--trailer <keyAlias>=<value>' arguments are also passed on the command line, the command is called again once for each -of these arguments with the same <token>. And the <value> part +of these arguments with the same <keyAlias>. And the <value> part of these arguments, if any, will be passed to the command as its first argument. This way the command can produce a <value> computed -from the <value> passed in the '--trailer <token>=<value>' argument. +from the <value> passed in the '--trailer <keyAlias>=<value>' argument. EXAMPLES -------- * Configure a 'sign' trailer with a 'Signed-off-by' key, and then - add two of these trailers to a message: + add two of these trailers to a commit message file: + ------------ $ git config trailer.sign.key "Signed-off-by" $ cat msg.txt subject -message -$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' +body text +$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt subject -message +body text Signed-off-by: Alice <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------ -* Use the `--in-place` option to edit a message file in place: +* Use the `--in-place` option to edit a commit message file in place: + ------------ $ cat msg.txt subject -message +body text Signed-off-by: Bob <bob@example.com> $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt $ cat msg.txt subject -message +body text Signed-off-by: Bob <bob@example.com> Acked-by: Alice <alice@example.com> @@ -319,17 +377,30 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re 'Signed-off-by: ' already, and show how it works: + ------------ +$ cat msg1.txt +subject + +body text $ git config trailer.sign.key "Signed-off-by: " $ git config trailer.sign.ifmissing add $ git config trailer.sign.ifexists doNothing -$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"' -$ git interpret-trailers <<EOF -> EOF +$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"' +$ git interpret-trailers --trailer sign <msg1.txt +subject + +body text Signed-off-by: Bob <bob@example.com> -$ git interpret-trailers <<EOF -> Signed-off-by: Alice <alice@example.com> -> EOF +$ cat msg2.txt +subject + +body text + +Signed-off-by: Alice <alice@example.com> +$ git interpret-trailers --trailer sign <msg2.txt +subject + +body text Signed-off-by: Alice <alice@example.com> ------------ @@ -354,18 +425,17 @@ Fix #42 $ cat ~/bin/glog-find-author #!/bin/sh test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true +$ cat msg.txt +subject + +body text $ git config trailer.help.key "Helped-by: " $ git config trailer.help.ifExists "addIfDifferentNeighbor" $ git config trailer.help.cmd "~/bin/glog-find-author" -$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF -> subject -> -> message -> -> EOF +$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt subject -message +body text Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Christian Couder <christian.couder@gmail.com> @@ -379,18 +449,17 @@ Helped-by: Christian Couder <christian.couder@gmail.com> $ cat ~/bin/glog-grep #!/bin/sh test -n "$1" && git log --grep "$1" --pretty=reference -1 || true +$ cat msg.txt +subject + +body text $ git config trailer.ref.key "Reference-to: " $ git config trailer.ref.ifExists "replace" $ git config trailer.ref.cmd "~/bin/glog-grep" -$ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF -> subject -> -> message -> -> EOF +$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt subject -message +body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ @@ -399,20 +468,23 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) commit that is related, and show how it works: + ------------ +$ cat msg.txt +subject + +body text + +see: HEAD~2 +$ cat ~/bin/glog-ref +#!/bin/sh +git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14 $ git config trailer.see.key "See-also: " $ git config trailer.see.ifExists "replace" $ git config trailer.see.ifMissing "doNothing" -$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG" -$ git interpret-trailers <<EOF -> subject -> -> message -> -> see: HEAD~2 -> EOF +$ git config trailer.see.cmd "glog-ref" +$ git interpret-trailers --trailer=see <msg.txt subject -message +body text See-also: fe3187489d69c4 (subject of related commit) ------------ @@ -424,22 +496,21 @@ See-also: fe3187489d69c4 (subject of related commit) to add a 'git-version' trailer: + ------------ -$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF -> ***subject*** -> -> ***message*** -> -> Fixes: Z -> Cc: Z -> Reviewed-by: Z -> Signed-off-by: Z -> EOF +$ cat temp.txt +***subject*** + +***message*** + +Fixes: Z +Cc: Z +Reviewed-by: Z +Signed-off-by: Z +$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt $ git config commit.template commit_template.txt -$ cat >.git/hooks/commit-msg <<EOF -> #!/bin/sh -> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" -> mv "\$1.new" "\$1" -> EOF +$ cat .git/hooks/commit-msg +#!/bin/sh +git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" +mv "\$1.new" "\$1" $ chmod +x .git/hooks/commit-msg ------------ diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 20e87ce..5796821 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -45,13 +45,23 @@ OPTIONS --decorate-refs=<pattern>:: --decorate-refs-exclude=<pattern>:: - If no `--decorate-refs` is given, pretend as if all refs were - included. For each candidate, do not use it for decoration if it + For each candidate reference, do not use it for decoration if it matches any patterns given to `--decorate-refs-exclude` or if it doesn't match any of the patterns given to `--decorate-refs`. The `log.excludeDecoration` config option allows excluding refs from the decorations, but an explicit `--decorate-refs` pattern will override a match in `log.excludeDecoration`. ++ +If none of these options or config settings are given, then references are +used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, +`refs/stash/`, or `refs/tags/`. + +--clear-decorations:: + When specified, this option clears all previous `--decorate-refs` + or `--decorate-refs-exclude` options and relaxes the default + decoration filter to include all references. This option is + assumed if the config value `log.initialDecorationSet` is set to + `all`. --source:: Print out the ref name given on the command line by which each @@ -110,11 +120,11 @@ By default, `git log` does not generate any diff output. The options below can be used to show the changes made by each commit. Note that unless one of `--diff-merges` variants (including short -`-m`, `-c`, and `--cc` options) is explicitly given, merge commits +`-m`, `-c`, `--cc`, and `--dd` options) is explicitly given, merge commits will not show a diff, even if a diff format like `--patch` is selected, nor will they match search options like `-S`. The exception is when `--first-parent` is in use, in which case `first-parent` is -the default format. +the default format for merge commits. :git-log: 1 :diff-merges-default: `off` @@ -199,47 +209,11 @@ i18n.logOutputEncoding:: Defaults to the value of `i18n.commitEncoding` if set, and UTF-8 otherwise. -log.date:: - Default format for human-readable dates. (Compare the - `--date` option.) Defaults to "default", which means to write - dates like `Sat May 8 19:35:34 2010 -0500`. -+ -If the format is set to "auto:foo" and the pager is in use, format -"foo" will be the used for the date format. Otherwise "default" will -be used. - -log.follow:: - If `true`, `git log` will act as if the `--follow` option was used when - a single <path> is given. This has the same limitations as `--follow`, - i.e. it cannot be used to follow multiple files and does not work well - on non-linear history. - -log.showRoot:: - If `false`, `git log` and related commands will not treat the - initial commit as a big creation event. Any root commits in - `git log -p` output would be shown without a diff attached. - The default is `true`. - -log.showSignature:: - If `true`, `git log` and related commands will act as if the - `--show-signature` option was passed to them. - -mailmap.*:: - See linkgit:git-shortlog[1]. - -notes.displayRef:: - Which refs, in addition to the default set by `core.notesRef` - or `GIT_NOTES_REF`, to read notes from when showing commit - messages with the `log` family of commands. See - linkgit:git-notes[1]. -+ -May be an unabbreviated ref name or a glob and may be specified -multiple times. A warning will be issued for refs that do not exist, -but a glob that does not match any refs is silently ignored. -+ -This setting can be disabled by the `--no-notes` option, -overridden by the `GIT_NOTES_DISPLAY_REF` environment variable, -and overridden by the `--notes=<ref>` option. +include::includes/cmd-config-section-rest.txt[] + +include::config/log.txt[] + +include::config/notes.txt[] GIT --- diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 0dabf3f..d08c7da 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,8 +10,9 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] [-f] - [-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored] - [-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified] + [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored] + [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified] + [--resolve-undo] [--directory [--no-empty-directory]] [--eol] [--deduplicate] [-x <pattern>|--exclude=<pattern>] @@ -20,29 +21,34 @@ SYNOPSIS [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--recurse-submodules] - [--abbrev[=<n>]] [--] [<file>...] + [--abbrev[=<n>]] [--format=<format>] [--] [<file>...] DESCRIPTION ----------- -This merges the file listing in the index with the actual working +This command merges the file listing in the index with the actual working directory list, and shows different combinations of the two. -One or more of the options below may be used to determine the files -shown: +Several flags can be used to determine which files are +shown, and each file may be printed multiple times if there are +multiple entries in the index or if multiple statuses are applicable for +the relevant file selection options. OPTIONS ------- -c:: --cached:: - Show cached files in the output (default) + Show all files cached in Git's index, i.e. all tracked files. + (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo + options are specified.) -d:: --deleted:: - Show deleted files in the output + Show files with an unstaged deletion -m:: --modified:: - Show modified files in the output + Show files with an unstaged modification (note that an unstaged + deletion also counts as an unstaged modification) -o:: --others:: @@ -50,11 +56,14 @@ OPTIONS -i:: --ignored:: - Show only ignored files in the output. When showing files in the - index, print only those matched by an exclude pattern. When - showing "other" files, show only those matched by an exclude - pattern. Standard ignore rules are not automatically activated, - therefore at least one of the `--exclude*` options is required. + Show only ignored files in the output. Must be used with + either an explicit '-c' or '-o'. When showing files in the + index (i.e. when used with '-c'), print only those files + matching an exclude pattern. When showing "other" files + (i.e. when used with '-o'), show only those matched by an + exclude pattern. Standard ignore rules are not automatically + activated; therefore, at least one of the `--exclude*` options + is required. -s:: --stage:: @@ -63,19 +72,29 @@ OPTIONS --directory:: If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents. + Has no effect without -o/--others. --no-empty-directory:: Do not list empty directories. Has no effect without --directory. -u:: --unmerged:: - Show unmerged files in the output (forces --stage) + Show information about unmerged files in the output, but do + not show any other tracked files (forces --stage, overrides + --cached). -k:: --killed:: - Show files on the filesystem that need to be removed due - to file/directory conflicts for checkout-index to - succeed. + Show untracked files on the filesystem that need to be removed + due to file/directory conflicts for tracked files to be able to + be written to the filesystem. + +--resolve-undo:: + Show files having resolve-undo information in the index + together with their resolve-undo information. (resolve-undo + information is what is used to implement "git checkout -m + $PATH", i.e. to recreate merge conflicts that were + accidentally resolved) -z:: \0 line termination on output and do not quote filenames. @@ -100,7 +119,10 @@ OPTIONS --exclude-per-directory=<file>:: Read additional exclude patterns that apply only to the - directory and its subdirectories in <file>. + 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 @@ -118,24 +140,27 @@ OPTIONS with `-s` or `-u` options does not make any sense. -t:: - This feature is semi-deprecated. For scripting purpose, - linkgit:git-status[1] `--porcelain` and + Show status tags together with filenames. Note that for + scripting purposes, linkgit:git-status[1] `--porcelain` and linkgit:git-diff-files[1] `--name-status` are almost always - superior alternatives, and users should look at + superior alternatives; users should look at linkgit:git-status[1] `--short` or linkgit:git-diff[1] `--name-status` for more user-friendly alternatives. + -- -This option identifies the file status with the following tags (followed by -a space) at the start of each line: - - H:: cached - S:: skip-worktree - M:: unmerged - R:: removed/deleted - C:: modified/changed - K:: to be killed - ?:: other +This option provides a reason for showing each filename, in the form +of a status tag (which is followed by a space and then the filename). +The status tags are all single characters from the following list: + + H:: tracked file that is not either unmerged or skip-worktree + S:: tracked file that is skip-worktree + M:: tracked file that is unmerged + R:: tracked file with unstaged removal/deletion + C:: tracked file with unstaged modification/change + K:: untracked paths which are part of file/directory conflicts + which prevent checking out tracked files + ?:: untracked file + U:: file with resolve-undo information -- -v:: @@ -192,6 +217,13 @@ followed by the ("attr/<eolattr>"). to the contained files. Sparse directories will be shown with a trailing slash, such as "x/" for a sparse directory "x". +--format=<format>:: + A string that interpolates `%(fieldname)` from the result being shown. + 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). + --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo` + and `--eol`. \--:: Do not interpret any more arguments as options. @@ -223,6 +255,42 @@ quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). Using `-z` the filename is output verbatim and the line is terminated by a NUL byte. +It is possible to print in a custom format by using the `--format` +option, which is able to interpolate different fields using +a `%(fieldname)` notation. For example, if you only care about the +"objectname" and "path" fields, you can execute with a specific +"--format" like + + git ls-files --format='%(objectname) %(path)' + +FIELD NAMES +----------- +The way each path is shown can be customized by using the +`--format=<format>` option, where the %(fieldname) in the +<format> string for various aspects of the index entry are +interpolated. The following "fieldname" are understood: + +objectmode:: + The mode of the file which is recorded in the index. +objecttype:: + The object type of the file which is recorded in the index. +objectname:: + The name of the file which is recorded in the index. +objectsize[:padded]:: + The object size of the file which is recorded in the index + ("-" if the object is a `commit` or `tree`). + It also supports a padded format of size with "%(objectsize:padded)". +stage:: + The stage of the file which is recorded in the index. +eolinfo:index:: +eolinfo:worktree:: + The <eolinfo> (see the description of the `--eol` option) of + the contents in the index or in the worktree for the path. +eolattr:: + The <eolattr> (see the description of the `--eol` option) + that applies to the path. +path:: + The pathname of the file which is recorded in the index. EXCLUDE PATTERNS ---------------- @@ -232,7 +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. -These exclude patterns come from these 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 @@ -254,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-ls-remote.txt b/Documentation/git-ls-remote.txt index 492e573..1c4f696 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>] [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>] - [--symref] [<repository> [<refs>...]] + [--symref] [<repository> [<patterns>...]] DESCRIPTION ----------- @@ -85,31 +85,62 @@ OPTIONS either a URL or the name of a remote (see the GIT URLS and REMOTES sections of linkgit:git-fetch[1]). -<refs>...:: +<patterns>...:: When unspecified, all references, after filtering done - with --heads and --tags, are shown. When <refs>... are - specified, only references matching the given patterns - are displayed. + with --heads and --tags, are shown. When <patterns>... are + specified, only references matching one or more of the given + patterns are displayed. Each pattern is interpreted as a glob + (see `glob` in linkgit:gitglossary[7]) which is matched against + the "tail" of a ref, starting either from the start of the ref + (so a full name like `refs/heads/foo` matches) or from a slash + separator (so `bar` matches `refs/heads/bar` but not + `refs/heads/foobar`). + +OUTPUT +------ + +The output is in the format: + +------------ +<oid> TAB <ref> LF +------------ + +When showing an annotated tag, unless `--refs` is given, two such +lines are shown: one with the refname for the tag itself as `<ref>`, +and another with `<ref>` followed by `^{}`. The `<oid>` on the latter +line shows the name of the object the tag points at. EXAMPLES -------- +* List all references (including symbolics and pseudorefs), peeling + tags: ++ +---- +$ git ls-remote +27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} +---- + +* List all references matching given patterns: ++ ---- -$ git ls-remote --tags ./. -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen -$ git remote add korg http://www.kernel.org/pub/scm/git/git.git -$ git ls-remote --tags korg v\* -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 +---- + +* List only tags matching a given wildcard pattern: ++ +---- +$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\* +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- SEE ALSO diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 0240adb..6572095 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -86,9 +86,9 @@ OPTIONS --format=<format>:: A string that interpolates `%(fieldname)` from the result being shown. 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). + `%xNN` where `NN` are hex digits interpolates to character + with hex code `NN`; for example `%x00` interpolates to + `\0` (NUL), `%x09` to `\t` (TAB) and `%x0a` to `\n` (LF). When specified, `--format` cannot be combined with other format-altering options, including `--long`, `--name-only` and `--object-only`. @@ -145,7 +145,7 @@ FIELD NAMES ----------- Various values from structured fields can be used to interpolate -into the resulting output. For each outputing line, the following +into the resulting output. For each outputting line, the following names can be used: objectmode:: diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 3fcfd96..2806028 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used. <patch>:: The patch extracted from e-mail. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/mailinfo.txt[] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index e3b2a88..3f0a666 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -34,7 +34,7 @@ OPTIONS -b:: If any file doesn't begin with a From line, assume it is a - single mail message instead of signaling error. + single mail message instead of signaling an error. -d<prec>:: Instead of the default 4 digits with leading zeros, diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index e56bad2..51d0f7e 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git maintenance' run [<options>] 'git maintenance' start [--scheduler=<scheduler>] -'git maintenance' (stop|register|unregister) +'git maintenance' (stop|register|unregister) [<options>] DESCRIPTION @@ -50,13 +50,13 @@ stop:: the background maintenance is restarted later. register:: - Initialize Git config values so any scheduled maintenance will - start running on this repository. This adds the repository to the - `maintenance.repo` config variable in the current user's global - config and enables some recommended configuration values for - `maintenance.<task>.schedule`. The tasks that are enabled are safe - for running in the background without disrupting foreground - processes. + Initialize Git config values so any scheduled maintenance will start + running on this repository. This adds the repository to the + `maintenance.repo` config variable in the current user's global config, + or the config specified by --config-file option, and enables some + recommended configuration values for `maintenance.<task>.schedule`. The + tasks that are enabled are safe for running in the background without + disrupting foreground processes. + The `register` subcommand will also set the `maintenance.strategy` config value to `incremental`, if this value is not previously set. The @@ -79,6 +79,10 @@ unregister:: Remove the current repository from background maintenance. This only removes the repository from the configured list. It does not stop the background maintenance processes from running. ++ +The `unregister` subcommand will report an error if the current repository +is not already registered. Use the `--force` option to return success even +when the current repository is not registered. TASKS ----- @@ -98,9 +102,9 @@ prefetch:: requested refs within `refs/prefetch/`. Also, tags are not updated. + This is done to avoid disrupting the remote-tracking branches. The end users -expect these refs to stay unmoved unless they initiate a fetch. With prefetch -task, however, the objects necessary to complete a later real fetch would -already be obtained, so the real fetch would go faster. In the ideal case, +expect these refs to stay unmoved unless they initiate a fetch. However, +with the prefetch task, the objects necessary to complete a later real fetch +would already be obtained, making the real fetch faster. In the ideal case, it will just become an update to a bunch of remote-tracking branches without any object transfer. @@ -397,6 +401,13 @@ If you want to customize the background tasks, please rename the tasks so future calls to `git maintenance (start|stop)` do not overwrite your custom tasks. +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/maintenance.txt[] + GIT --- diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 2d944e0..5ab957c 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- [verse] -'git merge-base' [-a|--all] <commit> <commit>... -'git merge-base' [-a|--all] --octopus <commit>... +'git merge-base' [-a | --all] <commit> <commit>... +'git merge-base' [-a | --all] --octopus <commit>... 'git merge-base' --is-ancestor <commit> <commit> 'git merge-base' --independent <commit>... 'git merge-base' --fork-point <ref> [<commit>] @@ -18,7 +18,7 @@ SYNOPSIS DESCRIPTION ----------- -'git merge-base' finds best common ancestor(s) between two commits to use +'git merge-base' finds the best common ancestor(s) between two commits to use in a three-way merge. One common ancestor is 'better' than another common ancestor if the latter is an ancestor of the former. A common ancestor that does not have any better common ancestor is a 'best common @@ -28,7 +28,7 @@ merge base for a pair of commits. OPERATION MODES --------------- -As the most common special case, specifying only two commits on the +In the most common special case, specifying only two commits on the command line means computing the merge base between the given two commits. More generally, among the two commits to compute the merge base from, @@ -64,7 +64,7 @@ from linkgit:git-show-branch[1] when used with the `--merge-base` option. the two commits, but also takes into account the reflog of <ref> to see if the history leading to <commit> forked from an earlier incarnation of the branch <ref> (see discussion - on this mode below). + of this mode below). OPTIONS ------- @@ -88,7 +88,7 @@ For example, with this topology: the merge base between 'A' and 'B' is '1'. -Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the +Given three commits 'A', 'B', and 'C', `git merge-base A B C` will compute the merge base between 'A' and a hypothetical commit 'M', which is a merge between 'B' and 'C'. For example, with this topology: @@ -130,7 +130,7 @@ When the history involves criss-cross merges, there can be more than one ---2---o---o---B .... -both '1' and '2' are merge-bases of A and B. Neither one is better than +both '1' and '2' are merge bases of A and B. Neither one is better than the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. @@ -204,7 +204,7 @@ will find B0, and $ git rebase --onto origin/master $fork_point topic -will replay D0, D1 and D on top of B to create a new history of this +will replay D0, D1, and D on top of B to create a new history of this shape: .... diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 7e9093f..71915a0 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -11,19 +11,20 @@ SYNOPSIS [verse] 'git merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] - [--[no-]diff3] <current-file> <base-file> <other-file> + [--[no-]diff3] [--object-id] <current> <base> <other> DESCRIPTION ----------- -'git merge-file' incorporates all changes that lead from the `<base-file>` -to `<other-file>` into `<current-file>`. The result ordinarily goes into -`<current-file>`. 'git merge-file' is useful for combining separate changes -to an original. Suppose `<base-file>` is the original, and both -`<current-file>` and `<other-file>` are modifications of `<base-file>`, +Given three files `<current>`, `<base>` and `<other>`, +'git merge-file' incorporates all changes that lead from `<base>` +to `<other>` into `<current>`. The result ordinarily goes into +`<current>`. 'git merge-file' is useful for combining separate changes +to an original. Suppose `<base>` is the original, and both +`<current>` and `<other>` are modifications of `<base>`, then 'git merge-file' combines both changes. -A conflict occurs if both `<current-file>` and `<other-file>` have changes +A conflict occurs if both `<current>` and `<other>` have changes in a common segment of lines. If a conflict is found, 'git merge-file' normally outputs a warning and brackets the conflict with lines containing <<<<<<< and >>>>>>> markers. A typical conflict will look like this: @@ -36,10 +37,14 @@ normally outputs a warning and brackets the conflict with lines containing If there are conflicts, the user should edit the result and delete one of the alternatives. When `--ours`, `--theirs`, or `--union` option is in effect, -however, these conflicts are resolved favouring lines from `<current-file>`, -lines from `<other-file>`, or lines from both respectively. The length of the +however, these conflicts are resolved favouring lines from `<current>`, +lines from `<other>`, or lines from both respectively. The length of the conflict markers can be given with the `--marker-size` option. +If `--object-id` is specified, exactly the same behavior occurs, except that +instead of specifying what to merge as files, it is specified as a list of +object IDs referring to blobs. + The exit value of this program is negative on error, and the number of conflicts otherwise (truncated to 127 if there are more than that many conflicts). If the merge was clean, the exit value is 0. @@ -52,6 +57,14 @@ linkgit:git[1]. OPTIONS ------- +--object-id:: + Specify the contents to merge as blobs in the current repository instead of + files. In this case, the operation must take place within a valid repository. ++ +If the `-p` option is specified, the merged file (including conflicts, if any) +goes to standard output as normal; otherwise, the merged file is written to the +object store and the object ID of its blob is written to standard output. + -L <label>:: This option may be given up to three times, and specifies labels to be used in place of the @@ -62,7 +75,7 @@ OPTIONS -p:: Send results to standard output instead of overwriting - `<current-file>`. + `<current>`. -q:: Quiet; do not warn about conflicts. @@ -79,6 +92,12 @@ OPTIONS 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 -------- @@ -93,6 +112,11 @@ EXAMPLES merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels `a` and `c` instead of `tmp/a123` and `tmp/c345`. +`git merge-file -p --object-id abc1234 def567 890abcd`:: + + combines the changes of the blob abc1234 and 890abcd since def567, + tries to merge them and writes the result to standard output + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 58731c1..dd388fa 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -3,26 +3,316 @@ git-merge-tree(1) NAME ---- -git-merge-tree - Show three-way merge without touching index +git-merge-tree - Perform merge without touching index or working tree SYNOPSIS -------- [verse] -'git merge-tree' <base-tree> <branch1> <branch2> +'git merge-tree' [--write-tree] [<options>] <branch1> <branch2> +'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated) +[[NEWMERGE]] DESCRIPTION ----------- -Reads three tree-ish, and output trivial merge results and -conflicting stages to the standard output. This is similar to -what three-way 'git read-tree -m' does, but instead of storing the -results in the index, the command outputs the entries to the -standard output. - -This is meant to be used by higher level scripts to compute -merge results outside of the index, and stuff the results back into the -index. For this reason, the output from the command omits -entries that match the <branch1> tree. + +This command has a modern `--write-tree` mode and a deprecated +`--trivial-merge` mode. With the exception of the +<<DEPMERGE,DEPRECATED DESCRIPTION>> section at the end, the rest of +this documentation describes the modern `--write-tree` mode. + +Performs a merge, but does not make any new commits and does not read +from or write to either the working tree or index. + +The performed merge will use the same features as the "real" +linkgit:git-merge[1], including: + + * three way content merges of individual files + * rename detection + * proper directory/file conflict handling + * recursive ancestor consolidation (i.e. when there is more than one + merge base, creating a virtual merge base by merging the merge bases) + * etc. + +After the merge completes, a new toplevel tree object is created. See +`OUTPUT` below for details. + +OPTIONS +------- + +-z:: + Do not quote filenames in the <Conflicted file info> section, + and end each filename with a NUL character rather than + newline. Also begin the messages section with a NUL character + instead of a newline. See <<OUTPUT>> below for more information. + +--name-only:: + In the Conflicted file info section, instead of writing a list + of (mode, oid, stage, path) tuples to output for conflicted + files, just provide a list of filenames with conflicts (and + do not list filenames multiple times if they have multiple + conflicting stages). + +--[no-]messages:: + Write any informational messages such as "Auto-merging <path>" + or CONFLICT notices to the end of stdout. If unspecified, the + default is to include these messages if there are merge + conflicts, and to omit them otherwise. + +--allow-unrelated-histories:: + merge-tree will by default error out if the two branches specified + share no common history. This flag can be given to override that + check and make the merge proceed anyway. + +--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 +------ + +For a successful merge, the output from git-merge-tree is simply one +line: + + <OID of toplevel tree> + +Whereas for a conflicted merge, the output is by default of the form: + + <OID of toplevel tree> + <Conflicted file info> + <Informational messages> + +These are discussed individually below. + +However, there is an exception. If `--stdin` is passed, then there is +an extra section at the beginning, a NUL character at the end, and then +all the sections repeat for each line of input. Thus, if the first merge +is conflicted and the second is clean, the output would be of the form: + + <Merge status> + <OID of toplevel tree> + <Conflicted file info> + <Informational messages> + NUL + <Merge status> + <OID of toplevel tree> + NUL + +[[MS]] +Merge status +~~~~~~~~~~~~ + +This is an integer status followed by a NUL character. The integer status is: + + 0: merge had conflicts + 1: merge was clean + <0: something prevented the merge from running (e.g. access to repository + objects denied by filesystem) + +[[OIDTLT]] +OID of toplevel tree +~~~~~~~~~~~~~~~~~~~~ + +This is a tree object that represents what would be checked out in the +working tree at the end of `git merge`. If there were conflicts, then +files within this tree may have embedded conflict markers. This section +is always followed by a newline (or NUL if `-z` is passed). + +[[CFI]] +Conflicted file info +~~~~~~~~~~~~~~~~~~~~ + +This is a sequence of lines with the format + + <mode> <object> <stage> <filename> + +The filename will be quoted as explained for the configuration +variable `core.quotePath` (see linkgit:git-config[1]). However, if +the `--name-only` option is passed, the mode, object, and stage will +be omitted. If `-z` is passed, the "lines" are terminated by a NUL +character instead of a newline character. + +[[IM]] +Informational messages +~~~~~~~~~~~~~~~~~~~~~~ + +This section provides informational messages, typically about +conflicts. The format of the section varies significantly depending +on whether `-z` is passed. + +If `-z` is passed: + +The output format is zero or more conflict informational records, each +of the form: + + <list-of-paths><conflict-type>NUL<conflict-message>NUL + +where <list-of-paths> is of the form + + <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL + +and includes paths (or branch names) affected by the conflict or +informational message in <conflict-message>. Also, <conflict-type> is a +stable string explaining the type of conflict, such as + + * "Auto-merging" + * "CONFLICT (rename/delete)" + * "CONFLICT (submodule lacks merge base)" + * "CONFLICT (binary)" + +and <conflict-message> is a more detailed message about the conflict which often +(but not always) embeds the <stable-short-type-description> within it. These +strings may change in future Git versions. Some examples: + + * "Auto-merging <file>" + * "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..." + * "Failed to merge submodule <submodule> (no merge base)" + * "Warning: cannot merge binary files: <filename>" + +If `-z` is NOT passed: + +This section starts with a blank line to separate it from the previous +sections, and then only contains the <conflict-message> information +from the previous section (separated by newlines). These are +non-stable strings that should not be parsed by scripts, and are just +meant for human consumption. Also, note that while <conflict-message> +strings usually do not contain embedded newlines, they sometimes do. +(However, the free-form messages will never have an embedded NUL +character). So, the entire block of information is meant for human +readers as an agglomeration of all conflict messages. + +EXIT STATUS +----------- + +For a successful, non-conflicted merge, the exit status is 0. When the +merge has conflicts, the exit status is 1. If the merge is not able to +complete (or start) due to some kind of error, the exit status is +something other than 0 or 1 (and the output is unspecified). When +--stdin is passed, the return status is 0 for both successful and +conflicted merges, and something other than 0 or 1 if it cannot complete +all the requested merges. + +USAGE NOTES +----------- + +This command is intended as low-level plumbing, similar to +linkgit:git-hash-object[1], linkgit:git-mktree[1], +linkgit:git-commit-tree[1], linkgit:git-write-tree[1], +linkgit:git-update-ref[1], and linkgit:git-mktag[1]. Thus, it can be +used as a part of a series of steps such as: + + NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2) + test $? -eq 0 || die "There were conflicts..." + NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2) + git update-ref $BRANCH1 $NEWCOMMIT + +Note that when the exit status is non-zero, `NEWTREE` in this sequence +will contain a lot more output than just a tree. + +For conflicts, the output includes the same information that you'd get +with linkgit:git-merge[1]: + + * what would be written to the working tree (the + <<OIDTLT,OID of toplevel tree>>) + * the higher order stages that would be written to the index (the + <<CFI,Conflicted file info>>) + * any messages that would have been printed to stdout (the + <<IM,Informational messages>>) + +INPUT FORMAT +------------ +'git merge-tree --stdin' input format is fully text based. Each line +has this format: + + [<base-commit> -- ]<branch1> <branch2> + +If one line is separated by `--`, the string before the separator is +used for specifying a merge-base for the merge and the string after +the separator describes the branches to be merged. + +MISTAKES TO AVOID +----------------- + +Do NOT look through the resulting toplevel tree to try to find which +files conflict; parse the <<CFI,Conflicted file info>> section instead. +Not only would parsing an entire tree be horrendously slow in large +repositories, there are numerous types of conflicts not representable by +conflict markers (modify/delete, mode conflict, binary file changed on +both sides, file/directory conflicts, various rename conflict +permutations, etc.) + +Do NOT interpret an empty <<CFI,Conflicted file info>> list as a clean +merge; check the exit status. A merge can have conflicts without having +individual files conflict (there are a few types of directory rename +conflicts that fall into this category, and others might also be added +in the future). + +Do NOT attempt to guess or make the user guess the conflict types from +the <<CFI,Conflicted file info>> list. The information there is +insufficient to do so. For example: Rename/rename(1to2) conflicts (both +sides renamed the same file differently) will result in three different +files having higher order stages (but each only has one higher order +stage), with no way (short of the <<IM,Informational messages>> section) +to determine which three files are related. File/directory conflicts +also result in a file with exactly one higher order stage. +Possibly-involved-in-directory-rename conflicts (when +"merge.directoryRenames" is unset or set to "conflicts") also result in +a file with exactly one higher order stage. In all cases, the +<<IM,Informational messages>> section has the necessary info, though it +is not designed to be machine parseable. + +Do NOT assume that each path from <<CFI,Conflicted file info>>, and +the logical conflicts in the <<IM,Informational messages>> have a +one-to-one mapping, nor that there is a one-to-many mapping, nor a +many-to-one mapping. Many-to-many mappings exist, meaning that each +path can have many logical conflict types in a single merge, and each +logical conflict type can affect many paths. + +Do NOT assume all filenames listed in the <<IM,Informational messages>> +section had conflicts. Messages can be included for files that have no +conflicts, such as "Auto-merging <file>". + +AVOID taking the OIDS from the <<CFI,Conflicted file info>> and +re-merging them to present the conflicts to the user. This will lose +information. Instead, look up the version of the file found within the +<<OIDTLT,OID of toplevel tree>> and show that instead. In particular, +the latter will have conflict markers annotated with the original +branch/commit being merged and, if renames were involved, the original +filename. While you could include the original branch/commit in the +conflict marker annotations when re-merging, the original filename is +not available from the <<CFI,Conflicted file info>> and thus you would +be losing information that might help the user resolve the conflict. + +[[DEPMERGE]] +DEPRECATED DESCRIPTION +---------------------- + +Per the <<NEWMERGE,DESCRIPTION>> and unlike the rest of this +documentation, this section describes the deprecated `--trivial-merge` +mode. + +Other than the optional `--trivial-merge`, this mode accepts no +options. + +This mode reads three tree-ish, and outputs trivial merge results and +conflicting stages to the standard output in a semi-diff format. +Since this was designed for higher level scripts to consume and merge +the results back into the index, it omits entries that match +<branch1>. The result of this second form is similar to what +three-way 'git read-tree -m' does, but instead of storing the results +in the index, the command outputs the entries to the standard output. + +This form not only has limited applicability (a trivial merge cannot +handle content merges of individual files, rename detection, proper +directory/file conflict handling, etc.), the output format is also +difficult to work with, and it will generally be less performant than +the first form even on successful merges (especially if working in +large repositories). GIT --- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3125473..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,11 +33,12 @@ 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 -a log message from the user describing the changes. +a log message from the user describing the changes. Before the operation, +`ORIG_HEAD` is set to the tip of the current branch (`C`). ------------ A---B---C topic @@ -45,21 +46,21 @@ a log message from the user describing the changes. 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 @@ -73,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>:: @@ -90,10 +91,7 @@ invocations. The automated message can include the branch description. If `--log` is specified, a shortlog of the commits being merged will be appended to the specified message. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] --overwrite-ignore:: --no-overwrite-ignore:: @@ -106,14 +104,14 @@ will be appended to the specified message. 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:: @@ -122,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>...:: @@ -146,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,9 +194,13 @@ happens: versions: stage 1 stores the version from the common ancestor, stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you can inspect the stages with `git ls-files -u`). The working - tree files contain the result of the "merge" program; i.e. 3-way + tree files contain the result of the merge operation; i.e. 3-way merge results with familiar conflict markers `<<<` `===` `>>>`. -5. No other changes are made. In particular, the local +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). +6. No other changes are made. In particular, the local modifications you had before you started merge will stay the same and the index entries for them stay as they were, i.e. matching `HEAD`. @@ -267,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: @@ -326,19 +328,20 @@ 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: * Use a mergetool. `git mergetool` to launch a graphical - mergetool which will work you through the merge. + mergetool which will work through the merge with you. * Look at the diffs. `git diff` will show a three-way diff, highlighting changes from both the `HEAD` and `MERGE_HEAD` - versions. + versions. `git diff AUTO_MERGE` will show what changes you've + made so far to resolve textual conflicts. * Look at the diffs from each branch. `git log --merge -p <path>` will show diffs first for the `HEAD` version and then the @@ -386,13 +389,16 @@ include::merge-strategies.txt[] CONFIGURATION ------------- -include::config/merge.txt[] 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[] + +include::config/merge.txt[] + SEE ALSO -------- linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 3e8f59a..0726b56 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -28,22 +28,22 @@ to define the operation mode for the functions listed below. FUNCTIONS --------- get_merge_tool:: - returns a merge tool. the return code is 1 if we returned a guessed + Returns a merge tool. The return code is 1 if we returned a guessed merge tool, else 0. '$GIT_MERGETOOL_GUI' may be set to 'true' to search for the appropriate guitool. get_merge_tool_cmd:: - returns the custom command for a merge tool. + Returns the custom command for a merge tool. get_merge_tool_path:: - returns the custom path for a merge tool. + Returns the custom path for a merge tool. initialize_merge_tool:: - bring merge tool specific functions into scope so they can be used or + Brings merge tool specific functions into scope so they can be used or overridden. run_merge_tool:: - launches a merge tool given the tool name and a true/false + Launches a merge tool given the tool name and a true/false flag to indicate whether a merge base is present. '$MERGED', '$LOCAL', '$REMOTE', and '$BASE' must be defined for use by the merge tool. diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index f784027..b9e20c5 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -17,7 +17,7 @@ Use `git mergetool` to run one of several merge utilities to resolve merge conflicts. It is typically run after 'git merge'. If one or more <file> parameters are given, the merge tool program will -be run to resolve differences on each file (skipping those without +be run to resolve differences in each file (skipping those without conflicts). Specifying a directory will include all unresolved files in that path. If no <file> names are specified, 'git mergetool' will run the merge tool program on every file with merge conflicts. @@ -49,7 +49,7 @@ variable `mergetool.<tool>.cmd`. + When 'git mergetool' is invoked with this tool (either through the `-t` or `--tool` option or the `merge.tool` configuration -variable) the configured command line will be invoked with `$BASE` +variable), the configured command line will be invoked with `$BASE` set to the name of a temporary file containing the common base for the merge, if available; `$LOCAL` set to the name of a temporary file containing the contents of the file on the current branch; @@ -81,16 +81,17 @@ success of the resolution after the custom tool has exited. -g:: --gui:: - When 'git-mergetool' is invoked with the `-g` or `--gui` option + When 'git-mergetool' is invoked with the `-g` or `--gui` option, the default merge tool will be read from the configured `merge.guitool` variable instead of `merge.tool`. If `merge.guitool` is not set, we will fallback to the tool - configured under `merge.tool`. + configured under `merge.tool`. This may be autoselected using + the configuration variable `mergetool.guiDefault`. --no-gui:: - This overrides a previous `-g` or `--gui` setting and reads the - default merge tool will be read from the configured `merge.tool` - variable. + This overrides a previous `-g` or `--gui` setting or + `mergetool.guiDefault` configuration and reads the default merge + tool from the configured `merge.tool` variable. -O<orderfile>:: Process files in the order specified in the @@ -102,6 +103,9 @@ success of the resolution after the custom tool has exited. CONFIGURATION ------------- :git-mergetool: 1 + +include::includes/cmd-config-section-all.txt[] + include::config/mergetool.txt[] TEMPORARY FILES @@ -111,7 +115,7 @@ These are safe to remove once a file has been merged and its `git mergetool` session has completed. Setting the `mergetool.keepBackup` configuration variable to `false` -causes `git mergetool` to automatically remove the backup as files +causes `git mergetool` to automatically remove the backup files as files are successfully merged. BACKEND SPECIFIC HINTS diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 466a697..006d759 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -Reads a tag contents on standard input and creates a tag object. The +Reads a tag's contents on standard input and creates a tag object. The output is the new tag's <object> identifier. This command is mostly equivalent to linkgit:git-hash-object[1] @@ -27,13 +27,13 @@ write a tag found in `my-tag`: The difference is that mktag will die before writing the tag if the tag doesn't pass a linkgit:git-fsck[1] check. -The "fsck" check done mktag is stricter than what linkgit:git-fsck[1] +The "fsck" check done by mktag is stricter than what linkgit:git-fsck[1] would run by default in that all `fsck.<msg-id>` messages are promoted from warnings to errors (so e.g. a missing "tagger" line is an error). Extra headers in the object are also an error under mktag, but ignored by linkgit:git-fsck[1]. This extra check can be turned off by setting -the appropriate `fsck.<msg-id>` varible: +the appropriate `fsck.<msg-id>` variable: git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers @@ -56,7 +56,7 @@ has a very simple fixed format: four lines of tagger <tagger> followed by some 'optional' free-form message (some tags created -by older Git may not have `tagger` line). The message, when it +by older Git may not have a `tagger` line). The message, when it exists, is separated by a blank line from the header. The message part may contain a signature that Git itself doesn't care about, but that can be verified with gpg. diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 76b44f4..383f09d 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -25,13 +25,13 @@ OPTIONS --missing:: Allow missing objects. The default behaviour (without this option) - is to verify that each tree entry's sha1 identifies an existing + is to verify that each tree entry's hash identifies an existing object. This option has no effect on the treatment of gitlink entries (aka "submodules") which are always allowed to be missing. --batch:: Allow building of more than one tree object before exiting. Each - tree is separated by a single blank line. The final new-line is + tree is separated by a single blank line. The final newline is optional. Note - if the `-z` option is used, lines are terminated with NUL. diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index c588fb9..3696506 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -70,9 +70,10 @@ verify:: Verify the contents of the MIDX file. expire:: - Delete the pack-files that are tracked by the MIDX file, but - have no objects referenced by the MIDX. Rewrite the MIDX file - afterward to remove all references to these pack-files. + Delete the pack-files that are tracked by the MIDX file, but + have no objects referenced by the MIDX (with the exception of + `.keep` packs and cruft packs). Rewrite the MIDX file afterward + to remove all references to these pack-files. repack:: Create a new pack-file containing objects in small pack-files @@ -128,8 +129,8 @@ $ git multi-pack-index verify SEE ALSO -------- See link:technical/multi-pack-index.html[The Multi-Pack-Index Design -Document] and link:technical/pack-format.html[The Multi-Pack-Index -Format] for more information on the multi-pack-index feature. +Document] and linkgit:gitformat-pack[5] for more information on the +multi-pack-index feature and its file format. GIT diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 79449bf..dc1bf61 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -9,14 +9,14 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- [verse] -'git mv' <options>... <args>... +'git mv' [<options>] <source>... <destination> DESCRIPTION ----------- -Move or rename a file, directory or symlink. +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>. @@ -30,7 +30,7 @@ OPTIONS ------- -f:: --force:: - Force renaming or moving of a file even if the target exists + Force renaming or moving of a file even if the <destination> exists. -k:: Skip move or rename actions which would lead to an error condition. An error happens when a source is neither existing nor diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index ec8a27c..d4f1c4d 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git name-rev' [--tags] [--refs=<pattern>] - ( --all | --stdin | <commit-ish>... ) + ( --all | --annotate-stdin | <commit-ish>... ) DESCRIPTION ----------- @@ -26,7 +26,7 @@ OPTIONS --refs=<pattern>:: Only use refs whose names match a given shell pattern. The pattern - can be one of branch name, tag name or fully qualified ref name. If + can be a branch name, a tag name, or a fully qualified ref name. If given multiple times, use refs whose names match any of the given shell patterns. Use `--no-refs` to clear any previous ref patterns given. @@ -46,7 +46,8 @@ OPTIONS Transform stdin by substituting all the 40-character SHA-1 hexes (say $hex) with "$hex ($rev_name)". When used with --name-only, substitute with "$rev_name", omitting $hex - altogether. + altogether. This option was called `--stdin` in older versions + of Git. + For example: + @@ -70,10 +71,6 @@ The full name after substitution is master, while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad ----------- ---stdin:: - This option is deprecated in favor of 'git name-rev --annotate-stdin'. - They are functionally equivalent. - --name-only:: Instead of printing both the SHA-1 and the name, print only the name. If given with --tags the usual tag prefix of @@ -107,7 +104,7 @@ Now you are wiser, because you know that it happened 940 revisions before v0.99. Another nice thing you can do is: ------------ -% git log | git name-rev --stdin +% git log | git name-rev --annotate-stdin ------------ GIT diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 0a42006..c9221a6 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -9,10 +9,10 @@ SYNOPSIS -------- [verse] 'git notes' [list [<object>]] -'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] 'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] ) -'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] -'git notes' edit [--allow-empty] [<object>] +'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace] 'git notes' show [<object>] 'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> 'git notes' merge --commit [-v | -q] @@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary after a three dash separator line. To change which notes are shown by 'git log', see the -"notes.displayRef" configuration in linkgit:git-log[1]. +"notes.displayRef" discussion in <<CONFIGURATION>>. See the "notes.rewrite.<command>" configuration for a way to carry notes across commands that rewrite commits. @@ -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:: @@ -65,7 +65,9 @@ add:: However, if you're using `add` interactively (using an editor to supply the notes contents), then - instead of aborting - the existing notes will be opened in the editor (like the `edit` - subcommand). + subcommand). If you specify multiple `-m` and `-F`, a blank + line will be inserted between the messages. Use the `--separator` + option to insert other delimiters. copy:: Copy the notes for the first object onto the second object (defaults to @@ -85,8 +87,12 @@ corresponding <to-object>. (The optional `<rest>` is ignored so that the command can read the input given to the `post-rewrite` hook.) append:: - Append to the notes of an existing object (defaults to HEAD). - Creates a new notes object if needed. + Append new message(s) given by `-m` or `-F` options to an + existing note, or add them as a new note if one does not + exist, for the object (defaults to HEAD). When appending to + an existing note, a blank line is added before each new + message as an inter-paragraph separator. The separator can + be customized with the `--separator` option. edit:: Edit the notes for a given object (defaults to HEAD). @@ -136,6 +142,7 @@ OPTIONS are concatenated as separate paragraphs. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. + If you wish to keep them verbatim, use `--no-stripspace`. -F <file>:: --file=<file>:: @@ -143,12 +150,16 @@ OPTIONS read the note message from the standard input. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. + If you wish to keep them verbatim, use `--no-stripspace`. -C <object>:: --reuse-message=<object>:: Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to - copy notes between objects.) + copy notes between objects.). By default, message will be + copied verbatim, but if you wish to strip out the lines + starting with `#` and empty lines other than a single line + between paragraphs, use with`--stripspace` option. -c <object>:: --reedit-message=<object>:: @@ -159,6 +170,19 @@ OPTIONS Allow an empty note object to be stored. The default behavior is to automatically remove empty notes. +--[no-]separator, --separator=<paragraph-break>:: + Specify a string used as a custom inter-paragraph separator + (a newline is added at the end as needed). If `--no-separator`, no + separators will be added between paragraphs. Defaults to a blank + line. + +--[no-]stripspace:: + Strip leading and trailing whitespace from the note message. + Also strip out empty lines other than a single line between + paragraphs. Lines starting with `#` will be stripped out + in non-editor cases like `-m`, `-F` and `-C`, but not in + editor case like `git notes edit`, `-c`, etc. + --ref <ref>:: Manipulate the notes tree in <ref>. This overrides `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref @@ -307,6 +331,7 @@ with 'git log', so if you use such notes, you'll probably need to write some special-purpose tools to do something useful with them. +[[CONFIGURATION]] CONFIGURATION ------------- @@ -316,57 +341,9 @@ core.notesRef:: This setting can be overridden through the environment and command line. -notes.mergeStrategy:: - Which merge strategy to choose by default when resolving notes - conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or - `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" - section above for more information on each strategy. -+ -This setting can be overridden by passing the `--strategy` option. - -notes.<name>.mergeStrategy:: - Which merge strategy to choose when doing a notes merge into - refs/notes/<name>. This overrides the more general - "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above - for more information on each available strategy. +include::includes/cmd-config-section-rest.txt[] -notes.displayRef:: - Which ref (or refs, if a glob or specified more than once), in - addition to the default set by `core.notesRef` or - `GIT_NOTES_REF`, to read notes from when showing commit - messages with the 'git log' family of commands. - This setting can be overridden on the command line or by the - `GIT_NOTES_DISPLAY_REF` environment variable. - See linkgit:git-log[1]. - -notes.rewrite.<command>:: - When rewriting commits with <command> (currently `amend` or - `rebase`), if this variable is `false`, git will not copy - notes from the original to the rewritten commit. Defaults to - `true`. See also "`notes.rewriteRef`" below. -+ -This setting can be overridden by the `GIT_NOTES_REWRITE_REF` -environment variable. - -notes.rewriteMode:: - When copying notes during a rewrite, what to do if the target - commit already has a note. Must be one of `overwrite`, - `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to - `concatenate`. -+ -This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` -environment variable. - -notes.rewriteRef:: - When copying notes during a rewrite, specifies the (fully - qualified) ref whose notes should be copied. May be a glob, - in which case notes in all matching refs will be copied. You - may also specify this configuration several times. -+ -Does not have a default value; you must configure this variable to -enable note rewriting. -+ -Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable. +include::config/notes.txt[] ENVIRONMENT diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index a9995a9..e32404c 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -116,9 +116,7 @@ unreachable object whose mtime is newer than the `--cruft-expiration`). + Incompatible with `--unpack-unreachable`, `--keep-unreachable`, `--pack-loose-unreachable`, `--stdin-packs`, as well as any other -options which imply `--revs`. Also incompatible with `--max-pack-size`; -when this option is set, the maximum pack size is not inferred from -`pack.packSizeLimit`. +options which imply `--revs`. --cruft-expiration=<approxidate>:: If specified, objects are eliminated from the cruft pack if they @@ -298,8 +296,8 @@ So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. nevertheless. --filter=<filter-spec>:: - Requires `--stdout`. Omits certain objects (usually blobs) from - the resulting packfile. See linkgit:git-rev-list[1] for valid + Omits certain objects (usually blobs) from the resulting + packfile. See linkgit:git-rev-list[1] for valid `<filter-spec>` forms. --no-filter:: diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index ee7034b..13c3eb5 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -9,7 +9,21 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- [verse] -'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... ) +'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...) + +WARNING +------- +`git pack-redundant` has been deprecated and is scheduled for removal in +a future version of Git. Because it can only remove entire duplicate +packs and not individual duplicate objects, it is generally not a useful +tool for reducing repository size. You are better off using `git gc` to +do so, which will put objects into a new pack, removing duplicates. + +Running `pack-redundant` without the `--i-still-use-this` flag will fail +in this release. If you believe you have a use case for which +`pack-redundant` is better suited and oppose this removal, please +contact the Git mailing list at git@vger.kernel.org. More information +about the list is available at https://git-scm.com/community. DESCRIPTION ----------- @@ -34,7 +48,7 @@ OPTIONS --alt-odb:: Don't require objects present in packs from alternate object - directories to be present in local packs. + database (odb) directories to be present in local packs. --verbose:: Outputs some statistics to stderr. Has a small performance penalty. diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 154081f..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] +'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>] DESCRIPTION ----------- @@ -51,14 +51,50 @@ The command by default packs all tags and refs that are already packed, and leaves other refs alone. This is because branches are expected to be actively developed and packing their tips does not help performance. -This option causes branch tips to be packed as well. Useful for -a repository with many branches of historical interests. +This option causes all refs to be packed as well, with the exception +of hidden refs, broken refs, and symbolic refs. Useful for a repository +with many branches of historical interests. --no-prune:: 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 +accumulate inclusion patterns. If a ref is both included in `--include` and +`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all +tags from being included by default. Symbolic refs and broken refs will never +be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear +and reset the list of patterns. + +--exclude <pattern>:: + +Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option +accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of +patterns. If a ref is already packed, including it with `--exclude` will not +unpack it. + +When used with `--all`, pack only loose refs which do not match any of +the provided `--exclude` patterns. + +When used with `--include`, refs provided to `--include`, minus refs that are +provided to `--exclude` will be packed. + BUGS ---- diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 442caff..1d15fa4 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -8,18 +8,18 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- [verse] -'git patch-id' [--stable | --unstable] +'git patch-id' [--stable | --unstable | --verbatim] DESCRIPTION ----------- Read a patch from the standard input and compute the patch ID for it. A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a -patch, with whitespace and line numbers ignored. As such, it's "reasonably -stable", but at the same time also reasonably unique, i.e., two patches that -have the same "patch ID" are almost guaranteed to be the same thing. +patch, with line numbers ignored. As such, it's "reasonably stable", but at +the same time also reasonably unique, i.e., two patches that have the same +"patch ID" are almost guaranteed to be the same thing. -IOW, you can use this thing to look for likely duplicate commits. +The main usecase for this command is to look for likely duplicate commits. When dealing with 'git diff-tree' output, it takes advantage of the fact that the patch is prefixed with the object name of the @@ -30,6 +30,12 @@ This can be used to make a mapping from patch ID to commit ID. OPTIONS ------- +--verbatim:: + Calculate the patch-id of the input as it is given, do not strip + any whitespace. + + This is the default if patchid.verbatim is true. + --stable:: Use a "stable" sum of hashes as the patch ID. With this option: - Reordering file diffs that make up a patch does not affect the ID. @@ -45,14 +51,16 @@ OPTIONS of "-O<orderfile>", thereby making existing databases storing such "unstable" or historical patch-ids unusable. + - All whitespace within the patch is ignored and does not affect the id. + This is the default if patchid.stable is set to true. --unstable:: Use an "unstable" hash as the patch ID. With this option, the result produced is compatible with the patch-id value produced - by git 1.9 and older. Users with pre-existing databases storing - patch-ids produced by git 1.9 and older (who do not deal with reordered - patches) may want to use this option. + by git 1.9 and older and whitespace is ignored. Users with pre-existing + databases storing patch-ids produced by git 1.9 and older (who do not deal + with reordered patches) may want to use this option. This is the default. diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 9fed59a..db742dc 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -9,13 +9,13 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- [verse] -'git prune-packed' [-n|--dry-run] [-q|--quiet] +'git prune-packed' [-n | --dry-run] [-q | --quiet] DESCRIPTION ----------- This program searches the `$GIT_OBJECT_DIRECTORY` for all objects that currently -exist in a pack file as well as the independent object directories. +exist in a pack file as well as in the independent object directories. All such extra objects are removed. diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 03552dd..9a45571 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -18,7 +18,7 @@ NOTE: In most cases, users should run 'git gc', which calls 'git prune'. See the section "NOTES", below. This runs 'git fsck --unreachable' using all the refs -available in `refs/`, optionally with additional set of +available in `refs/`, optionally with an additional set of objects specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the object database. In addition, it 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-push.txt b/Documentation/git-push.txt index 2f25aa3..9b7cfbc 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,8 +9,8 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] +'git push' [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] + [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose] [-u | --set-upstream] [-o <string> | --push-option=<string>] [--[no-]signed|--signed=(true|false|if-asked)] [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]] @@ -37,7 +37,7 @@ the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide what to push (See linkgit:git-config[1] for the meaning of `push.default`). -When neither the command-line nor the configuration specify what to +When neither the command-line nor the configuration specifies what to push, the default behavior is used, which corresponds to the `simple` value for `push.default`: the current branch is pushed to the corresponding upstream branch, but as a safety measure, the push is @@ -48,7 +48,7 @@ local one. OPTIONS[[OPTIONS]] ------------------ <repository>:: - The "remote" repository that is destination of a push + The "remote" repository that is the destination of a push operation. This parameter can be either a URL (see the section <<URLS,GIT URLS>> below) or the name of a remote (see the section <<REMOTES,REMOTES>> below). @@ -147,6 +147,7 @@ already exists on the remote side. `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. --all:: +--branches:: Push all branches (i.e. refs under `refs/heads/`); cannot be used with other <refspec>. @@ -409,10 +410,14 @@ Specifying `--no-force-if-includes` disables this behavior. all submodules that changed in the revisions to be pushed will be pushed. If on-demand was not able to push all necessary revisions it will also be aborted and exit with non-zero status. If 'only' is used all - submodules will be recursively pushed while the superproject is left + submodules will be pushed while the superproject is left unpushed. A value of 'no' or using `--no-recurse-submodules` can be used to override the push.recurseSubmodules configuration variable when no submodule recursion is required. ++ +When using 'on-demand' or 'only', if a submodule has a +"push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration, +further recursion will occur. In this case, "only" is treated as "on-demand". --[no-]verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The @@ -692,6 +697,13 @@ a `git gc` command on the origin repository. include::transfer-data-leaks.txt[] +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/push.txt[] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 70562dc..40e02d9 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -38,14 +38,14 @@ OPTIONS a patch. At the time of this writing only missing author information is warned about. ---author Author Name <Author Email>:: +--author 'Author Name <Author Email>':: The author name and email address to use when no author information can be found in the patch description. --patches <dir>:: The directory to find the quilt patches. + -The default for the patch directory is patches +The default for the patch directory is 'patches' or the value of the `$QUILT_PATCHES` environment variable. diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt index fe350d7..fbdbe0b 100644 --- a/Documentation/git-range-diff.txt +++ b/Documentation/git-range-diff.txt @@ -12,6 +12,7 @@ SYNOPSIS [--no-dual-color] [--creation-factor=<factor>] [--left-only | --right-only] ( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> ) + [[--] <path>...] DESCRIPTION ----------- @@ -19,6 +20,9 @@ DESCRIPTION This command shows the differences between two versions of a patch series, or more generally, two commit ranges (ignoring merge commits). +In the presence of `<path>` arguments, these commit ranges are limited +accordingly. + To that end, it first finds pairs of commits from both commit ranges that correspond with each other. Two commits are said to correspond when the diff between their patches (i.e. the author information, the commit @@ -66,7 +70,7 @@ to revert to color all lines according to the outer diff markers Defaults to 60. Try a larger value if `git range-diff` erroneously considers a large change a total rewrite (deletion of one commit and addition of another), and a smaller one in the reverse case. - See the ``Algorithm`` section below for an explanation why this is + See the ``Algorithm`` section below for an explanation of why this is needed. --left-only:: @@ -162,7 +166,7 @@ A typical output of `git range-diff` would look like this: In this example, there are 3 old and 3 new commits, where the developer removed the 3rd, added a new one before the first two, and modified the -commit message of the 2nd commit as well its diff. +commit message of the 2nd commit as well as its diff. When the output goes to a terminal, it is color-coded by default, just like regular `git diff`'s output. In addition, the first line (adding a diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index b9bfdc0..1c48c28 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- [verse] -'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] +'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>) [-u | -i]] [--index-output=<file>] [--no-sparse-checkout] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) @@ -25,15 +25,15 @@ fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` flag. When used with `-m`, the `-u` flag causes it to also update the files in the work tree with the result of the merge. -Trivial merges are done by 'git read-tree' itself. Only conflicting paths -will be in unmerged state when 'git read-tree' returns. +Only trivial merges are done by 'git read-tree' itself. Only conflicting paths +will be in an unmerged state when 'git read-tree' returns. OPTIONS ------- -m:: Perform a merge, not just a read. The command will refuse to run if your index file has unmerged entries, - indicating that you have not finished previous merge you + indicating that you have not finished a previous merge you started. --reset:: @@ -219,7 +219,7 @@ see which of the "local changes" that you made were carried forward by running `git diff-index --cached $M`. Note that this does not necessarily match what `git diff-index --cached $H` would have produced before such a two tree merge. This is because of cases -18 and 19 --- if you already had the changes in $M (e.g. maybe +18 and 19 -- if you already had the changes in $M (e.g. maybe you picked it up via e-mail in a patch form), `git diff-index --cached $H` would have told you about the change before this merge, but it would not show in `git diff-index --cached $M` diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 262fb01..74df345 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -12,44 +12,51 @@ 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 ----------- -If <branch> is specified, 'git rebase' will perform an automatic +If `<branch>` is specified, `git rebase` will perform an automatic `git switch <branch>` before doing anything else. Otherwise it remains on the current branch. -If <upstream> is not specified, the upstream configured in -branch.<name>.remote and branch.<name>.merge options will be used (see +If `<upstream>` is not specified, the upstream configured in +`branch.<name>.remote` and `branch.<name>.merge` options will be used (see linkgit:git-config[1] for details) and the `--fork-point` option is assumed. If you are currently not on any branch or if the current branch does not have a configured upstream, the rebase will abort. All changes made by commits in the current branch but that are not -in <upstream> are saved to a temporary area. This is the same set +in `<upstream>` are saved to a temporary area. This is the same set of commits that would be shown by `git log <upstream>..HEAD`; or by `git log 'fork_point'..HEAD`, if `--fork-point` is active (see the description on `--fork-point` below); or by `git log HEAD`, if the `--root` option is specified. -The current branch is reset to <upstream>, or <newbase> if the ---onto option was supplied. This has the exact same effect as -`git reset --hard <upstream>` (or <newbase>). ORIG_HEAD is set +The current branch is reset to `<upstream>` or `<newbase>` if the +`--onto` option was supplied. This has the exact same effect as +`git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set to point at the tip of the branch before the reset. +[NOTE] +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip +at the end of the rebase if other commands that write that pseudo-ref +(e.g. `git reset`) are used during the rebase. The previous branch tip, +however, is accessible using the reflog of the current branch +(i.e. `@{1}`, see linkgit:gitrevisions[7]). + The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that -any commits in HEAD which introduce the same textual changes as a commit -in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream +any commits in `HEAD` which introduce the same textual changes as a commit +in `HEAD..<upstream>` are omitted (i.e., a patch already accepted upstream with a different commit message or timestamp will be skipped). It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure and run `git rebase --continue`. Another option is to bypass the commit that caused the merge failure with `git rebase --skip`. To check out the -original <branch> and remove the .git/rebase-apply working files, use the -command `git rebase --abort` instead. +original `<branch>` and remove the `.git/rebase-apply` working files, use +the command `git rebase --abort` instead. Assume the following history exists and the current branch is "topic": @@ -79,7 +86,7 @@ remain the checked-out branch. If the upstream branch already contains a change you have made (e.g., because you mailed a patch which was applied upstream), then that commit -will be skipped and warnings will be issued (if the `merge` backend is +will be skipped and warnings will be issued (if the 'merge' backend is used). For example, running `git rebase master` on the following history (in which `A'` and `A` introduce the same set of changes, but have different committer information): @@ -176,11 +183,11 @@ would result in the removal of commits F and G: ------------ This is useful if F and G were flawed in some way, or should not be -part of topicA. Note that the argument to --onto and the <upstream> +part of topicA. Note that the argument to `--onto` and the `<upstream>` parameter can be any valid commit-ish. -In case of conflict, 'git rebase' will stop at the first problematic commit -and leave conflict markers in the tree. You can use 'git diff' to locate +In case of conflict, `git rebase` will stop at the first problematic commit +and leave conflict markers in the tree. You can use `git diff` to locate the markers (<<<<<<) and make edits to resolve the conflict. For each file you edit, you need to tell Git that the conflict has been resolved, typically this would be done with @@ -201,12 +208,45 @@ Alternatively, you can undo the 'git rebase' with git rebase --abort +MODE OPTIONS +------------ + +The options in this section cannot be used with any other option, +including not with each other: + +--continue:: + Restart the rebasing process after having resolved a merge conflict. + +--skip:: + Restart the rebasing process by skipping the current patch. + +--abort:: + Abort the rebase operation and reset HEAD to the original + branch. If `<branch>` was provided when the rebase operation was + started, then `HEAD` will be reset to `<branch>`. Otherwise `HEAD` + will be reset to where it was when the rebase operation was + started. + +--quit:: + Abort the rebase operation but `HEAD` is not reset back to the + original branch. The index and working tree are also left + unchanged as a result. If a temporary stash entry was created + using `--autostash`, it will be saved to the stash list. + +--edit-todo:: + Edit the todo list during an interactive rebase. + +--show-current-patch:: + Show the current patch in an interactive rebase or when rebase + is stopped because of conflicts. This is the equivalent of + `git show REBASE_HEAD`. + OPTIONS ------- --onto <newbase>:: Starting point at which to create the new commits. If the - --onto option is not specified, the starting point is - <upstream>. May be any valid commit, and not just an + `--onto` option is not specified, the starting point is + `<upstream>`. May be any valid commit, and not just an existing branch name. + As a special case, you may use "A\...B" as a shortcut for the @@ -215,19 +255,21 @@ leave out at most one of A and B, in which case it defaults to HEAD. --keep-base:: Set the starting point at which to create the new commits to the - merge base of <upstream> and <branch>. Running - 'git rebase --keep-base <upstream> <branch>' is equivalent to + merge base of `<upstream>` and `<branch>`. Running + `git rebase --keep-base <upstream> <branch>` is equivalent to running - 'git rebase --onto <upstream>...<branch> <upstream> <branch>'. + `git rebase --reapply-cherry-picks --no-fork-point --onto <upstream>...<branch> <upstream> <branch>`. + This option is useful in the case where one is developing a feature on top of an upstream branch. While the feature is being worked on, the upstream branch may advance and it may not be the best idea to keep -rebasing on top of the upstream but to keep the base commit as-is. +rebasing on top of the upstream but to keep the base commit as-is. As +the base commit is unchanged this option implies `--reapply-cherry-picks` +to avoid losing commits. + -Although both this option and --fork-point find the merge base between -<upstream> and <branch>, this option uses the merge base as the _starting -point_ on which new commits will be created, whereas --fork-point uses +Although both this option and `--fork-point` find the merge base between +`<upstream>` and `<branch>`, this option uses the merge base as the _starting +point_ on which new commits will be created, whereas `--fork-point` uses the merge base to determine the _set of commits_ which will be rebased. + See also INCOMPATIBLE OPTIONS below. @@ -238,23 +280,7 @@ See also INCOMPATIBLE OPTIONS below. upstream for the current branch. <branch>:: - Working branch; defaults to HEAD. - ---continue:: - Restart the rebasing process after having resolved a merge conflict. - ---abort:: - Abort the rebase operation and reset HEAD to the original - branch. If <branch> was provided when the rebase operation was - started, then HEAD will be reset to <branch>. Otherwise HEAD - will be reset to where it was when the rebase operation was - started. - ---quit:: - Abort the rebase operation but HEAD is not reset back to the - original branch. The index and working tree are also left - unchanged as a result. If a temporary stash entry was created - using --autostash, it will be saved to the stash list. + Working branch; defaults to `HEAD`. --apply:: Use applying strategies to rebase (calling `git-am` @@ -263,22 +289,31 @@ 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 +Note that commits which start empty are kept (unless `--no-keep-empty` is specified), and commits which are clean cherry-picks (as determined by `git log --cherry-mark ...`) are detected and dropped as a -preliminary step (unless --reapply-cherry-picks is passed). +preliminary step (unless `--reapply-cherry-picks` or `--keep-base` is +passed). + See also INCOMPATIBLE OPTIONS below. @@ -287,7 +322,7 @@ See also INCOMPATIBLE OPTIONS below. Do not keep commits that start empty before the rebase (i.e. that do not change anything from its parent) in the result. The default is to keep commits which start empty, - since creating such commits requires passing the --allow-empty + since creating such commits requires passing the `--allow-empty` override flag to `git commit`, signifying that a user is very intentionally creating such a commit and thus wants to keep it. @@ -299,7 +334,7 @@ flag exists as a convenient shortcut, such as for cases where external tools generate many empty commits and you want them all removed. + For commits which do not start empty but become empty after rebasing, -see the --empty flag. +see the `--empty` flag. + See also INCOMPATIBLE OPTIONS below. @@ -311,13 +346,14 @@ See also INCOMPATIBLE OPTIONS below. upstream changes, the behavior towards them is controlled by the `--empty` flag.) + -By default (or if `--no-reapply-cherry-picks` is given), these commits -will be automatically dropped. Because this necessitates reading all -upstream commits, this can be expensive in repos with a large number -of upstream commits that need to be read. When using the `merge` -backend, warnings will be issued for each dropped commit (unless -`--quiet` is given). Advice will also be issued unless -`advice.skippedCherryPicks` is set to false (see linkgit:git-config[1]). +In the absence of `--keep-base` (or if `--no-reapply-cherry-picks` is +given), these commits will be automatically dropped. Because this +necessitates reading all upstream commits, this can be expensive in +repositories with a large number of upstream commits that need to be +read. When using the 'merge' backend, warnings will be issued for each +dropped commit (unless `--quiet` is given). Advice will also be issued +unless `advice.skippedCherryPicks` is set to false (see +linkgit:git-config[1]). + `--reapply-cherry-picks` allows rebase to forgo reading all upstream commits, potentially improving performance. @@ -332,26 +368,15 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. ---skip:: - Restart the rebasing process by skipping the current patch. - ---edit-todo:: - Edit the todo list during an interactive rebase. - ---show-current-patch:: - Show the current patch in an interactive rebase or when rebase - is stopped because of conflicts. This is the equivalent of - `git show REBASE_HEAD`. - -m:: --merge:: Using merging strategies to rebase (default). + Note that a rebase merge works by replaying each commit from the working -branch on top of the <upstream> branch. Because of this, when a merge +branch on top of the `<upstream>` branch. Because of this, when a merge conflict happens, the side reported as 'ours' is the so-far rebased -series, starting with <upstream>, and 'theirs' is the working branch. In -other words, the sides are swapped. +series, starting with `<upstream>`, and 'theirs' is the working branch. +In other words, the sides are swapped. + See also INCOMPATIBLE OPTIONS below. @@ -360,9 +385,9 @@ See also INCOMPATIBLE OPTIONS below. Use the given merge strategy, instead of the default `ort`. This implies `--merge`. + -Because 'git rebase' replays each commit from the working branch -on top of the <upstream> branch using the given strategy, using -the 'ours' strategy simply empties all patches from the <branch>, +Because `git rebase` replays each commit from the working branch +on top of the `<upstream>` branch using the given strategy, using +the `ours` strategy simply empties all patches from the `<branch>`, which makes little sense. + See also INCOMPATIBLE OPTIONS below. @@ -376,10 +401,7 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -392,11 +414,11 @@ See also INCOMPATIBLE OPTIONS below. -q:: --quiet:: - Be quiet. Implies --no-stat. + Be quiet. Implies `--no-stat`. -v:: --verbose:: - Be verbose. Implies --stat. + Be verbose. Implies `--stat`. --stat:: Show a diffstat of what changed upstream since the last rebase. The @@ -411,13 +433,13 @@ See also INCOMPATIBLE OPTIONS below. --verify:: Allows the pre-rebase hook to run, which is the default. This option can - be used to override --no-verify. See also linkgit:githooks[5]. + be used to override `--no-verify`. See also linkgit:githooks[5]. -C<n>:: - Ensure at least <n> lines of surrounding context match before + Ensure at least `<n>` lines of surrounding context match before and after each change. When fewer lines of surrounding context exist they all must match. By default no context is - ever ignored. Implies --apply. + ever ignored. Implies `--apply`. + See also INCOMPATIBLE OPTIONS below. @@ -436,21 +458,21 @@ details). --fork-point:: --no-fork-point:: - Use reflog to find a better common ancestor between <upstream> - and <branch> when calculating which commits have been - introduced by <branch>. + Use reflog to find a better common ancestor between `<upstream>` + and `<branch>` when calculating which commits have been + introduced by `<branch>`. + -When --fork-point is active, 'fork_point' will be used instead of -<upstream> to calculate the set of commits to rebase, where +When `--fork-point` is active, 'fork_point' will be used instead of +`<upstream>` to calculate the set of commits to rebase, where 'fork_point' is the result of `git merge-base --fork-point <upstream> <branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' -ends up being empty, the <upstream> will be used as a fallback. +ends up being empty, the `<upstream>` will be used as a fallback. + -If <upstream> is given on the command line, then the default is -`--no-fork-point`, otherwise the default is `--fork-point`. See also -`rebase.forkpoint` in linkgit:git-config[1]. +If `<upstream>` or `--keep-base` is given on the command line, then +the default is `--no-fork-point`, otherwise the default is +`--fork-point`. See also `rebase.forkpoint` in linkgit:git-config[1]. + -If your branch was based on <upstream> but <upstream> was rewound and +If your branch was based on `<upstream>` but `<upstream>` was rewound and your branch contains commits which were dropped, this option can be used with `--keep-base` in order to drop those commits from your branch. + @@ -458,24 +480,26 @@ See also INCOMPATIBLE OPTIONS below. --ignore-whitespace:: Ignore whitespace differences when trying to reconcile -differences. Currently, each backend implements an approximation of -this behavior: + differences. Currently, each backend implements an approximation of + this behavior: + -apply backend: When applying a patch, ignore changes in whitespace in -context lines. Unfortunately, this means that if the "old" lines being -replaced by the patch differ only in whitespace from the existing -file, you will get a merge conflict instead of a successful patch -application. +apply backend;; + When applying a patch, ignore changes in whitespace in context + lines. Unfortunately, this means that if the "old" lines being + replaced by the patch differ only in whitespace from the existing + file, you will get a merge conflict instead of a successful patch + application. + -merge backend: Treat lines with only whitespace changes as unchanged -when merging. Unfortunately, this means that any patch hunks that were -intended to modify whitespace and nothing else will be dropped, even -if the other side had no changes that conflicted. +merge backend;; + Treat lines with only whitespace changes as unchanged when merging. + Unfortunately, this means that any patch hunks that were intended + to modify whitespace and nothing else will be dropped, even if the + other side had no changes that conflicted. --whitespace=<option>:: - This flag is passed to the 'git apply' program + This flag is passed to the `git apply` program (see linkgit:git-apply[1]) that applies the patch. - Implies --apply. + Implies `--apply`. + See also INCOMPATIBLE OPTIONS below. @@ -507,26 +531,31 @@ 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. -r:: --rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: +--no-rebase-merges:: By default, a rebase will simply drop merge commits from the todo list, and put the rebased commits into a single, linear branch. With `--rebase-merges`, the rebase will instead try to preserve the branching structure within the commits that are to be rebased, by recreating the merge commits. Any resolved merge conflicts or manual amendments in these merge commits will have to be - resolved/re-applied manually. + resolved/re-applied manually. `--no-rebase-merges` can be used to + countermand both the `rebase.rebaseMerges` config option and a previous + `--rebase-merges`. + -By default, or when `no-rebase-cousins` was specified, commits which do not -have `<upstream>` as direct ancestor will keep their original branch point, -i.e. commits that would be excluded by linkgit:git-log[1]'s -`--ancestry-path` option will keep their original ancestry by default. If -the `rebase-cousins` mode is turned on, such commits are instead rebased -onto `<upstream>` (or `<onto>`, if specified). +When rebasing merges, there are two modes: `rebase-cousins` and +`no-rebase-cousins`. If the mode is not specified, it defaults to +`no-rebase-cousins`. In `no-rebase-cousins` mode, commits which do not have +`<upstream>` as direct ancestor will keep their original branch point, i.e. +commits that would be excluded by linkgit:git-log[1]'s `--ancestry-path` +option will keep their original ancestry by default. In `rebase-cousins` mode, +such commits are instead rebased onto `<upstream>` (or `<onto>`, if +specified). + It is currently only possible to recreate the merge commits using the `ort` merge strategy; different merge strategies can be used only via @@ -537,7 +566,7 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS below. -x <cmd>:: --exec <cmd>:: Append "exec <cmd>" after each line creating a commit in the - final history. <cmd> will be interpreted as one or more shell + final history. `<cmd>` will be interpreted as one or more shell commands. Any command that fails will interrupt the rebase, with exit code 1. + @@ -550,7 +579,7 @@ or by giving more than one `--exec`: + git rebase -i --exec "cmd1" --exec "cmd2" --exec ... + -If `--autosquash` is used, "exec" lines will not be appended for +If `--autosquash` is used, `exec` lines will not be appended for the intermediate commits, and will only appear at the end of each squash/fixup series. + @@ -560,31 +589,35 @@ without an explicit `--interactive`. See also INCOMPATIBLE OPTIONS below. --root:: - Rebase all commits reachable from <branch>, instead of - limiting them with an <upstream>. This allows you to rebase - the root commit(s) on a branch. When used with --onto, it - will skip changes already contained in <newbase> (instead of - <upstream>) whereas without --onto it will operate on every change. + Rebase all commits reachable from `<branch>`, instead of + limiting them with an `<upstream>`. This allows you to rebase + the root commit(s) on a branch. + 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. @@ -601,13 +634,27 @@ 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:: + Automatically force-update any branches that point to commits that + are being rebased. Any branches that are checked out in a worktree + are not updated in this way. ++ +If the configuration variable `rebase.updateRefs` is set, then this option +can be used to override and disable this setting. ++ +See also INCOMPATIBLE OPTIONS below. INCOMPATIBLE OPTIONS -------------------- @@ -623,16 +670,15 @@ are incompatible with the following options: * --merge * --strategy * --strategy-option - * --allow-empty-message - * --[no-]autosquash + * --autosquash * --rebase-merges * --interactive * --exec * --no-keep-empty * --empty= - * --reapply-cherry-picks - * --edit-todo - * --root when used in combination with --onto + * --[no-]reapply-cherry-picks when used without --keep-base + * --update-refs + * --root when used without --onto In addition, the following pairs of options are incompatible: @@ -643,9 +689,9 @@ In addition, the following pairs of options are incompatible: BEHAVIORAL DIFFERENCES ----------------------- -git rebase has two primary backends: apply and merge. (The apply +`git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' backend used to be known as the 'am' backend, but the name led to -confusion as it looks like a verb instead of a noun. Also, the merge +confusion as it looks like a verb instead of a noun. Also, the 'merge' backend used to be known as the interactive backend, but it is now used for non-interactive cases as well. Both were renamed based on lower-level functionality that underpinned each.) There are some @@ -654,19 +700,19 @@ subtle differences in how these two backends behave: Empty commits ~~~~~~~~~~~~~ -The apply backend unfortunately drops intentionally empty commits, i.e. +The 'apply' backend unfortunately drops intentionally empty commits, i.e. commits that started empty, though these are rare in practice. It also drops commits that become empty and has no option for controlling this behavior. -The merge backend keeps intentionally empty commits by default (though -with -i they are marked as empty in the todo list editor, or they can -be dropped automatically with --no-keep-empty). +The 'merge' backend keeps intentionally empty commits by default (though +with `-i` they are marked as empty in the todo list editor, or they can +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 +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 @@ -674,20 +720,20 @@ Directory rename detection Due to the lack of accurate tree information (arising from constructing fake ancestors with the limited information available in -patches), directory rename detection is disabled in the apply backend. +patches), directory rename detection is disabled in the 'apply' backend. Disabled directory rename detection means that if one side of history renames a directory and the other adds new files to the old directory, then the new files will be left behind in the old directory without any warning at the time of rebasing that you may want to move these files into the new directory. -Directory rename detection works with the merge backend to provide you +Directory rename detection works with the 'merge' backend to provide you warnings in such cases. Context ~~~~~~~ -The apply backend works by creating a sequence of patches (by calling +The 'apply' backend works by creating a sequence of patches (by calling `format-patch` internally), and then applying the patches in sequence (calling `am` internally). Patches are composed of multiple hunks, each with line numbers, a context region, and the actual changes. The @@ -698,11 +744,11 @@ order to apply the changes to the right lines. However, if multiple areas of the code have the same surrounding lines of context, the wrong one can be picked. There are real-world cases where this has caused commits to be reapplied incorrectly with no conflicts reported. -Setting diff.context to a larger value may prevent such types of +Setting `diff.context` to a larger value may prevent such types of problems, but increases the chance of spurious conflicts (since it will require more lines of matching context to apply). -The merge backend works with a full copy of each relevant file, +The 'merge' backend works with a full copy of each relevant file, insulating it from these types of problems. Labelling of conflicts markers @@ -710,30 +756,30 @@ Labelling of conflicts markers When there are content conflicts, the merge machinery tries to annotate each side's conflict markers with the commits where the -content came from. Since the apply backend drops the original +content came from. Since the 'apply' backend drops the original information about the rebased commits and their parents (and instead generates new fake commits based off limited information in the generated patches), those commits cannot be identified; instead it has -to fall back to a commit summary. Also, when merge.conflictStyle is -set to diff3 or zdiff3, the apply backend will use "constructed merge +to fall back to a commit summary. Also, when `merge.conflictStyle` is +set to `diff3` or `zdiff3`, the 'apply' backend will use "constructed merge base" to label the content from the merge base, and thus provide no information about the merge base commit whatsoever. -The merge backend works with the full commits on both sides of history +The 'merge' backend works with the full commits on both sides of history and thus has no such limitations. Hooks ~~~~~ -The apply backend has not traditionally called the post-commit hook, -while the merge backend has. Both have called the post-checkout hook, -though the merge backend has squelched its output. Further, both +The 'apply' backend has not traditionally called the post-commit hook, +while the 'merge' backend has. Both have called the post-checkout hook, +though the 'merge' backend has squelched its output. Further, both backends only call the post-checkout hook with the starting point commit of the rebase, not the intermediate commits nor the final commit. In each case, the calling of these hooks was by accident of implementation rather than by design (both backends were originally implemented as shell scripts and happened to invoke other commands -like 'git checkout' or 'git commit' that would call the hooks). Both +like `git checkout` or `git commit` that would call the hooks). Both backends should have the same behavior, though it is not entirely clear which, if any, is correct. We will likely make rebase stop calling either of these hooks in the future. @@ -741,10 +787,10 @@ calling either of these hooks in the future. Interruptability ~~~~~~~~~~~~~~~~ -The apply backend has safety problems with an ill-timed interrupt; if +The 'apply' backend has safety problems with an ill-timed interrupt; if the user presses Ctrl-C at the wrong time to try to abort the rebase, the rebase can enter a state where it cannot be aborted with a -subsequent `git rebase --abort`. The merge backend does not appear to +subsequent `git rebase --abort`. The 'merge' backend does not appear to suffer from the same shortcoming. (See https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for details.) @@ -756,8 +802,8 @@ When a conflict occurs while rebasing, rebase stops and asks the user to resolve. Since the user may need to make notable changes while resolving conflicts, after conflicts are resolved and the user has run `git rebase --continue`, the rebase should open an editor and ask the -user to update the commit message. The merge backend does this, while -the apply backend blindly applies the original commit message. +user to update the commit message. The 'merge' backend does this, while +the 'apply' backend blindly applies the original commit message. Miscellaneous differences ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -777,23 +823,23 @@ completeness: them to stderr. * State directories: The two backends keep their state in different - directories under .git/ + directories under `.git/` include::merge-strategies.txt[] NOTES ----- -You should understand the implications of using 'git rebase' on a +You should understand the implications of using `git rebase` on a repository that you share. See also RECOVERING FROM UPSTREAM REBASE below. -When the git-rebase command is run, it will first execute a "pre-rebase" -hook if one exists. You can use this hook to do sanity checks and -reject the rebase if it isn't appropriate. Please see the template -pre-rebase hook script for an example. +When the rebase is run, it will first execute a `pre-rebase` hook if one +exists. You can use this hook to do sanity checks and reject the rebase +if it isn't appropriate. Please see the template `pre-rebase` hook script +for an example. -Upon completion, <branch> will be the current branch. +Upon completion, `<branch>` will be the current branch. INTERACTIVE MODE ---------------- @@ -848,7 +894,7 @@ not look at them but at the commit names ("deadbee" and "fa1afe1" in this example), so do not delete or edit the names. By replacing the command "pick" with the command "edit", you can tell -'git rebase' to stop after applying that commit, so that you can edit +`git rebase` to stop after applying that commit, so that you can edit the files and/or the commit message, amend the commit, and continue rebasing. @@ -876,14 +922,13 @@ commit, the message from the final one is used. You can also use "fixup -C" to get the same behavior as "fixup -c" except without opening an editor. - -'git rebase' will stop when "pick" has been replaced with "edit" or +`git rebase` will stop when "pick" has been replaced with "edit" or when a command fails due to merge errors. When you are done editing and/or resolving conflicts you can continue with `git rebase --continue`. For example, if you want to reorder the last 5 commits, such that what -was HEAD~4 becomes the new HEAD. To achieve that, you would call -'git rebase' like this: +was `HEAD~4` becomes the new `HEAD`. To achieve that, you would call +`git rebase` like this: ---------------------- $ git rebase -i HEAD~5 @@ -903,7 +948,7 @@ like this: ------------------ Suppose you want to rebase the side branch starting at "A" to "Q". Make -sure that the current HEAD is "B", and call +sure that the current `HEAD` is "B", and call ----------------------------- $ git rebase -i -r --onto Q O @@ -929,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" @@ -956,23 +1000,23 @@ SPLITTING COMMITS ----------------- In interactive mode, you can mark commits with the action "edit". However, -this does not necessarily mean that 'git rebase' expects the result of this +this does not necessarily mean that `git rebase` expects the result of this edit to be exactly one commit. Indeed, you can undo the commit, or you can add other commits. This can be used to split a commit into two: - Start an interactive rebase with `git rebase -i <commit>^`, where - <commit> is the commit you want to split. In fact, any commit range + `<commit>` is the commit you want to split. In fact, any commit range will do, as long as it contains that commit. - Mark the commit you want to split with the action "edit". - When it comes to editing that commit, execute `git reset HEAD^`. The - effect is that the HEAD is rewound by one, and the index follows suit. + effect is that the `HEAD` is rewound by one, and the index follows suit. However, the working tree stays the same. - Now add the changes to the index that you want to have in the first commit. You can use `git add` (possibly interactively) or - 'git gui' (or both) to do that. + `git gui` (or both) to do that. - Commit the now-current index with whatever commit message is appropriate now. @@ -983,7 +1027,7 @@ add other commits. This can be used to split a commit into two: If you are not absolutely sure that the intermediate revisions are consistent (they compile, pass the testsuite, etc.) you should use -'git stash' to stash away the not-yet-committed changes +`git stash` to stash away the not-yet-committed changes after each commit, test, and amend the commit if fixes are necessary. @@ -1087,12 +1131,12 @@ NOTE: While an "easy case recovery" sometimes appears to be successful example, a commit that was removed via `git rebase --interactive` will be **resurrected**! -The idea is to manually tell 'git rebase' "where the old 'subsystem' +The idea is to manually tell `git rebase` "where the old 'subsystem' ended and your 'topic' began", that is, what the old merge base between them was. You will have to find a way to name the last commit of the old 'subsystem', for example: -* With the 'subsystem' reflog: after 'git fetch', the old tip of +* With the 'subsystem' reflog: after `git fetch`, the old tip of 'subsystem' is at `subsystem@{1}`. Subsequent fetches will increase the number. (See linkgit:git-reflog[1].) @@ -1250,6 +1294,8 @@ merge cmake CONFIGURATION ------------- +include::includes/cmd-config-section-all.txt[] + include::config/rebase.txt[] include::config/sequencer.txt[] diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 014a784..20aca92 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- [verse] -'git-receive-pack' <directory> +'git receive-pack' <git-dir> DESCRIPTION ----------- @@ -18,10 +18,10 @@ information fed from the remote end. This command is usually not invoked directly by the end user. The UI for the protocol is on the 'git send-pack' side, and the -program pair is meant to be used to push updates to remote +program pair is meant to be used to push updates to a remote repository. For pull operations, see linkgit:git-fetch-pack[1]. -The command allows for creation and fast-forwarding of sha1 refs +The command allows for the creation and fast-forwarding of sha1 refs (heads/tags) on the remote end (strictly speaking, it is the local end 'git-receive-pack' runs, but to the user who is sitting at the send-pack end, it is updating the remote. Confused?) @@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1]. OPTIONS ------- -<directory>:: +<git-dir>:: The repository to sync into. --http-backend-info-refs:: diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 5ced7ad..a929c52 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -9,22 +9,19 @@ git-reflog - Manage reflog information SYNOPSIS -------- [verse] -'git reflog' <subcommand> <options> - -DESCRIPTION ------------ -The command takes various subcommands, and different options -depending on the subcommand: - -[verse] -'git reflog' ['show'] [<log-options>] [<ref>] +'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>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... + [--dry-run | -n] [--verbose] <ref>@{<specifier>}... 'git reflog exists' <ref> +DESCRIPTION +----------- +This command manages the information recorded in the reflogs. + Reference logs, or "reflogs", record when the tips of branches and other references were updated in the local repository. Reflogs are useful in various Git commands, to specify the old value of a @@ -33,7 +30,8 @@ moves ago", `master@{one.week.ago}` means "where master used to point to one week ago in this local repository", and so on. See linkgit:gitrevisions[7] for more details. -This command manages the information recorded in the reflogs. +The command takes various subcommands, and different options +depending on the subcommand: The "show" subcommand (which is also the default, in the absence of any subcommands) shows the log of the reference provided in the @@ -42,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-ext.txt b/Documentation/git-remote-ext.txt index 88ea7e1..b33ee3c 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -44,15 +44,15 @@ The following sequences have a special meaning: This argument will not be passed to '<command>'. Instead, it will cause the helper to start by sending git:// service requests to the remote side with the service field set to an appropriate value and - the repository field set to rest of the argument. Default is not to send + the repository field set to the rest of the argument. Default is not to send such a request. + -This is useful if remote side is git:// server accessed over +This is useful if the remote side is git:// server accessed over some tunnel. '%V' (must be first characters in argument):: This argument will not be passed to '<command>'. Instead it sets - the vhost field in the git:// service request (to rest of the argument). + the vhost field in the git:// service request (to the rest of the argument). Default is not to send vhost in such request (if sent). ENVIRONMENT VARIABLES @@ -82,12 +82,12 @@ begins with `ext::`. Examples: "ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'":: Like host.example:foo/repo, but use /home/foo/.ssh/somekey as - keypair and user as user on remote side. This avoids needing to + keypair and user as the user on the remote side. This avoids the need to edit .ssh/config. "ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo":: Represents repository with path /somerepo accessible over - git protocol at abstract namespace address /git-server. + git protocol at the abstract namespace address /git-server. "ext::git-server-alias foo %G/repo":: Represents a repository with path /repo accessed using the diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 0451ceb..1dd2648 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -13,19 +13,19 @@ DESCRIPTION ----------- This helper uses specified file descriptors to connect to a remote Git server. This is not meant for end users but for programs and scripts calling git -fetch, push or archive. +fetch, push, or archive. If only <infd> is given, it is assumed to be a bidirectional socket connected -to remote Git server (git-upload-pack, git-receive-pack or +to a remote Git server (git-upload-pack, git-receive-pack, or git-upload-archive). If both <infd> and <outfd> are given, they are assumed to be pipes connected to a remote Git server (<infd> being the inbound pipe -and <outfd> being the outbound pipe. +and <outfd> being the outbound pipe). It is assumed that any handshaking procedures have already been completed (such as sending service request for git://) before this helper is started. <anything> can be any string. It is ignored. It is meant for providing -information to user in the URL in case that URL is displayed in some +information to the user in the URL in case that URL is displayed in some context. ENVIRONMENT VARIABLES @@ -45,7 +45,7 @@ EXAMPLES `git push fd::7,8 master (as URL)`:: Push master, using file descriptor #7 to read data from git-receive-pack and file descriptor #8 to write data to - same service. + the same service. `git push fd::7,8/bar master`:: Same as above. 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-repack.txt b/Documentation/git-repack.txt index 0bf1389..c902512 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -74,6 +74,23 @@ to the new separate pack will be written. immediately instead of waiting for the next `git gc` invocation. Only useful with `--cruft -d`. +--max-cruft-size=<n>:: + Repack cruft objects into packs as large as `<n>` bytes before + creating new packs. As long as there are enough cruft packs + smaller than `<n>`, repacking will cause a new cruft pack to + be created containing objects from any combined cruft packs, + along with any new unreachable objects. Cruft packs larger than + `<n>` will not be modified. When the new cruft pack is larger + than `<n>` bytes, it will be split into multiple packs, all of + which are guaranteed to be at most `<n>` bytes in size. Only + useful with `--cruft -d`. + +--expire-to=<dir>:: + Write a cruft pack containing pruned objects (if any) to the + directory `<dir>`. This option is useful for keeping a copy of + any pruned objects in a separate directory as a backup. Only + useful with `--cruft -d`. + -l:: Pass the `--local` option to 'git pack-objects'. See linkgit:git-pack-objects[1]. @@ -137,6 +154,29 @@ depth is 4095. a larger and slower repository; see the discussion in `pack.packSizeLimit`. +--filter=<filter-spec>:: + Remove objects matching the filter specification from the + resulting packfile and put them into a separate packfile. Note + that objects used in the working directory are not filtered + out. So for the split to fully work, it's best to perform it + in a bare repo and to use the `-a` and `-d` options along with + this option. Also `--no-write-bitmap-index` (or the + `repack.writebitmaps` config option set to `false`) should be + used otherwise writing bitmap index will fail, as it supposes + a single packfile containing all the objects. See + linkgit:git-rev-list[1] for valid `<filter-spec>` forms. + +--filter-to=<dir>:: + Write the pack containing filtered out objects to the + directory `<dir>`. Only useful with `--filter`. This can be + used for putting the pack on a separate object directory that + is accessed through the Git alternates mechanism. **WARNING:** + If the packfile containing the filtered out objects is not + accessible, the repo can become corrupt as it might not be + possible to access the objects in that packfile. See the + `objects` and `objects/info/alternates` sections of + linkgit:gitrepository-layout[5]. + -b:: --write-bitmap-index:: Write a reachability bitmap index as part of the repack. This @@ -159,7 +199,7 @@ depth is 4095. Exclude the given pack from repacking. This is the equivalent of having `.keep` file on the pack. `<pack-name>` is the pack file name without leading directory (e.g. `pack-123.pack`). - The option could be specified multiple times to keep multiple + The option can be specified multiple times to keep multiple packs. --unpack-unreachable=<when>:: @@ -180,7 +220,7 @@ depth is 4095. Pass the `--delta-islands` option to `git-pack-objects`, see linkgit:git-pack-objects[1]. --g=<factor>:: +-g<factor>:: --geometric=<factor>:: Arrange resulting pack structure so that each successive pack contains at least `<factor>` times the number of objects as the @@ -197,11 +237,8 @@ uniquely by the set of packs being "rolled-up"; in other words, the packs determined to need to be combined in order to restore a geometric progression. + -When `--unpacked` is specified, loose objects are implicitly included in -this "roll-up", without respect to their reachability. This is subject -to change in the future. This option (implying a drastically different -repack mode) is not guaranteed to work with all other combinations of -option to `git repack`. +Loose objects are implicitly included in this "roll-up", without respect to +their reachability. This is subject to change in the future. + When writing a multi-pack bitmap, `git repack` selects the largest resulting pack as the preferred pack for object selection by the MIDX (see diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index f271d75..0a65460 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -35,7 +35,7 @@ Replacement references will be used by default by all Git commands except those doing reachability traversal (prune, pack transfer and fsck). -It is possible to disable use of replacement references for any +It is possible to disable the use of replacement references for any command using the `--no-replace-objects` option just after 'git'. For example if commit 'foo' has been replaced by commit 'bar': @@ -111,14 +111,14 @@ OPTIONS FORMATS ------- -The following format are available: +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..f6c269c --- /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 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-request-pull.txt b/Documentation/git-request-pull.txt index fa5a426..15dcbb6 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -16,7 +16,7 @@ DESCRIPTION Generate a request asking your upstream project to pull changes into their tree. The request, printed to the standard output, begins with the branch description, summarizes -the changes and indicates from where they can be pulled. +the changes, and indicates from where they can be pulled. The upstream project is expected to have the commit named by `<start>` and the output asks it to integrate the changes you made @@ -50,7 +50,7 @@ EXAMPLES -------- Imagine that you built your work on your `master` branch on top of -the `v1.0` release, and want it to be integrated to the project. +the `v1.0` release, and want it to be integrated into the project. First you push that change to your public repository for others to see: diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 4cfc883..992b469 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- [verse] -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc'] +'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc] DESCRIPTION ----------- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 01cb4c9..79ad564 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 'git reset' [<mode>] [<commit>]:: This form resets the current branch head to `<commit>` and possibly updates the index (resetting it to the tree of `<commit>`) and - the working tree depending on `<mode>`. If `<mode>` is omitted, + the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If `<mode>` is omitted, defaults to `--mixed`. The `<mode>` must be one of the following: + -- diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5964810..975825b 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -78,6 +78,8 @@ all modified paths. --theirs:: When restoring files in the working tree from the index, use stage #2 ('ours') or #3 ('theirs') for unmerged paths. + This option cannot be used when checking out paths from a + tree-ish (i.e. with the `--source` option). + Note that during `git rebase` and `git pull --rebase`, 'ours' and 'theirs' may appear swapped. See the explanation of the same options @@ -87,6 +89,8 @@ in linkgit:git-checkout[1] for details. --merge:: When restoring files on the working tree from the index, recreate the conflicted merge in the unmerged paths. + This option cannot be used when checking out paths from a + tree-ish (i.e. with the `--source` option). --conflict=<style>:: The same as `--merge` option above, but changes the way the @@ -101,7 +105,7 @@ in linkgit:git-checkout[1] for details. specified. Unmerged paths on the working tree are left alone. --ignore-skip-worktree-bits:: - In sparse checkout mode, by default is to only update entries + In sparse checkout mode, the default is to only update entries matched by `<pathspec>` and sparse patterns in $GIT_DIR/info/sparse-checkout. This option ignores the sparse patterns and unconditionally restores any files in @@ -195,7 +199,7 @@ the same as using linkgit:git-reset[1]) $ git restore --staged hello.c ------------ -or you can restore both the index and the working tree (this the same +or you can restore both the index and the working tree (this is the same as using linkgit:git-checkout[1]) ------------ diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 20bb8e8..2e05c4b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order SYNOPSIS -------- [verse] -'git rev-list' [<options>] <commit>... [[--] <path>...] +'git rev-list' [<options>] <commit>... [--] [<path>...] DESCRIPTION ----------- @@ -17,9 +17,9 @@ DESCRIPTION :git-rev-list: 1 include::rev-list-description.txt[] -'rev-list' is a very essential Git command, since it +'rev-list' is an essential Git command, since it provides the ability to build and traverse commit ancestry graphs. For -this reason, it has a lot of different options that enables it to be +this reason, it has a lot of different options that enable it to be used by commands as different as 'git bisect' and 'git repack'. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 6b8ca08..f9d5a35 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -9,12 +9,12 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- [verse] -'git rev-parse' [<options>] <args>... +'git rev-parse' [<options>] <arg>... DESCRIPTION ----------- -Many Git porcelainish commands take mixture of flags +Many Git porcelainish commands take a mixture of flags (i.e. parameters that begin with a dash '-') and parameters meant for the underlying 'git rev-list' command they use internally and flags and parameters for the other commands they use @@ -36,7 +36,7 @@ Each of these options must appear first on the command line. --sq-quote:: Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE section below). In contrast to the `--sq` option below, this - mode does only quoting. Nothing else is done to command input. + mode only does quoting. Nothing else is done to command input. Options for --parseopt ~~~~~~~~~~~~~~~~~~~~~~ @@ -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` @@ -156,18 +156,30 @@ for another option. are not refs (i.e. branch or tag names; or more explicitly disambiguating "heads/master" form, when you want to name the "master" branch when there is an - unfortunately named tag "master"), and show them as full + 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,6 +209,14 @@ 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):: + 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` + configuration along with `transfer.hideRefs` (see + linkgit:git-config[1]). This option affects the next pseudo-ref option + `--all` or `--glob` and is cleared after processing them. + --disambiguate=<prefix>:: Show every object whose name begins with the given prefix. The <prefix> must be at least 4 hexadecimal digits long to @@ -299,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. @@ -375,7 +398,7 @@ Each line of options has this format: dash to separate words in a multi-word argument hint. The remainder of the line, after stripping the spaces, is used -as the help associated to the option. +as the help associated with the option. Blank lines are ignored, and lines that don't match this specification are used as option group headers (start the line with a space to create such @@ -390,7 +413,7 @@ some-command [<options>] <args>... some-command does foo and bar! -- -h,help show the help +h,help! show the help foo some nifty option --foo bar= some cool option --bar with an argument @@ -416,10 +439,10 @@ usage: some-command [<options>] <args>... some-command does foo and bar! -h, --help show the help - --foo some nifty option --foo - --bar ... some cool option --bar with an argument - --baz <arg> another cool option --baz with a named argument - --qux[=<path>] qux may take a path argument but has meaning by itself + --[no-]foo some nifty option --foo + --[no-]bar ... some cool option --bar with an argument + --[no-]baz <arg> another cool option --baz with a named argument + --[no-]qux[=<path>] qux may take a path argument but has meaning by itself An option group Header -C[...] option C with an optional argument diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 8463fe9..568925d 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -8,7 +8,7 @@ git-revert - Revert some existing commits SYNOPSIS -------- [verse] -'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>... +'git revert' [--[no-]edit] [-n] [-m <parent-number>] [-s] [-S[<keyid>]] <commit>... 'git revert' (--continue | --skip | --abort | --quit) DESCRIPTION @@ -112,14 +112,11 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +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 @@ -145,6 +142,23 @@ EXAMPLES changes. The revert only modifies the working tree and the index. +DISCUSSION +---------- + +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>""'. +Please consider rewording these to be shorter and more unique. + +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/revert.txt[] + SEE ALSO -------- linkgit:git-cherry-pick[1] diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 81bc23f..363a269 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -163,7 +163,7 @@ will be staged (unless --cached or -n are used). A submodule is considered up to date when the HEAD is the same as recorded in the index, no tracked files are modified and no untracked -files that aren't ignored are present in the submodules work tree. +files that aren't ignored are present in the submodule's work tree. Ignored files are deemed expendable and won't stop a submodule's work tree from being removed. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 41cd8cb..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 @@ -68,11 +68,12 @@ This option may be specified multiple times. Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) to edit an introductory message for the patch series. + -When `--compose` is used, git send-email will use the From, Subject, and -In-Reply-To headers specified in the message. If the body of the message -(what you type after the headers and a blank line) only contains blank -(or Git: prefixed) lines, the summary won't be sent, but From, Subject, -and In-Reply-To headers will be used unless they are removed. +When `--compose` is used, git send-email will use the From, To, Cc, Bcc, +Subject, Reply-To, and In-Reply-To headers specified in the message. If +the body of the message (what you type after the headers and a blank +line) only contains blank (or Git: prefixed) lines, the summary won't be +sent, but the headers mentioned above will be used unless they are +removed. + Missing From or In-Reply-To headers will be prompted for. + @@ -93,7 +94,7 @@ See the CONFIGURATION section for `sendemail.multiEdit`. --in-reply-to=<identifier>:: 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. The second and subsequent emails will be sent as replies according to the `--[no-]chain-reply-to` setting. @@ -137,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. @@ -173,14 +174,23 @@ 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. --smtp-encryption=<encryption>:: - Specify the encryption to use, either 'ssl' or 'tls'. Any other - value reverts to plain SMTP. Default is the value of - `sendemail.smtpEncryption`. + Specify in what way encrypting begins for the SMTP connection. + Valid values are 'ssl' and 'tls'. Any other value reverts to plain + (unencrypted) SMTP, which defaults to port 25. + Despite the names, both values will use the same newer version of TLS, + but for historic reasons have these names. 'ssl' refers to "implicit" + encryption (sometimes called SMTPS), that uses port 465 by default. + 'tls' refers to "explicit" encryption (often known as STARTTLS), + that uses port 25 by default. Other ports might be used by the SMTP + server, which are not the default. Commonly found alternative port for + 'tls' and unencrypted is 587. You need to check your provider's + documentation or your server configuration to make sure + for your own case. Default is the value of `sendemail.smtpEncryption`. --smtp-domain=<FQDN>:: Specifies the Fully Qualified Domain Name (FQDN) used in the @@ -259,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). @@ -268,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. @@ -291,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. @@ -303,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 @@ -311,6 +323,17 @@ Automating Output of this command must be single email address per line. Default is the value of `sendemail.ccCmd` configuration value. +--header-cmd=<command>:: + Specify a command that is executed once per outgoing message + and output RFC 2822 style header lines to be inserted into + them. When the `sendemail.headerCmd` configuration variable is + set, its value is always used. When --header-cmd is provided + at the command line, its value takes precedence over the + `sendemail.headerCmd` configuration variable. + +--no-header-cmd:: + Disable any header command in use. + --[no-]chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after @@ -327,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>:: @@ -363,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. @@ -433,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, @@ -448,49 +471,17 @@ Information --dump-aliases:: Instead of the normal operation, dump the shorthand alias names from - the configured alias file(s), one per line in alphabetical order. Note, - this only includes the alias name and not its expanded email addresses. - See 'sendemail.aliasesfile' for more information about aliases. + 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. CONFIGURATION ------------- -sendemail.aliasesFile:: - To avoid typing long email addresses, point this to one or more - email aliases files. You must also supply `sendemail.aliasFileType`. +include::includes/cmd-config-section-all.txt[] -sendemail.aliasFileType:: - Format of the file(s) specified in sendemail.aliasesFile. Must be - one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'. -+ -What an alias file in each format looks like can be found in -the documentation of the email program of the same name. The -differences and limitations from the standard formats are -described below: -+ --- -sendmail;; -* Quoted aliases and quoted addresses are not supported: lines that - contain a `"` symbol are ignored. -* Redirection to a file (`/path/name`) or pipe (`|command`) is not - supported. -* File inclusion (`:include: /path/name`) is not supported. -* Warnings are printed on the standard error output for any - explicitly unsupported constructs, and any other lines that are not - recognized by the parser. --- - -sendemail.multiEdit:: - If true (default), a single editor instance will be spawned to edit - files you have to edit (patches when `--annotate` is used, and the - summary when `--compose` is used). If false, files will be edited one - after the other, spawning a new editor each time. - -sendemail.confirm:: - Sets the default for whether to confirm before sending. Must be - one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` - in the previous section for the meaning of these values. +include::config/sendemail.txt[] EXAMPLES -------- @@ -507,14 +498,10 @@ edit ~/.gitconfig to specify your account settings: smtpServerPort = 587 ---- -If you have multi-factor authentication set up on your Gmail account, you will -need to generate an app-specific password for use with 'git send-email'. Visit +If you have multi-factor authentication set up on your Gmail account, you can +generate an app-specific password for use with 'git send-email'. Visit https://security.google.com/settings/security/apppasswords to create it. -If you do not have multi-factor authentication set up on your Gmail account, -you will need to allow less secure app access. Visit -https://myaccount.google.com/lesssecureapps to enable it. - Once your commits are ready to be sent to the mailing list, run the following commands: diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index be41f11..b9e73f2 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,9 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>] +'git send-pack' [--mirror] [--dry-run] [--force] + [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] - [--[no-]signed|--signed=(true|false|if-asked)] + [--[no-]signed | --signed=(true|false|if-asked)] [<host>:]<directory> (--all | <ref>...) DESCRIPTION @@ -54,7 +55,7 @@ be in a separate packet, and the list must end with a flush packet. --force:: Usually, the command refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it. - This flag disables the check. What this means is that + This flag disables the check. This means that the remote repository can lose commits; use it with care. @@ -105,7 +106,7 @@ SPECIFYING THE REFS There are three ways to specify which refs to update on the remote end. -With `--all` flag, all refs that exist locally are transferred to +With the `--all` flag, all refs that exist locally are transferred to the remote side. You cannot specify any '<ref>' if you use this flag. @@ -114,9 +115,9 @@ both on the local side and on the remote side are updated. When one or more '<ref>' are specified explicitly (whether on the command line or via `--stdin`), it can be either a -single pattern, or a pair of such pattern separated by a colon +single pattern, or a pair of such patterns separated by a colon ":" (this means that a ref name cannot have a colon in it). A -single pattern '<name>' is just a shorthand for '<name>:<name>'. +single pattern '<name>' is just shorthand for '<name>:<name>'. Each pattern pair consists of the source side (before the colon) and the destination side (after the colon). The ref to be @@ -129,7 +130,7 @@ name. See linkgit:git-rev-parse[1]. - It is an error if <src> does not match exactly one of the local refs. - - It is an error if <dst> matches more than one remote refs. + - It is an error if <dst> matches more than one remote ref. - If <dst> does not match any remote ref, either @@ -142,9 +143,9 @@ name. See linkgit:git-rev-parse[1]. Without `--force`, the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an -ancestor) of <src>. This check, known as "fast-forward check", -is performed in order to avoid accidentally overwriting the -remote ref and lose other peoples' commits from there. +ancestor) of <src>. This check, known as the "fast-forward check", +is performed to avoid accidentally overwriting the +remote ref and losing other people's commits from there. With `--force`, the fast-forward check is disabled for all refs. diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 8632612..bdaf6e5 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -22,7 +22,7 @@ The 'git sh-setup' scriptlet is designed to be sourced (using the normal Git directories and a few helper shell functions. Before sourcing it, your script should set up a few variables; -`USAGE` (and `LONG_USAGE`, if any) is used to define message +`USAGE` (and `LONG_USAGE`, if any) is used to define the message given by `usage()` shell function. `SUBDIRECTORY_OK` can be set if the script can run from a subdirectory of the working tree (some commands do not). diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index f64e770..7d0277d 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -47,6 +47,11 @@ OPTIONS Each pretty-printed commit will be rewrapped before it is shown. +--date=<format>:: + Show dates formatted according to the given date string. (See + the `--date` option in the "Commit Formatting" section of + linkgit:git-log[1]). Useful with `--group=format:<format>`. + --group=<type>:: Group commits based on `<type>`. If no `--group` option is specified, the default is `author`. `<type>` is one of: @@ -59,6 +64,9 @@ OPTIONS example, if your project uses `Reviewed-by` trailers, you might want to see who has been reviewing with `git shortlog -ns --group=trailer:reviewed-by`. + - `format:<format>`, any string accepted by the `--format` option of + 'git log'. (See the "PRETTY FORMATS" section of + linkgit:git-log[1].) + Note that commits that do not include the trailer will not be counted. Likewise, commits with multiple trailers (e.g., multiple signoffs) may diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 5cc2fce..c771c89 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] +'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...] -'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] +'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION ----------- @@ -50,7 +50,7 @@ OPTIONS --current:: With this option, the command includes the current - branch to the list of revs to be shown when it is not + branch in the list of revs to be shown when it is not given on the command line. --topo-order:: @@ -74,8 +74,7 @@ OPTIONS that is the common ancestor of all the branches. This flag tells the command to go <n> more common commits beyond that. When <n> is negative, display only the - <reference>s given, without showing the commit ancestry - tree. + <ref>s given, without showing the commit ancestry tree. --list:: Synonym to `--more=-1` @@ -88,8 +87,8 @@ OPTIONS the case of three or more commits. --independent:: - Among the <reference>s given, display only the ones that - cannot be reached from any other <reference>. + Among the <ref>s given, display only the ones that cannot be + reached from any other <ref>. --no-name:: Do not show naming strings for each commit. @@ -126,25 +125,26 @@ OPTIONS default to color output. Same as `--color=never`. -Note that --more, --list, --independent and --merge-base options +Note that --more, --list, --independent, and --merge-base options are mutually exclusive. OUTPUT ------ -Given N <references>, the first N lines are the one-line -description from their commit message. The branch head that is -pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*` -character while other heads are prefixed with a `!` character. -Following these N lines, one-line log for each commit is +Given N <ref>s, the first N lines are the one-line description from +their commit message. The branch head that is pointed at by +$GIT_DIR/HEAD is prefixed with an asterisk `*` character while other +heads are prefixed with a `!` character. + +Following these N lines, a one-line log for each commit is displayed, indented N places. If a commit is on the I-th branch, the I-th indentation character shows a `+` sign; otherwise it shows a space. Merge commits are denoted by a `-` sign. Each commit shows a short name that can be used as an extended SHA-1 to name that commit. -The following example shows three branches, "master", "fixes" +The following example shows three branches, "master", "fixes", and "mhf": ------------------------------------------------ @@ -154,7 +154,7 @@ $ git show-branch master fixes mhf ! [mhf] Allow "+remote:local" refspec to cause --force when fetching. --- + [mhf] Allow "+remote:local" refspec to cause --force when fetching. - + [mhf~1] Use git-octopus when pulling more than one heads. + + [mhf~1] Use git-octopus when pulling more than one head. + [fixes] Introduce "reset type" flag to "git reset" + [mhf~2] "git fetch --force". + [mhf~3] Use .git/remote/origin, not .git/branches/origin. @@ -197,7 +197,14 @@ $ git show-branch --reflog="10,1 hour ago" --list master shows 10 reflog entries going back from the tip as of 1 hour ago. Without `--list`, the output also shows how these tips are -topologically related with each other. +topologically related to each other. + +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/showbranch.txt[] GIT --- diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index ab4d271..ba75747 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -8,10 +8,14 @@ git-show-ref - List references in a local repository SYNOPSIS -------- [verse] -'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] - [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] +'git show-ref' [--head] [-d | --dereference] + [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...] +'git show-ref' --verify [-q | --quiet] [-d | --dereference] + [-s | --hash[=<n>]] [--abbrev[=<n>]] + [--] [<ref>...] 'git show-ref' --exclude-existing[=<pattern>] +'git show-ref' --exists <ref> DESCRIPTION ----------- @@ -23,10 +27,14 @@ particular ref exists. By default, shows the tags, heads, and remote refs. -The --exclude-existing form is a filter that does the inverse. It reads +The `--exclude-existing` form is a filter that does the inverse. It reads refs from stdin, one ref per line, and shows those that don't exist in the local repository. +The `--exists` form can be used to check for the existence of a single +references. This form does not verify whether the reference resolves to an +actual object. + Use of this utility is encouraged in favor of directly accessing files under the `.git` directory. @@ -47,14 +55,14 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "{caret}{}" + Dereference tags into object IDs as well. They will be shown with `^{}` appended. -s:: --hash[=<n>]:: - Only show the SHA-1 hash, not the reference name. When combined with - --dereference the dereferenced tag will still be shown after the SHA-1. + Only show the OID, not the reference name. When combined with + `--dereference`, the dereferenced tag will still be shown after the OID. --verify:: @@ -62,6 +70,12 @@ OPTIONS Aside from returning an error code of 1, it will also print an error message if `--quiet` was not specified. +--exists:: + + Check whether the given reference exists. Returns an exit code of 0 if + it does, 2 if it is missing, and 1 in case looking up the reference + failed with an error other than the reference being missing. + --abbrev[=<n>]:: Abbreviate the object name. When using `--hash`, you do @@ -70,15 +84,15 @@ OPTIONS -q:: --quiet:: - Do not print any results to stdout. When combined with `--verify` this - can be used to silently check if a reference exists. + Do not print any results to stdout. Can be used with `--verify` to + silently check if a reference exists. --exclude-existing[=<pattern>]:: - Make 'git show-ref' act as a filter that reads refs from stdin of the - form "`^(?:<anything>\s)?<refname>(?:\^{})?$`" + Make `git show-ref` act as a filter that reads refs from stdin of the + form `^(?:<anything>\s)?<refname>(?:\^{})?$` and performs the following actions on each: - (1) strip "{caret}{}" at the end of line if any; + (1) strip `^{}` at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; @@ -96,7 +110,13 @@ OPTIONS OUTPUT ------ -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. +The output is in the format: + +------------ +<oid> SP <ref> LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --head --dereference @@ -110,7 +130,13 @@ $ git show-ref --head --dereference ... ----------------------------------------------------------------------------- -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>' +When using `--hash` (and not `--dereference`), the output is in the format: + +------------ +<oid> LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --heads --hash @@ -132,7 +158,7 @@ use: ----------------------------------------------------------------------------- This will show "refs/heads/master" but also "refs/remote/other-repo/master", -if such references exists. +if such references exist. When using the `--verify` flag, the command requires an exact path: @@ -142,10 +168,10 @@ When using the `--verify` flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, 'git show-ref' will return an error code of 1, +If nothing matches, `git show-ref` will return an error code of 1, and in the case of verification, it will show an error message. -For scripting, you can ask it to be quiet with the "--quiet" flag, which +For scripting, you can ask it to be quiet with the `--quiet` flag, which allows you to do things like ----------------------------------------------------------------------------- @@ -157,11 +183,11 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use "--tags" and/or "--heads" +To show only tags, or only proper branch heads, use `--tags` and/or `--heads` respectively (using both means that it shows tags and heads, but not other random references under the refs/ subdirectory). -To do automatic tag object dereferencing, use the "-d" or "--dereference" +To do automatic tag object dereferencing, use the `-d` or `--dereference` flag, so you can do ----------------------------------------------------------------------------- diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 2b1bc72..5eb6743 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -26,7 +26,7 @@ with --name-only). For plain blobs, it shows the plain contents. -The command takes options applicable to the 'git diff-tree' command to +Some options that 'git log' command understands can be used to control how the changes the commit introduces are shown. This manual page describes only the most frequently used options. @@ -61,7 +61,7 @@ EXAMPLES -------- `git show v1.0.0`:: - Shows the tag `v1.0.0`, along with the object the tags + Shows the tag `v1.0.0`, along with the object the tag points at. `git show v1.0.0^{tree}`:: diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 3776705..529a8ed 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files SYNOPSIS -------- [verse] -'git sparse-checkout <subcommand> [<options>]' +'git sparse-checkout' (init | list | set | add | reapply | disable | check-rules) [<options>] DESCRIPTION @@ -135,6 +135,29 @@ paths to pass to a subsequent 'set' or 'add' command. However, the disable command, so the easy restore of calling a plain `init` decreased in utility. +'check-rules':: + Check whether sparsity rules match one or more paths. ++ +By default `check-rules` reads a list of paths from stdin and outputs only +the ones that match the current sparsity rules. The input is expected to consist +of one path per line, matching the output of `git ls-tree --name-only` including +that pathnames that begin with a double quote (") are interpreted as C-style +quoted strings. ++ +When called with the `--rules-file <file>` flag the input files are matched +against the sparse checkout rules found in `<file>` instead of the current ones. +The rules in the files are expected to be in the same form as accepted by `git +sparse-checkout set --stdin` (in particular, they must be newline-delimited). ++ +By default, the rules passed to the `--rules-file` option are interpreted as +cone mode directories. To pass non-cone mode patterns with `--rules-file`, +combine the option with the `--no-cone` option. ++ +When called with the `-z` flag, the format of the paths input on stdin as well +as the output paths are \0 terminated and not quoted. Note that this does not +apply to the format of the rules passed with the `--rules-file` option. + + EXAMPLES -------- `git sparse-checkout set MY/DIR1 SUB/DIR2`:: @@ -263,7 +286,7 @@ patterns in non-cone mode has a number of shortcomings: problem above? Also, if it suggests paths, what if the user has a file or directory that begins with either a '!' or '#' or has a '*', '\', '?', '[', or ']' in its name? And if it suggests paths, will - it complete "/pro" to "/proc" (in the root filesytem) rather than to + it complete "/pro" to "/proc" (in the root filesystem) rather than to "/progress.txt" in the current directory? (Note that users are likely to want to start paths with a leading '/' in non-cone mode, for the same reason that .gitignore files often have one.) diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 6e15f47..06fb7f1 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,17 +9,20 @@ SYNOPSIS -------- [verse] 'git stash' list [<log-options>] -'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>] -'git stash' drop [-q|--quiet] [<stash>] -'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] +'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>] +'git stash' drop [-q | --quiet] [<stash>] +'git stash' pop [--index] [-q | --quiet] [<stash>] +'git stash' apply [--index] [-q | --quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet] - [-u|--include-untracked] [-a|--all] [-m|--message <message>] +'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet] + [-u | --include-untracked] [-a | --all] [(-m | --message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]] +'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet] + [-u | --include-untracked] [-a | --all] [<message>] 'git stash' clear 'git stash' create [<message>] -'git stash' store [-m|--message <message>] [-q|--quiet] <commit> +'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit> DESCRIPTION ----------- @@ -47,7 +50,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`). COMMANDS -------- -push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: +push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: Save your local modifications to a new 'stash entry' and roll them back to HEAD (in the working tree and in the index). @@ -363,7 +366,7 @@ only the commit ends-up being in the stash and not on the current branch. # ... hack hack hack ... $ git add --patch foo # add unrelated changes to the index $ git stash push --staged # save these changes to the stash -# ... hack hack hack, finish curent changes ... +# ... hack hack hack, finish current changes ... $ git commit -m 'Massive' # commit fully tested changes $ git switch fixup-branch # switch to another branch $ git stash pop # to finish work on the saved changes @@ -382,6 +385,13 @@ grep commit | cut -d\ -f3 | xargs git log --merges --no-walk --grep=WIP ---------------------------------------------------------------- +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/stash.txt[] + SEE ALSO -------- diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 54a4b29..9a37688 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -9,7 +9,7 @@ git-status - Show the working tree status SYNOPSIS -------- [verse] -'git status' [<options>...] [--] [<pathspec>...] +'git status' [<options>] [--] [<pathspec>...] DESCRIPTION ----------- @@ -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]. @@ -245,11 +247,12 @@ U U unmerged, both modified .... Submodules have more state and instead report - M the submodule has a different HEAD than - recorded in the index - m the submodule has modified content - ? the submodule has untracked files -since modified content or untracked files in a submodule cannot be added + +* 'M' = the submodule has a different HEAD than recorded in the index +* 'm' = the submodule has modified content +* '?' = the submodule has untracked files + +This is since modified content or untracked files in a submodule cannot be added via `git add` in the superproject to prepare a commit. 'm' and '?' are applied recursively. For example if a nested submodule @@ -308,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. ------------------------------------------------------------ @@ -457,6 +460,66 @@ during the write may conflict with other simultaneous processes, causing them to fail. Scripts running `status` in the background should consider using `git --no-optional-locks status` (see linkgit:git[1] for details). +UNTRACKED FILES AND PERFORMANCE +------------------------------- + +`git status` can be very slow in large worktrees if/when it +needs to search for untracked files and directories. There are +many configuration options available to speed this up by either +avoiding the work or making use of cached results from previous +Git commands. There is no single optimum set of settings right +for everyone. We'll list a summary of the relevant options to help +you, but before going into the list, you may want to run `git status` +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=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 + you create any new files and manually `git add` them. + +* `advice.statusUoption=false` (see linkgit:git-config[1]): + setting this variable to `false` disables the warning message + given when enumerating untracked files takes more than 2 + seconds. In a large project, it may take longer and the user + may have already accepted the trade off (e.g. using "-uno" may + not be an acceptable option for the user), in which case, there + is no point issuing the warning message, and in such a case, + disabling the warning may be the best. + +* `core.untrackedCache=true` (see linkgit:git-update-index[1]): + enable the untracked cache feature and only search directories + that have been modified since the previous `git status` command. + Git remembers the set of untracked files within each directory + and assumes that if a directory has not been modified, then + the set of untracked files within has not changed. This is much + faster than enumerating the contents of every directory, but still + not without cost, because Git still has to search for the set of + modified directories. The untracked cache is stored in the + `.git/index` file. The reduced cost of searching for untracked + files is offset slightly by the increased size of the index and + the cost of keeping it up-to-date. That reduced search time is + usually worth the additional size. + +* `core.untrackedCache=true` and `core.fsmonitor=true` or + `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 + is faster than using just the untracked cache alone because + Git can also avoid searching for modified directories. Git + only has to enumerate the exact set of directories that have + changed recently. While the FSMonitor feature can be enabled + without the untracked cache, the benefits are greatly reduced + in that case. + +Note that after you turn on the untracked cache and/or FSMonitor +features it may take a few `git status` commands for the various +caches to warm up before you see improved command times. This is +normal. + SEE ALSO -------- linkgit:gitignore[5] diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 2438f76..a293327 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -29,7 +29,7 @@ With no arguments, this will: In the case where the input consists entirely of whitespace characters, no output will be produced. -*NOTE*: This is intended for cleaning metadata, prefer the `--whitespace=fix` +*NOTE*: This is intended for cleaning metadata. Prefer the `--whitespace=fix` mode of linkgit:git-apply[1] for correcting whitespace of patches or files in the repository. @@ -37,11 +37,11 @@ OPTIONS ------- -s:: --strip-comments:: - Skip and remove all lines starting with comment character (default '#'). + Skip and remove all lines starting with a comment character (default '#'). -c:: --comment-lines:: - Prepend comment character and blank to each line. Lines will automatically + Prepend the comment character and a blank space to each line. Lines will automatically be terminated with a newline. On empty lines, only the comment character will be prepended. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 4d3ab6b..ca0347a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree). init [--] [<path>...]:: Initialize the submodules recorded in the index (which were added and committed elsewhere) by setting `submodule.$name.url` - in .git/config. It uses the same setting from `.gitmodules` as + in `.git/config`, using the same setting from `.gitmodules` as a template. If the URL is relative, it will be resolved using the default remote. If there is no default remote, the current repository will be assumed to be upstream. @@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules configured to be active will be initialized, otherwise all submodules are initialized. + -When present, it will also copy the value of `submodule.$name.update`. -This command does not alter existing information in .git/config. -You can then customize the submodule clone URLs in .git/config +It will also copy the value of `submodule.$name.update`, if present in +the `.gitmodules` file, to `.git/config`, but (1) this command does not +alter existing information in `.git/config`, and (2) `submodule.$name.update` +that is set to a custom command is *not* copied for security reasons. ++ +You can then customize the submodule clone URLs in `.git/config` for your local setup and proceed to `git submodule update`; you can also just use `git submodule update --init` without the explicit 'init' step if you do not intend to customize @@ -133,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 @@ -143,6 +146,8 @@ the submodules. The "updating" can be done in several ways depending on command line options and the value of `submodule.<name>.update` configuration variable. The command line option takes precedence over the configuration variable. If neither is given, a 'checkout' is performed. +(note: what is in `.gitmodules` file is irrelevant at this point; +see `git submodule init` above for how `.gitmodules` is used). The 'update' procedures supported both from the command line as well as through the `submodule.<name>.update` configuration are: @@ -160,16 +165,18 @@ checked out in the submodule. merge;; the commit recorded in the superproject will be merged into the current branch in the submodule. -The following 'update' procedures are only available via the -`submodule.<name>.update` configuration variable: +The following update procedures have additional limitations: - custom command;; arbitrary shell command that takes a single - argument (the sha1 of the commit recorded in the - superproject) is executed. When `submodule.<name>.update` - is set to '!command', the remainder after the exclamation mark - is the custom command. + custom command;; mechanism for running arbitrary commands with the + commit ID as an argument. Specifically, if the + `submodule.<name>.update` configuration variable is set to + `!custom command`, the object name of the commit recorded in the + superproject for the submodule is appended to the `custom command` + string and executed. Note that this mechanism is not supported in + the `.gitmodules` file or on the command line. - none;; the submodule is not updated. + none;; the submodule is not updated. This update procedure is not + allowed on the command line. If the submodule is not yet initialized, and you just want to use the setting as stored in `.gitmodules`, you can automatically initialize the @@ -178,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 bbcbdce..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:: @@ -265,6 +270,13 @@ always create a new name for it (without switching away): $ git switch -c good-surprises ------------ +CONFIGURATION +------------- + +include::includes/cmd-config-section-all.txt[] + +include::config/checkout.txt[] + SEE ALSO -------- linkgit:git-checkout[1], diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index ef68ad2..761b154 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git symbolic-ref' [-m <reason>] <name> <ref> -'git symbolic-ref' [-q] [--short] <name> +'git symbolic-ref' [-q] [--short] [--no-recurse] <name> 'git symbolic-ref' --delete [-q] <name> DESCRIPTION @@ -27,7 +27,7 @@ symbolic ref. A symbolic ref is a regular file that stores a string that begins with `ref: refs/`. For example, your `.git/HEAD` is -a regular file whose contents is `ref: refs/heads/master`. +a regular file whose content is `ref: refs/heads/master`. OPTIONS ------- @@ -46,6 +46,15 @@ OPTIONS When showing the value of <name> as a symbolic ref, try to shorten the value, e.g. from `refs/heads/master` to `master`. +--recurse:: +--no-recurse:: + When showing the value of <name> as a symbolic ref, if + <name> refers to another symbolic ref, follow such a chain + of symbolic refs until the result no longer points at a + symbolic ref (`--recurse`, which is the default). + `--no-recurse` stops after dereferencing only a single level + of symbolic ref. + -m:: Update the reflog for <name> with <reason>. This is valid only when creating or updating a symbolic ref. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 31a97a1..5fe519c 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG SYNOPSIS -------- [verse] -'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e] +'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>] @@ -26,19 +26,19 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. -If one of `-a`, `-s`, or `-u <keyid>` is passed, the command +If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. -If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>` +If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. Otherwise, a tag reference that points directly at the given object (i.e., a lightweight tag) is created. A GnuPG signed tag object will be created when `-s` or `-u -<keyid>` is used. When `-u <keyid>` is not used, the +<key-id>` is used. When `-u <key-id>` is not used, the committer identity for the current user is used to find the GnuPG key for signing. The configuration variable `gpg.program` is used to specify custom GnuPG binary. @@ -72,8 +72,8 @@ OPTIONS Override `tag.gpgSign` configuration variable that is set to force each and every tag to be signed. --u <keyid>:: ---local-user=<keyid>:: +-u <key-id>:: +--local-user=<key-id>:: Make a GPG-signed tag, using the given key. -f:: @@ -131,6 +131,10 @@ options for details. --ignore-case:: Sorting and filtering tags are case insensitive. +--omit-empty:: + Do not print a newline after formatted refs where the format expands + to the empty string. + --column[=<options>]:: --no-column:: Display tag listing in columns. See configuration variable @@ -164,14 +168,14 @@ This option is only applicable when listing tags without annotation lines. Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. - Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` + Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. -F <file>:: --file=<file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. - Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` + Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. -e:: @@ -220,7 +224,7 @@ it in the repository configuration as follows: ------------------------------------- [user] - signingKey = <gpg-keyid> + signingKey = <gpg-key-id> ------------------------------------- `pager.tag` is only respected when listing tags, i.e., when `-l` is @@ -377,6 +381,16 @@ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 include::date-formats.txt[] +FILES +----- + +`$GIT_DIR/TAG_EDITMSG`:: + This file contains the message of an in-progress annotated + tag. If `git tag` exits due to an error before creating an + annotated tag then the tag message that has been provided by the + user in an editor session will be available in this file, but + may be overwritten by the next invocation of `git tag`. + NOTES ----- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 5ea2f2c..8c47890 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -49,7 +49,7 @@ OPTIONS --remove:: If a specified file is in the index but is missing then it's removed. - Default behavior is to ignore removed file. + Default behavior is to ignore removed files. --refresh:: Looks at the current index and checks to see if merges or @@ -95,7 +95,7 @@ OPTIONS the index. If you want to change the working tree file, you need to unset the bit to tell Git. This is sometimes helpful when working with a big project on a - filesystem that has very slow lstat(2) system call + filesystem that has a very slow lstat(2) system call (e.g. cifs). + Git will fail (gracefully) in case it needs to modify this file @@ -108,7 +108,7 @@ you will need to handle the situation manually. without regard to the "assume unchanged" setting. --[no-]skip-worktree:: - When one of these flags is specified, the object name recorded + When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. @@ -119,7 +119,7 @@ you will need to handle the situation manually. the `--remove` option was specified. --[no-]fsmonitor-valid:: - When one of these flags is specified, the object name recorded + When one of these flags is specified, the object names recorded for the paths are not updated. Instead, these options set and unset the "fsmonitor valid" bit for the paths. See section "File System Monitor" below for more information. @@ -127,7 +127,7 @@ you will need to handle the situation manually. -g:: --again:: Runs 'git update-index' itself on the paths whose index - entries are different from those from the `HEAD` commit. + entries are different from those of the `HEAD` commit. --unresolve:: Restores the 'unmerged' or 'needs updating' state of a @@ -151,24 +151,30 @@ you will need to handle the situation manually. automatically removed with warning messages. --stdin:: - Instead of taking list of paths from the command line, - read list of paths from the standard input. Paths are + Instead of taking a list of paths from the command line, + read a list of paths from the standard input. Paths are separated by LF (i.e. one path per line) by default. --verbose:: - Report what is being added and removed from index. + Report what is being added and removed from the index. --index-version <n>:: Write the resulting index out in the named on-disk format version. - Supported versions are 2, 3 and 4. The current default version is 2 + Supported versions are 2, 3, and 4. The current default version is 2 or 3, depending on whether extra features are used, such as - `git add -N`. + `git add -N`. With `--verbose`, also report the version the index + file uses before and after this command. + Version 4 performs a simple pathname compression that reduces index size by 30%-50% on large repositories, which results in faster load -time. Version 4 is relatively young (first released in 1.8.0 in -October 2012). Other Git implementations such as JGit and libgit2 -may not support it yet. +time. Git supports it since version 1.8.0, released in October 2012, +and support for it was added to libgit2 in 2016 and to JGit in 2020. +Older versions of this manual page called it "relatively young", but +it should be considered mature technology these days. + +--show-index-version:: + Report the index format version used by the on-disk index file. + See `--index-version` above. -z:: Only meaningful with `--stdin` or `--index-info`; paths are @@ -420,7 +426,7 @@ as `switch`, `pull`, `merge`) will avoid writing these files. However, these commands will sometimes write these files anyway in important cases such as conflicts during a merge or rebase. Git commands will also avoid treating the lack of such files as an -intentional deletion; for example `git add -u` will not not stage a +intentional deletion; for example `git add -u` will not stage a deletion for these files and `git commit -a` will not make a commit deleting them either. diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 48b6683..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,25 +100,25 @@ 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 behavior of the next command naming a <ref>. + Modify the behavior of the next command naming a <ref>. The only valid option is `no-deref` to avoid dereferencing a symbolic 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-update-server-info.txt b/Documentation/git-update-server-info.txt index 969bb2e..6bc9b50 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers SYNOPSIS -------- [verse] -'git update-server-info' +'git update-server-info' [-f | --force] DESCRIPTION ----------- @@ -19,11 +19,17 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover what references and packs the server has. This command generates such auxiliary files. +OPTIONS +------- +-f:: +--force:: + Update the info files from scratch. + OUTPUT ------ Currently the command updates the following files. Please see -linkgit:gitrepository-layout[5] for description of +linkgit:gitrepository-layout[5] for a description of what they are for: * objects/info/packs diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index fba0f1c..e8eb10b 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive SYNOPSIS -------- [verse] -'git upload-archive' <directory> +'git upload-archive' <repository> DESCRIPTION ----------- @@ -54,7 +54,7 @@ access via non-smart-http. OPTIONS ------- -<directory>:: +<repository>:: The repository to get a tar archive from. GIT diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 8f87b23..7ad60bc 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -26,7 +26,7 @@ OPTIONS ------- --[no-]strict:: - Do not try <directory>/.git/ if <directory> is no Git directory. + Do not try <directory>/.git/ if <directory> is not a Git directory. --timeout=<n>:: Interrupt transfer after <n> seconds of inactivity. @@ -39,10 +39,9 @@ OPTIONS --http-backend-info-refs:: Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See - "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in - link:technical/protocol-v2.html[the Git Wire Protocol, Version - 2] documentation. Also understood by + "Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP + Transport" in the linkgit:gitprotocol-v2[5] + documentation. Also understood by linkgit:git-receive-pack[1]. <directory>:: diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 387cc1b..0680568 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -9,16 +9,17 @@ git-var - Show a Git logical variable SYNOPSIS -------- [verse] -'git var' ( -l | <variable> ) +'git var' (-l | <variable>) DESCRIPTION ----------- -Prints a Git logical variable. +Prints a Git logical variable. Exits with code 1 if the variable has +no value. OPTIONS ------- -l:: - Cause the logical variables to be listed. In addition, all the + Display the logical variables. In addition, all the variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality is deprecated in favor of `git config -l`.) @@ -49,6 +50,14 @@ ifdef::git-default-editor[] The build you are using chose '{git-default-editor}' as the default. endif::git-default-editor[] +GIT_SEQUENCE_EDITOR:: + Text editor used to edit the 'todo' file while running `git rebase + -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by + the shell when it is used. The order of preference is the + `$GIT_SEQUENCE_EDITOR` environment variable, then + `sequence.editor` configuration, and then the value of `git var + GIT_EDITOR`. + GIT_PAGER:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference @@ -62,6 +71,29 @@ endif::git-default-pager[] GIT_DEFAULT_BRANCH:: The name of the first branch created in newly initialized repositories. +GIT_SHELL_PATH:: + The path of the binary providing the POSIX shell for commands which use the shell. + +GIT_ATTR_SYSTEM:: + The path to the system linkgit:gitattributes[5] file, if one is enabled. + +GIT_ATTR_GLOBAL:: + The path to the global (per-user) linkgit:gitattributes[5] file. + +GIT_CONFIG_SYSTEM:: + The path to the system configuration file, if one is enabled. + +GIT_CONFIG_GLOBAL:: + The path to the global (per-user) configuration files, if any. + +Most path values contain only one value. However, some can contain multiple +values, which are separated by newlines, and are listed in order from highest to +lowest priority. Callers should be prepared for any such path value to contain +multiple items. + +Note that paths are printed even if they do not exist, but not if they are +disabled by other environment variables. + SEE ALSO -------- linkgit:git-commit-tree[1] diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index 92097f6..aee4c40 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits SYNOPSIS -------- [verse] -'git verify-commit' <commit>... +'git verify-commit' [-v | --verbose] [--raw] <commit>... DESCRIPTION ----------- diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 61ca6d0..d7e8869 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -9,13 +9,13 @@ git-verify-pack - Validate packed Git archive files SYNOPSIS -------- [verse] -'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... +'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... DESCRIPTION ----------- Reads given idx file for packed Git archive created with the -'git pack-objects' command and verifies idx file and the +'git pack-objects' command and verifies the idx file and the corresponding pack file. OPTIONS @@ -25,13 +25,13 @@ OPTIONS -v:: --verbose:: - After verifying the pack, show list of objects contained + After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. -s:: --stat-only:: Do not verify the pack contents; only show the histogram of delta - chain length. With `--verbose`, list of objects is also shown. + chain length. With `--verbose`, the list of objects is also shown. \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index 0b8075d..81d50ec 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- [verse] -'git verify-tag' [--format=<format>] <tag>... +'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 8b63ceb..8e55e0b 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -3,7 +3,7 @@ git-whatchanged(1) NAME ---- -git-whatchanged - Show logs with difference each commit introduces +git-whatchanged - Show logs with differences each commit introduces SYNOPSIS @@ -18,11 +18,11 @@ Shows commit logs and diff output each commit introduces. New users are encouraged to use linkgit:git-log[1] instead. The `whatchanged` command is essentially the same as linkgit:git-log[1] -but defaults to show the raw format diff output and to skip merges. +but defaults to showing the raw format diff output and skipping merges. -The command is kept primarily for historical reasons; fingers of +The command is primarily kept for historical reasons; fingers of many people who learned Git long before `git log` was invented by -reading Linux kernel mailing list are trained to type it. +reading the Linux kernel mailing list are trained to type it. Examples diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index ada30c8..2a240f5 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>] +'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] + [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] 'git worktree list' [-v | --porcelain [-z]] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> @@ -94,6 +95,16 @@ exist, a new branch based on `HEAD` is automatically created as if `-b <branch>` was given. If `<branch>` does exist, it will be checked out in the new worktree, if it's not checked out anywhere else, otherwise the 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 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 +command fails with a warning reminding the user to fetch from their remote +first (or override by using `-f/--force`). list:: @@ -221,6 +232,10 @@ This can also be set up as the default behaviour by using the With `prune`, do not remove anything; just report what it would remove. +--orphan:: + With `add`, make the new worktree and index empty, associating + the worktree with a new unborn branch named `<new-branch>`. + --porcelain:: With `list`, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user @@ -271,7 +286,8 @@ rules and how to access refs of one worktree from another. In general, all pseudo refs are per-worktree and all refs starting with `refs/` are shared. Pseudo refs are ones like `HEAD` which are directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions, -however: refs inside `refs/bisect` and `refs/worktree` are not shared. +however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are +not shared. Refs that are per-worktree can still be accessed from another worktree via two special paths, `main-worktree` and `worktrees`. The former gives @@ -348,8 +364,8 @@ linked worktree `git rev-parse --git-path HEAD` returns `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git rev-parse --git-path refs/heads/master` uses `$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`, -since refs are shared across all worktrees, except `refs/bisect` and -`refs/worktree`. +since refs are shared across all worktrees, except `refs/bisect`, +`refs/worktree` and `refs/rewritten`. See linkgit:gitrepository-layout[5] for more information. The rule of thumb is do not make any assumption about whether a path belongs to diff --git a/Documentation/git.txt b/Documentation/git.txt index 302607a..7a1b112 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -13,8 +13,7 @@ SYNOPSIS [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] - [--super-prefix=<path>] [--config-env=<name>=<envvar>] - <command> [<args>] + [--config-env=<name>=<envvar>] <command> [<args>] DESCRIPTION ----------- @@ -97,9 +96,9 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config to avoid ambiguity with `<name>` containing one. + This is useful for cases where you want to pass transitory -configuration options to git, but are doing so on OS's where -other processes might be able to read your cmdline -(e.g. `/proc/self/cmdline`), but not your environ +configuration options to git, but are doing so on operating systems +where other processes might be able to read your command line +(e.g. `/proc/self/cmdline`), but not your environment (e.g. `/proc/self/environ`). That behavior is the default on Linux, but may not be on your system. + @@ -169,19 +168,23 @@ If you just want to run git as if it was started in `<path>` then use details. Equivalent to setting the `GIT_NAMESPACE` environment variable. ---super-prefix=<path>:: - Currently for internal use only. Set a prefix which gives a path from - above a repository down to its root. One use is to give submodules - context about the superproject that invoked it. - --bare:: Treat the repository as a bare repository. If GIT_DIR environment is not set, it is set to the current working 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). @@ -208,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 @@ -218,6 +221,11 @@ If you just want to run git as if it was started in `<path>` then use nohelpers (exclude helper commands), alias and config (retrieve command list from config variable completion.commands) +--attr-source=<tree-ish>:: + Read gitattributes from <tree-ish> instead of the worktree. See + linkgit:gitattributes[5]. This is equivalent to setting the + `GIT_ATTR_SOURCE` environment variable. + GIT COMMANDS ------------ @@ -339,6 +347,23 @@ The following documentation pages are guides about Git concepts. include::cmds-guide.txt[] +Repository, command and file interfaces +--------------------------------------- + +This documentation discusses repository and command interfaces which +users are expected to interact with directly. See `--user-formats` in +linkgit:git-help[1] for more details on the criteria. + +include::cmds-userinterfaces.txt[] + +File formats, protocols and other developer interfaces +------------------------------------------------------ + +This documentation discusses file formats, over-the-wire protocols and +other git developer interfaces. See `--developer-interfaces` in +linkgit:git-help[1]. + +include::cmds-developerinterfaces.txt[] Configuration Mechanism ----------------------- @@ -441,7 +466,12 @@ Please see linkgit:gitglossary[7]. Environment Variables --------------------- -Various Git commands use the following environment variables: +Various Git commands pay attention to environment variables and change +their behavior. The environment variables marked as "Boolean" take +their values the same way as Boolean valued configuration variables, e.g. +"true", "yes", "on" and positive numbers are taken as "yes". + +Here are the variables: The Git Repository ~~~~~~~~~~~~~~~~~~ @@ -450,13 +480,13 @@ is worth noting that they may be used/overridden by SCMS sitting above Git so take care if using a foreign front-end. `GIT_INDEX_FILE`:: - This environment allows the specification of an alternate + This environment variable specifies an alternate index file. If not specified, the default of `$GIT_DIR/index` is used. `GIT_INDEX_VERSION`:: - This environment variable allows the specification of an index - version for new repositories. It won't affect existing index + This environment variable specifies what index version is used + when writing the index file out. It won't affect existing index files. By default index file version 2 or 3 is used. See linkgit:git-update-index[1] for more information. @@ -513,7 +543,7 @@ double-quotes and respecting backslash escapes. E.g., the value When run in a directory that does not have ".git" repository directory, Git tries to find such a directory in the parent directories to find the top of the working tree, but by default it - does not cross filesystem boundaries. This environment variable + does not cross filesystem boundaries. This Boolean environment variable can be set to true to tell Git not to stop at filesystem boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect an explicit repository directory set via `GIT_DIR` or on the @@ -530,10 +560,15 @@ double-quotes and respecting backslash escapes. E.g., the value `GIT_DEFAULT_HASH`:: If this variable is set, the default hash algorithm for new - repositories will be set to this value. This value is currently - ignored when cloning; the setting of the remote repository - is used instead. The default is "sha1". THIS VARIABLE IS - EXPERIMENTAL! See `--object-format` in linkgit:git-init[1]. + repositories will be set to this value. This value is + ignored when cloning and the setting of the remote repository + 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 ~~~~~~~~~~~ @@ -597,7 +632,7 @@ The file parameters can point at the user's working file (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` when a new file is added), or a temporary file (e.g. `old-file` in the index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the -temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits. +temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits. + For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1 parameter, <path>. @@ -665,6 +700,14 @@ for further details. plink or tortoiseplink. This variable overrides the config setting `ssh.variant` that serves the same purpose. +`GIT_SSL_NO_VERIFY`:: + Setting and exporting this environment variable to any value + tells Git not to verify the SSL certificate when fetching or + pushing over HTTPS. + +`GIT_ATTR_SOURCE`:: + Sets the treeish that gitattributes will be read from. + `GIT_ASKPASS`:: If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) @@ -673,7 +716,7 @@ for further details. option in linkgit:git-config[1]. `GIT_TERMINAL_PROMPT`:: - If this environment variable is set to `0`, git will not prompt + If this Boolean environment variable is set to false, git will not prompt on the terminal (e.g., when asking for HTTP authentication). `GIT_CONFIG_GLOBAL`:: @@ -688,19 +731,19 @@ for further details. `GIT_CONFIG_NOSYSTEM`:: Whether to skip reading settings from the system-wide - `$(prefix)/etc/gitconfig` file. This environment variable can + `$(prefix)/etc/gitconfig` file. This Boolean environment variable can be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a predictable environment for a picky script, or you can set it - temporarily to avoid using a buggy `/etc/gitconfig` file while + to true to temporarily avoid using a buggy `/etc/gitconfig` file while waiting for someone with sufficient permissions to fix it. `GIT_FLUSH`:: - 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. @@ -808,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`. + @@ -835,11 +878,15 @@ for full details. `GIT_TRACE_REDACT`:: By default, when tracing is activated, Git redacts the values of cookies, the "Authorization:" header, the "Proxy-Authorization:" - header and packfile URIs. Set this variable to `0` to prevent this + header and packfile URIs. Set this Boolean environment variable to false to prevent this redaction. +`GIT_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 variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search for commits that touch the path `*.c`, not any paths that the @@ -848,17 +895,22 @@ for full details. `git ls-tree`, `--raw` diff output, etc). `GIT_GLOB_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs as glob patterns (aka "glob" magic). `GIT_NOGLOB_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs as literal (aka "literal" magic). `GIT_ICASE_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs as case-insensitive. +`GIT_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 @@ -870,7 +922,7 @@ for full details. end user, to be recorded in the body of the reflog. `GIT_REF_PARANOIA`:: - If set to `0`, ignore broken or badly named refs when iterating + If this Boolean environment variable is set to false, ignore broken or badly named refs when iterating over lists of refs. Normally Git will try to include any such refs, which may cause some operations to fail. This is usually preferable, as potentially destructive operations (e.g., @@ -881,17 +933,25 @@ for full details. should not normally need to set this to `0`, but it may be useful when trying to salvage data from a corrupted repository. +`GIT_COMMIT_GRAPH_PARANOIA`:: + When loading a commit object from the commit-graph, Git performs an + existence check on the object in the object database. This is done to + avoid issues with stale commit-graphs that contain references to + already-deleted commits, but comes with a performance penalty. ++ +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 `protocol.allow` is set to `never`, and each of the listed protocols has `protocol.<name>.allow` set to `always` - (overriding any existing configuration). In other words, any - protocol not mentioned will be disallowed (i.e., this is a - whitelist, not a blacklist). See the description of + (overriding any existing configuration). See the description of `protocol.allow` in linkgit:git-config[1] for more details. `GIT_PROTOCOL_FROM_USER`:: - Set to 0 to prevent protocols used by fetch/push/clone which are + Set this Boolean environment variable to false to prevent protocols used by fetch/push/clone which are configured to the `user` state. This is useful to restrict recursive submodule initialization from an untrusted repository or for programs which feed potentially-untrusted URLS to git commands. See @@ -900,7 +960,7 @@ for full details. `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 @@ -919,7 +979,7 @@ only affects clones and fetches; it is not yet used for pushes (but may be in the future). `GIT_OPTIONAL_LOCKS`:: - If set to `0`, Git will complete any requested operation without + If this Boolean environment variable is set to false, Git will complete any requested operation without performing any optional sub-operations that require taking a lock. For example, this will prevent `git status` from refreshing the index as a side effect. This is useful for processes running in @@ -987,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 @@ -1033,7 +1094,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 4b36d51..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 ------- @@ -120,20 +135,19 @@ repository upon 'git add' and 'git commit'. `text` ^^^^^^ -This attribute enables and controls end-of-line normalization. When a -text file is normalized, its line endings are converted to LF in the -repository. To control what line ending style is used in the working -directory, use the `eol` attribute for a single file and the -`core.eol` configuration variable for all text files. -Note that setting `core.autocrlf` to `true` or `input` overrides -`core.eol` (see the definitions of those options in -linkgit:git-config[1]). +This attribute marks the path as a text file, which enables end-of-line +conversion: When a matching file is added to the index, the file's line +endings are normalized to LF in the index. Conversely, when the file is +copied from the index to the working directory, its line endings may be +converted from LF to CRLF depending on the `eol` attribute, the Git +config, and the platform (see explanation of `eol` below). Set:: Setting the `text` attribute on a path enables end-of-line - normalization and marks the path as a text file. End-of-line - conversion takes place without guessing the content type. + conversion on checkin and checkout as described above. Line endings + are normalized to LF in the index every time the file is checked in, + even if the file was previously added to Git with CRLF line endings. Unset:: @@ -142,10 +156,11 @@ Unset:: Set to string value "auto":: - When `text` is set to "auto", the path is marked for automatic - end-of-line conversion. If Git decides that the content is - text, its line endings are converted to LF on checkin. - When the file has been committed with CRLF, no conversion is done. + When `text` is set to "auto", Git decides by itself whether the file + is text or binary. If it is text and the file was not already in + Git with CRLF endings, line endings are converted on checkin and + checkout as described above. Otherwise, no conversion is done on + checkin or checkout. Unspecified:: @@ -159,26 +174,29 @@ unspecified. `eol` ^^^^^ -This attribute sets a specific line-ending style to be used in the -working directory. This attribute has effect only if the `text` -attribute is set or unspecified, or if it is set to `auto`, the file is -detected as text, and it is stored with LF endings in the index. Note -that setting this attribute on paths which are in the index with CRLF -line endings may make the paths to be considered dirty unless -`text=auto` is set. Adding the path to the index again will normalize -the line endings in the index. +This attribute marks a path to use a specific line-ending style in the +working tree when it is checked out. It has effect only if `text` or +`text=auto` is set (see above), but specifying `eol` automatically sets +`text` if `text` was left unspecified. Set to string value "crlf":: - This setting forces Git to normalize line endings for this - file on checkin and convert them to CRLF when the file is - checked out. + This setting converts the file's line endings in the working + directory to CRLF when the file is checked out. Set to string value "lf":: - This setting forces Git to normalize line endings to LF on - checkin and prevents conversion to CRLF when the file is - checked out. + This setting uses the same line endings in the working directory as + in the index when the file is checked out. + +Unspecified:: + + If the `eol` attribute is unspecified for a file, its line endings + in the working directory are determined by the `core.autocrlf` or + `core.eol` configuration variable (see the definitions of those + options in linkgit:git-config[1]). If `text` is set but neither of + those variables is, the default is `eol=crlf` on Windows and + `eol=lf` on all other platforms. Backwards compatibility with `crlf` attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -758,6 +776,37 @@ with the above configuration, i.e. `j-c-diff`, with 7 parameters, just like `GIT_EXTERNAL_DIFF` program is called. See linkgit:git[1] for details. +Setting the internal diff algorithm +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The diff algorithm can be set through the `diff.algorithm` config key, but +sometimes it may be helpful to set the diff algorithm per path. For example, +one may want to use the `minimal` diff algorithm for .json files, and the +`histogram` for .c files, and so on without having to pass in the algorithm +through the command line each time. + +First, in `.gitattributes`, assign the `diff` attribute for paths. + +------------------------ +*.json diff=<name> +------------------------ + +Then, define a "diff.<name>.algorithm" configuration to specify the diff +algorithm, choosing from `myers`, `patience`, `minimal`, or `histogram`. + +---------------------------------------------------------------- +[diff "<name>"] + algorithm = histogram +---------------------------------------------------------------- + +This diff algorithm applies to user facing diff output like git-diff(1), +git-show(1) and is used for the `--stat` output as well. The merge machinery +will not use the diff algorithm set through this method. + +NOTE: If `diff.<name>.command` is defined for path with the +`diff=<name>` attribute, it is executed as an external diff driver +(see above), and adding `diff.<name>.algorithm` has no effect, as the +algorithm is not passed to the external diff driver. Defining a custom hunk-header ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1088,17 +1137,20 @@ 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 the file named with `%A` by overwriting it, and exit with zero status if it managed to merge them cleanly, or non-zero if there -were conflicts. +were conflicts. When the driver crashes (e.g. killed by SEGV), +it is expected to exit with non-zero status that are higher than +128, and in such a case, the merge results in a failure (which is +different from producing a conflict). The `merge.*.recursive` variable specifies what other merge driver to use when the merge driver is called for an internal @@ -1107,15 +1159,16 @@ 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` ^^^^^^^^^^^^^^^^^^^^^^ This attribute controls the length of conflict markers left in -the work tree file during a conflicted merge. Only setting to -the value to a positive integer has any meaningful effect. +the work tree file during a conflicted merge. Only a positive +integer has a meaningful effect. For example, this line in `.gitattributes` can be used to tell the merge machinery to leave much longer (instead of the usual 7-character-long) @@ -1155,7 +1208,7 @@ Unspecified:: String:: - Specify a comma separate list of common whitespace problems to + Specify a comma separated list of common whitespace problems to notice in the same format as the `core.whitespace` configuration variable. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 1819a5a..7c70932 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -23,10 +23,10 @@ arguments. Here are the rules: A subcommand may take dashed options (which may take their own arguments, e.g. "--max-parents 2") and arguments. You SHOULD give dashed options first and then arguments. Some commands may - accept dashed options after you have already gave non-option + accept dashed options after you have already given non-option arguments (which may make the command ambiguous), but you should not rely on it (because eventually we may find a way to fix - these ambiguity by enforcing the "options then args" rule). + these ambiguities by enforcing the "options then args" rule). * Revisions come first and then paths. E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, @@ -37,12 +37,12 @@ arguments. Here are the rules: they can be disambiguated by placing `--` between them. E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work tree. Please show changes between the version I staged in the index - and what I have in the work tree for that file", not "show difference + and what I have in the work tree for that file", not "show the difference between the HEAD commit and the work tree as a whole". You can say `git diff HEAD --` to ask for the latter. * Without disambiguating `--`, Git makes a reasonable guess, but errors - out and asking you to disambiguate when ambiguous. E.g. if you have a + out and asks you to disambiguate when ambiguous. E.g. if you have a file called HEAD in your work tree, `git diff HEAD` is ambiguous, and you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. @@ -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/gitcredentials.txt b/Documentation/gitcredentials.txt index 80517b4..71dd197 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -17,9 +17,10 @@ DESCRIPTION Git will sometimes need credentials from the user in order to perform operations; for example, it may need to ask for a username and password -in order to access a remote repository over HTTP. This manual describes -the mechanisms Git uses to request these credentials, as well as some -features to avoid inputting these credentials repeatedly. +in order to access a remote repository over HTTP. Some remotes accept +a personal access token or OAuth access token as a password. This +manual describes the mechanisms Git uses to request these credentials, +as well as some features to avoid inputting these credentials repeatedly. REQUESTING CREDENTIALS ---------------------- @@ -61,7 +62,9 @@ for a password. It is generally configured by adding this to your config: Credential helpers, on the other hand, are external programs from which Git can request both usernames and passwords; they typically interface with secure -storage provided by the OS or other programs. +storage provided by the OS or other programs. Alternatively, a +credential-generating helper might generate credentials for certain servers via +some API. To use a helper, you must first select one to use. Git currently includes the following helpers: @@ -101,6 +104,17 @@ $ git help credential-foo $ git config --global credential.helper foo ------------------------------------------- +=== Available helpers + +The community maintains a comprehensive list of Git credential helpers at +https://git-scm.com/doc/credential-helpers. + +=== OAuth + +An alternative to inputting passwords or personal access tokens is to use an +OAuth credential helper. Initial authentication opens a browser window to the +host. Subsequent authentication happens in the background. Many popular Git +hosts support OAuth. CREDENTIAL CONTEXTS ------------------- @@ -164,7 +178,7 @@ helper:: If there are multiple instances of the `credential.helper` configuration variable, each helper will be tried in turn, and may provide a username, password, or nothing. Once Git has acquired both a username and a -password, no more helpers will be tried. +non-expired password, no more helpers will be tried. + If `credential.helper` is configured to the empty string, this resets the helper list to empty (so you may override a helper set by a @@ -257,7 +271,7 @@ appended to its command line, which is one of: `erase`:: - Remove a matching credential, if any, from the helper's storage. + Remove matching credentials, if any, from the helper's storage. The details of the credential will be provided on the helper's stdin stream. The exact format is the same as the input/output format of the @@ -269,6 +283,7 @@ stdout in the same format (see linkgit:git-credential[1] for common attributes). A helper is free to produce a subset, or even no values at all if it has nothing useful to provide. Any provided attributes will overwrite those already known about by Git's credential subsystem. +Unrecognised attributes are silently discarded. While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and @@ -286,8 +301,8 @@ For a `store` or `erase` operation, the helper's output is ignored. If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr. -If it does not support the requested operation (e.g., a read-only store), -it should silently ignore the request. +If it does not support the requested operation (e.g., a read-only store +or generator), it should silently ignore the request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 0d57f86..642c512 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -173,7 +173,7 @@ Note that when rename detection is on but both copy and break detection are off, rename detection adds a preliminary step that first checks if files are moved across directories while keeping their filename the same. If there is a file added to a directory whose -contents is sufficiently similar to a file with the same name that got +contents are sufficiently similar to a file with the same name that got deleted from a different directory, it will mark them as renames and exclude them from the later quadratic step (the one that pairwise compares all unmatched files to find the "best" matches, determined by @@ -213,7 +213,7 @@ from the original, and does not count insertion. If you removed only 10 lines from a 100-line document, even if you added 910 new lines to make a new 1000-line document, you did not do a complete rewrite. diffcore-break breaks such a case in order to -help diffcore-rename to consider such filepairs as candidate of +help diffcore-rename to consider such filepairs as a candidate of rename/copy detection, but if filepairs broken that way were not matched with other filepairs to create rename/copy, then this transformation merges them back into the original @@ -230,13 +230,13 @@ like these: * -B/60 (the same as above, since diffcore-break defaults to 50%). -Note that earlier implementation left a broken pair as a separate -creation and deletion patches. This was an unnecessary hack and +Note that earlier implementation left a broken pair as separate +creation and deletion patches. This was an unnecessary hack, and the latest implementation always merges all the broken pairs back into modifications, but the resulting patch output is formatted differently for easier review in case of such -a complete rewrite by showing the entire contents of old version -prefixed with '-', followed by the entire contents of new +a complete rewrite by showing the entire contents of the old version +prefixed with '-', followed by the entire contents of the new version prefixed with '+'. @@ -245,25 +245,25 @@ 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 implementation runs diff twice and greps, and this can be quite -expensive. To speed things up binary files without textconv filters +expensive. To speed things up, binary files without textconv filters will be ignored. When `-S` or `-G` are used without `--pickaxe-all`, only filepairs diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt index faba2ef..6cfdd0e 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt @@ -14,7 +14,7 @@ DESCRIPTION ----------- Git users can broadly be grouped into four categories for the purposes of -describing here a small set of useful command for everyday Git. +describing here a small set of useful commands for everyday Git. * <<STANDALONE,Individual Developer (Standalone)>> commands are essential for anybody who makes a commit, even for somebody who works alone. @@ -229,7 +229,7 @@ without a formal "merging". Or longhand + git am -3 -k` An alternate participant submission mechanism is using the -`git request-pull` or pull-request mechanisms (e.g as used on +`git request-pull` or pull-request mechanisms (e.g. as used on GitHub (www.github.com) to notify your upstream of your contribution. diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt index b9be864..1b75cf7 100644 --- a/Documentation/technical/bundle-format.txt +++ b/Documentation/gitformat-bundle.txt @@ -1,11 +1,33 @@ -= Git bundle v2 format +gitformat-bundle(5) +=================== -The Git bundle format is a format that represents both refs and Git objects. +NAME +---- +gitformat-bundle - The bundle file format + + +SYNOPSIS +-------- +[verse] +*.bundle +*.bdl + +DESCRIPTION +----------- + +The Git bundle format is a format that represents both refs and Git +objects. A bundle is a header in a format similar to +linkgit:git-show-ref[1] followed by a pack in *.pack format. -== Format +The format is created and read by the linkgit:git-bundle[1] command, +and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1]. + + +FORMAT +------ We will use ABNF notation to define the Git bundle format. See -protocol-common.txt for the details. +linkgit:gitprotocol-common[5] for the details. A v2 bundle looks like this: @@ -36,14 +58,16 @@ value = *(%01-09 / %0b-FF) pack = ... ; packfile ---- -== Semantics + +SEMANTICS +--------- A Git bundle consists of several parts. * "Capabilities", which are only in the v3 format, indicate functionality that the bundle requires to be read properly. -* "Prerequisites" lists the objects that are NOT included in the bundle and the +* "Prerequisites" list the objects that are NOT included in the bundle and the reader of the bundle MUST already have, in order to use the data in the bundle. The objects stored in the bundle may refer to prerequisite objects and anything reachable from them (e.g. a tree object in the bundle can reference @@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id. This is a comment and it has no specific meaning. The writer of the bundle MAY put any string here. The reader of the bundle MUST ignore the comment. -=== Note on the shallow clone and a Git bundle +Note on shallow clones and Git bundles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note that the prerequisites does not represent a shallow-clone boundary. The +Note that the prerequisites do not represent a shallow-clone boundary. The semantics of the prerequisites and the shallow-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository. -== Capabilities +CAPABILITIES +------------ Because there is no opportunity for negotiation, unknown capabilities cause 'git bundle' to abort. @@ -79,3 +105,7 @@ bundle' to abort. * `filter` specifies an object filter as in the `--filter` option in linkgit:git-rev-list[1]. The resulting pack-file must be marked as a `.promisor` pack-file after it is unbundled. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt index 593614f..3315df6 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/gitformat-chunk.txt @@ -1,12 +1,25 @@ -Chunk-based file formats -======================== +gitformat-chunk(5) +================== + +NAME +---- +gitformat-chunk - Chunk-based file formats + +SYNOPSIS +-------- + +Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see +the pack format documentation in linkgit:gitformat-pack[5]). + +DESCRIPTION +----------- Some file formats in Git use a common concept of "chunks" to describe sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the `commit-graph` and `multi-pack-index` files. See -link:technical/pack-format.html[the `multi-pack-index` format] and -link:technical/commit-graph-format.html[the `commit-graph` format] for +the `multi-pack-index` format in linkgit:gitformat-pack[5] and +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for how they use the chunks to describe structured data. A chunk-based file format begins with some header information custom to @@ -29,7 +42,7 @@ Each row consists of a 4-byte chunk identifier (ID) and an 8-byte offset. Each integer is stored in network-byte order. The chunk identifier `ID[i]` is a label for the data stored within this -fill from `OFFSET[i]` (inclusive) to `OFFSET[i+1]` (exclusive). Thus, the +file from `OFFSET[i]` (inclusive) to `OFFSET[i+1]` (exclusive). Thus, the size of the `i`th chunk is equal to the difference between `OFFSET[i+1]` and `OFFSET[i]`. This requires that the chunk data appears contiguously in the same order as the table of contents. @@ -54,7 +67,7 @@ caller is responsible for opening the `hashfile` and writing header information so the file format is identifiable before the chunk-based format begins. -Then, call `add_chunk()` for each chunk that is intended for write. This +Then, call `add_chunk()` for each chunk that is intended for writing. This populates the `chunkfile` with information about the order and size of each chunk to write. Provide a `chunk_write_fn` function pointer to perform the write of the chunk data upon request. @@ -108,9 +121,13 @@ for future formats: * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()` in `commit-graph.c` for how the chunk-format API is used to write and parse the commit-graph file format documented in - link:technical/commit-graph-format.html[the commit-graph file format]. + the commit-graph file format in linkgit:gitformat-commit-graph[5]. * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` in `midx.c` for how the chunk-format API is used to write and parse the multi-pack-index file format documented in - link:technical/pack-format.html[the multi-pack-index file format]. + the multi-pack-index file format section of linkgit:gitformat-pack[5]. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt index 484b185..31cad58 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -1,7 +1,20 @@ -Git commit graph format -======================= +gitformat-commit-graph(5) +========================= -The Git commit graph stores a list of commit OIDs and some associated +NAME +---- +gitformat-commit-graph - Git commit-graph format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/info/commit-graph +$GIT_DIR/objects/info/commit-graphs/* + +DESCRIPTION +----------- + +The Git commit-graph stores a list of commit OIDs and some associated metadata, including: - The generation number of the commit. @@ -21,7 +34,7 @@ corresponding to the array position within the list of commit OIDs. Due to some special constants we use to track parents, we can store at most (1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits. -== Commit graph files have the following format: +== Commit-graph files have the following format: In order to allow extensions that add extra data to the graph, we organize the body into "chunks" and provide a binary lookup table at the beginning @@ -30,7 +43,7 @@ and hash type. All multi-byte numbers are in network byte order. -HEADER: +=== HEADER: 4-byte signature: The signature is: {'C', 'G', 'P', 'H'} @@ -52,7 +65,7 @@ HEADER: We infer the length (H*B) of the Base Graphs chunk from this value. -CHUNK LOOKUP: +=== CHUNK LOOKUP: (C + 1) * 12 bytes listing the table of contents for the chunks: First 4 bytes describe the chunk id. Value 0 is a terminating label. @@ -62,23 +75,23 @@ CHUNK LOOKUP: ID appears at most once. The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5] The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless otherwise specified. -CHUNK DATA: +=== CHUNK DATA: - OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) The ith entry, F[i], stores the number of OIDs with first byte at most i. Thus F[255] stores the total number of commits (N). - OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) +==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) The OIDs for all commits in the graph, sorted in ascending order. - Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) +==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) * The first H bytes are for the OID of the root tree. * The next 8 bytes are for the positions of the first two parents of the ith commit. Stores value 0x70000000 if no parent in that @@ -93,7 +106,7 @@ CHUNK DATA: 2 bits of the lowest byte, storing the 33rd and 34th bit of the commit time. - Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] * This list of 4-byte values store corrected commit date offsets for the commits, arranged in the same order as commit data chunk. * If the corrected commit date offset cannot be stored within 31 bits, @@ -104,7 +117,7 @@ CHUNK DATA: by compatible versions of Git and in case of split commit-graph chains, the topmost layer also has Generation Data chunk. - Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] * This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits. @@ -112,7 +125,7 @@ CHUNK DATA: chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits. - Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit @@ -120,14 +133,14 @@ CHUNK DATA: positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent. - Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters from commit 0 to commit i (inclusive) in lexicographic order. The Bloom filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header length), where BIDX[-1] is 0. * The BIDX chunk is ignored if the BDAT chunk is not present. - Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] * It starts with header consisting of three unsigned 32-bit integers: - Version of the hash algorithm being used. We currently only support value 1 which corresponds to the 32-bit version of the murmur3 hash @@ -147,13 +160,13 @@ CHUNK DATA: of length one, with either all bits set to zero or one respectively. * The BDAT chunk is present if and only if BIDX is present. - Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] This list of H-byte hashes describe a set of B commit-graph files that form a commit-graph chain. The graph position for the ith commit in this file's OID Lookup chunk is equal to i plus the number of commits in all base graphs. If B is non-zero, this chunk must exist. -TRAILER: +=== TRAILER: H-byte HASH-checksum of all of the above. @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By changing the IDs, newer versions of Git will silently ignore those older chunks and write the new information without trusting the incorrect data. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt index 65da0da..145cace 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/gitformat-index.txt @@ -1,5 +1,19 @@ +gitformat-index(5) +================== + +NAME +---- +gitformat-index - Git index format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/index + +DESCRIPTION +----------- + Git index format -================ == The Git index file has the following format @@ -26,8 +40,6 @@ Git index format Extensions are identified by signature. Optional extensions can be ignored if Git does not understand them. - Git currently supports cache tree and resolve undo extensions. - 4-byte extension signature. If the first byte is 'A'..'Z' the extension is optional and can be ignored. @@ -71,11 +83,13 @@ Git index format 32-bit mode, split into (high to low bits) + 16-bit unused, must be zero + 4-bit object type valid values in binary are 1000 (regular file), 1010 (symbolic link) and 1110 (gitlink) - 3-bit unused + 3-bit unused, must be zero 9-bit unix permission. Only 0755 and 0644 are valid for regular files. Symbolic links and gitlinks have value 0 in this field. @@ -127,7 +141,7 @@ Git index format entry is encoded as if the path name for the previous entry is an empty string). At the beginning of an entry, an integer N in the variable width encoding (the same encoding as the offset is encoded - for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed by a NUL-terminated string S. Removing N bytes from the end of the path name for the previous entry, and replacing it with the string S yields the path name for this entry. @@ -372,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 @@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type: with signature { 's', 'd', 'i', 'r' }. Like the split-index extension, tools should avoid interacting with a sparse index unless they understand this extension. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt index b520aa9..d6ae229 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/gitformat-pack.txt @@ -1,5 +1,30 @@ -Git pack format -=============== +gitformat-pack(5) +================= + +NAME +---- +gitformat-pack - Git pack format + + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/pack-*.{pack,idx} +$GIT_DIR/objects/pack/pack-*.rev +$GIT_DIR/objects/pack/pack-*.mtimes +$GIT_DIR/objects/pack/multi-pack-index + +DESCRIPTION +----------- + +The Git pack format is how Git stores most of its primary repository +data. Over the lifetime of a repository, loose objects (if any) and +smaller packs are consolidated into larger pack(s). See +linkgit:git-gc[1] and linkgit:git-pack-objects[1]. + +The pack format is also used over-the-wire, see +e.g. linkgit:gitprotocol-v2[5], as well as being a part of +other container formats in the case of linkgit:gitformat-bundle[5]. == Checksums and object IDs @@ -23,7 +48,7 @@ Similarly, in SHA-256 repositories, these values are computed using SHA-256. Observation: we cannot have more than 4G versions ;-) and more than 4G objects in a pack. - - The header is followed by number of object entries, each of + - The header is followed by a number of object entries, each of which looks like this: (undeltified representation) @@ -37,7 +62,7 @@ Similarly, in SHA-256 repositories, these values are computed using SHA-256. is an OBJ_OFS_DELTA object compressed delta data - Observation: length of each object is encoded in a variable + Observation: the length of each object is encoded in a variable length format and is not constrained to 32-bit or anything. - The trailer records a pack checksum of all of the above. @@ -92,7 +117,7 @@ the delta data is a sequence of instructions to reconstruct the object from the base object. If the base object is deltified, it must be converted to canonical form first. Each instruction appends more and more data to the target object until it's complete. There are two -supported instructions so far: one for copy a byte range from the +supported instructions so far: one for copying a byte range from the source object and one for inserting new data embedded in the instruction itself. @@ -112,7 +137,7 @@ copy. Offset and size are in little-endian order. All offset and size bytes are optional. This is to reduce the instruction size when encoding small offsets or sizes. The first seven -bits in the first octet determines which of the next seven octets is +bits in the first octet determine which of the next seven octets is present. If bit zero is set, offset1 is present. If bit one is set offset2 is present and so on. @@ -136,9 +161,9 @@ converted to 0x10000. | 0xxxxxxx | data | +----------+============+ -This is the instruction to construct target object without the base +This is the instruction to construct the target object without the base object. The following data is appended to the target object. The first -seven bits of the first octet determines the size of data in +seven bits of the first octet determine the size of data in bytes. The size must be non-zero. ==== Reserved instruction @@ -269,7 +294,7 @@ Pack file entry: <+ - The same trailer as a v1 pack file: - A copy of the pack checksum at the end of + A copy of the pack checksum at the end of the corresponding packfile. Index checksum of all of the above. @@ -356,7 +381,7 @@ CHUNK LOOKUP: using the next chunk position if necessary.) The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5]. The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless @@ -365,10 +390,20 @@ CHUNK LOOKUP: CHUNK DATA: Packfile Names (ID: {'P', 'N', 'A', 'M'}) - Stores the packfile names as concatenated, null-terminated strings. - Packfiles must be listed in lexicographic order for fast lookups by - name. This is the only chunk not guaranteed to be a multiple of four - bytes in length, so should be the last chunk for alignment reasons. + Store the names of packfiles as a sequence of NUL-terminated + strings. There is no extra padding between the filenames, + and they are listed in lexicographic order. The chunk itself + 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 @@ -482,3 +517,165 @@ 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 +removing unreachable objects. This document provides an overview of Git's +pruning mechanism, and how a cruft pack can be used instead to accomplish the +same. + +=== Background + +To remove unreachable objects from your repository, Git offers `git repack -Ad` +(see linkgit:git-repack[1]). Quoting from the documentation: + +---- +[...] unreachable objects in a previous pack become loose, unpacked objects, +instead of being left in the old pack. [...] loose unreachable objects will be +pruned according to normal expiry rules with the next 'git gc' invocation. +---- + +Unreachable objects aren't removed immediately, since doing so could race with +an incoming push which may reference an object which is about to be deleted. +Instead, those unreachable objects are stored as loose objects and stay that way +until they are older than the expiration window, at which point they are removed +by linkgit:git-prune[1]. + +Git must store these unreachable objects loose in order to keep track of their +per-object mtimes. If these unreachable objects were written into one big pack, +then either freshening that pack (because an object contained within it was +re-written) or creating a new pack of unreachable objects would cause the pack's +mtime to get updated, and the objects within it would never leave the expiration +window. Instead, objects are stored loose in order to keep track of the +individual object mtimes and avoid a situation where all cruft objects are +freshened at once. + +This can lead to undesirable situations when a repository contains many +unreachable objects which have not yet left the grace period. Having large +directories in the shards of `.git/objects` can lead to decreased performance in +the repository. But given enough unreachable objects, this can lead to inode +starvation and degrade the performance of the whole system. Since we +can never pack those objects, these repositories often take up a large amount of +disk space, since we can only zlib compress them, but not store them in delta +chains. + +=== Cruft packs + +A cruft pack eliminates the need for storing unreachable objects in a loose +state by including the per-object mtimes in a separate file alongside a single +pack containing all loose objects. + +A cruft pack is written by `git repack --cruft` when generating a new pack. +linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft` +is a classic all-into-one repack, meaning that everything in the resulting pack is +reachable, and everything else is unreachable. Once written, the `--cruft` +option instructs `git repack` to generate another pack containing only objects +not packed in the previous step (which equates to packing all unreachable +objects together). This progresses as follows: + + 1. Enumerate every object, marking any object which is (a) not contained in a + kept-pack, and (b) whose mtime is within the grace period as a traversal + tip. + + 2. Perform a reachability traversal based on the tips gathered in the previous + step, adding every object along the way to the pack. + + 3. Write the pack out, along with a `.mtimes` file that records the per-object + timestamps. + +This mode is invoked internally by linkgit:git-repack[1] when instructed to +write a cruft pack. Crucially, the set of in-core kept packs is exactly the set +of packs which will not be deleted by the repack; in other words, they contain +all of the repository's reachable objects. + +When a repository already has a cruft pack, `git repack --cruft` typically only +adds objects to it. An exception to this is when `git repack` is given the +`--cruft-expiration` option, which allows the generated cruft pack to omit +expired objects instead of waiting for linkgit:git-gc[1] to expire those objects +later on. + +It is linkgit:git-gc[1] that is typically responsible for removing expired +unreachable objects. + +=== Alternatives + +Notable alternatives to this design include: + + - The location of the per-object mtime data. + +On the location of mtime data, a new auxiliary file tied to the pack was chosen +to avoid complicating the `.idx` format. If the `.idx` format were ever to gain +support for optional chunks of data, it may make sense to consolidate the +`.mtimes` format into the `.idx` itself. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt index 166721b..d4d3a31 100644 --- a/Documentation/technical/signature-format.txt +++ b/Documentation/gitformat-signature.txt @@ -1,17 +1,40 @@ -Git signature format -==================== +gitformat-signature(5) +====================== -== Overview +NAME +---- +gitformat-signature - Git cryptographic signature formats + +SYNOPSIS +-------- +[verse] +<[tag|commit] object header(s)> +<over-the-wire protocol> + +DESCRIPTION +----------- Git uses cryptographic signatures in various places, currently objects (tags, commits, mergetags) and transactions (pushes). In every case, the command which is about to create an object or transaction determines a payload from that, -calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and -embeds the signature into the object or transaction. +calls an external program to obtain a detached signature for the payload +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the +object or transaction. + +Signatures begin with an "ASCII Armor" header line and end with a tail line, +which differ depending on signature type (as selected by `gpg.format`, see +linkgit:git-config[1]). These are, for `gpg.format` values: -Signatures always begin with `-----BEGIN PGP SIGNATURE-----` -and end with `-----END PGP SIGNATURE-----`, unless gpg is told to -produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`. +`gpg` (PGP):: + `-----BEGIN PGP SIGNATURE-----` and `-----END PGP SIGNATURE-----`. + Or, if gpg is told to produce RFC1991 signatures, + `-----BEGIN PGP MESSAGE-----` and `-----END PGP MESSAGE-----` + +`ssh` (SSH):: + `-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----` + +`x509` (X.509):: + `-----BEGIN SIGNED MESSAGE-----` and `-----END SIGNED MESSAGE-----` Signatures sometimes appear as a part of the normal payload (e.g. a signed tag has the signature block appended after the payload @@ -26,7 +49,7 @@ line. This is even true for an originally empty line. In the following examples, the end of line that ends with a whitespace letter is highlighted with a `$` sign; if you are trying to recreate these -example by hand, do not cut and paste them---they are there +example by hand, do not cut and paste them--they are there primarily to highlight extra whitespace at the end of some lines. The signed payload and the way the signature is embedded depends @@ -200,3 +223,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000 # gpg: There is no indication that the signature belongs to the owner. # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index a16e62b..ee9b92c 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -27,6 +27,18 @@ repository. An exception are hooks triggered during a push ('pre-receive', 'update', 'post-receive', 'post-update', 'push-to-checkout') which are always executed in $GIT_DIR. +Environment variables, such as `GIT_DIR`, `GIT_WORK_TREE`, etc., are exported +so that Git commands run by the hook can correctly locate the repository. If +your hook needs to invoke Git commands in a foreign repository or in a +different working tree of the same repository, then it should clear these +environment variables so they do not interfere with Git operations at the +foreign location. For example: + +------------ +local_desc=$(git describe) +foreign_desc=$(unset $(git rev-parse --local-env-vars); git -C ../foreign-repo describe) +------------ + Hooks can get their arguments via the environment, command-line arguments, and stdin. See the documentation for each hook below for details. @@ -68,7 +80,7 @@ If it exits with non-zero status, then the working tree will not be committed after applying the patch. It can be used to inspect the current working tree and refuse to -make a commit if it does not pass certain test. +make a commit if it does not pass certain tests. The default 'pre-applypatch' hook, when enabled, runs the 'pre-commit' hook, if the latter is enabled. @@ -145,7 +157,7 @@ If the exit status is non-zero, `git commit` will abort. The purpose of the hook is to edit the message file in place, and it is not suppressed by the `--no-verify` option. A non-zero exit means a failure of the hook and aborts the commit. It should not -be used as replacement for pre-commit hook. +be used as a replacement for the pre-commit hook. The sample `prepare-commit-msg` hook that comes with Git removes the help message found in the commented portion of the commit template. @@ -231,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: @@ -239,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. @@ -263,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 @@ -333,7 +345,7 @@ for the user. The default 'update' hook, when enabled--and with `hooks.allowunannotated` config option unset or set to false--prevents -unannotated tags to be pushed. +unannotated tags from being pushed. [[proc-receive]] proc-receive @@ -367,12 +379,12 @@ following example for the protocol, the letter 'S' stands for S: ... ... S: flush-pkt - # Receive result from the hook. + # Receive results from the hook. # OK, run this command successfully. H: PKT-LINE(ok <ref>) # NO, I reject it. H: PKT-LINE(ng <ref> <reason>) - # Fall through, let 'receive-pack' to execute it. + # Fall through, let 'receive-pack' execute it. H: PKT-LINE(ok <ref>) H: PKT-LINE(option fall-through) # OK, but has an alternate reference. The alternate reference name @@ -491,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`. @@ -583,10 +595,51 @@ processed by rebase. sendemail-validate ~~~~~~~~~~~~~~~~~~ -This hook is invoked by linkgit:git-send-email[1]. It takes a single parameter, -the name of the file that holds the e-mail to be sent. Exiting with a -non-zero status causes `git send-email` to abort before sending any -e-mails. +This hook is invoked by linkgit:git-send-email[1]. + +It takes these command line arguments. They are, +1. the name of the file which holds the contents of the email to be sent. +2. The name of the file which holds the SMTP headers of the email. + +The SMTP headers are passed in the exact same way as they are passed to the +user's Mail Transport Agent (MTA). In effect, the email given to the user's +MTA, is the contents of $2 followed by the contents of $1. + +An example of a few common headers is shown below. Take notice of the +capitalization and multi-line tab structure. + + From: Example <from@example.com> + To: to@example.com + Cc: cc@example.com, + A <author@example.com>, + One <one@example.com>, + two@example.com + Subject: PATCH-STRING + +Exiting with a non-zero status causes `git send-email` to abort +before sending any e-mails. + +The following environment variables are set when executing the hook. + +`GIT_SENDEMAIL_FILE_COUNTER`:: + A 1-based counter incremented by one for every file holding an e-mail + to be sent (excluding any FIFOs). This counter does not follow the + patch series counter scheme. It will always start at 1 and will end at + GIT_SENDEMAIL_FILE_TOTAL. + +`GIT_SENDEMAIL_FILE_TOTAL`:: + The total number of files that will be sent (excluding any FIFOs). This + counter does not follow the patch series counter scheme. It will always + be equal to the number of files being sent, whether there is a cover + letter or not. + +These variables may for instance be used to validate patch series. + +The sample `sendemail-validate` hook that comes with Git checks that all sent +patches (excluding the cover letter) can be applied on top of the upstream +repository default branch without conflicts. Some placeholders are left for +additional validation steps to be performed after all patches of a given series +have been applied. fsmonitor-watchman ~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index f2738b1..5e0964e 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -88,7 +88,7 @@ PATTERN FORMAT Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". - - The slash '/' is used as the directory separator. Separators may + - The slash "`/`" is used as the directory separator. Separators may occur at the beginning, middle or end of the `.gitignore` search pattern. - If there is a separator at the beginning or middle (or both) of the @@ -146,7 +146,9 @@ The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked. To stop tracking a file that is currently tracked, use -'git rm --cached'. +'git rm --cached' to remove the file from the index. The filename +can then be added to the `.gitignore` file to stop the file from +being reintroduced in later commits. Git does not follow symbolic links when accessing a `.gitignore` file in the working tree. This keeps behavior consistent when the file is @@ -172,10 +174,10 @@ EXAMPLES is not relevant if there is already a middle slash in the pattern. - - The pattern "foo/*", matches "foo/test.json" - (a regular file), "foo/bar" (a directory), but it does not match - "foo/bar/hello.c" (a regular file), as the asterisk in the - pattern does not match "bar/hello.c" which has a slash in it. + - The pattern `foo/*`, matches `foo/test.json` + (a regular file), `foo/bar` (a directory), but it does not match + `foo/bar/hello.c` (a regular file), as the asterisk in the + pattern does not match `bar/hello.c` which has a slash in it. -------------------------------------------------------------- $ git status diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index d50e9ed..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 ----------- @@ -26,7 +26,7 @@ changes each commit introduces are shown. Finally, it supports some gitk-specific options. gitk generally only understands options with arguments in the -'sticked' form (see linkgit:gitcli[7]) due to limitations in the +'stuck' form (see linkgit:gitcli[7]) due to limitations in the command-line parser. rev-list options and arguments @@ -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/gitmodules.txt b/Documentation/gitmodules.txt index dcee09b..d9bec8b 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -43,9 +43,9 @@ submodule.<name>.update:: command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', - 'merge' or 'none'. See description of 'update' command in - linkgit:git-submodule[1] for their meaning. For security - reasons, the '!command' form is not accepted here. + 'merge' or 'none', but not '!command' (for security reasons). + See the description of the 'update' command in + linkgit:git-submodule[1] for more details. submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt index 9dfade9..2cf7735 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -1,8 +1,20 @@ -Git Protocol Capabilities -========================= +gitprotocol-capabilities(5) +=========================== + +NAME +---- +gitprotocol-capabilities - Protocol v0 and v1 capabilities + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- NOTE: this document describes capabilities for versions 0 and 1 of the pack -protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2] +protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5] doc. Servers SHOULD support all capabilities defined in this document. @@ -18,7 +30,7 @@ to be in effect. The client MUST NOT ask for capabilities the server did not say it supports. Server MUST diagnose and abort if capabilities it does not understand -was sent. Server MUST NOT ignore capabilities that client requested +were sent. Server MUST NOT ignore capabilities that client requested and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand. @@ -49,8 +61,8 @@ complete cut across the DAG, or the client has said "done". Without multi_ack, a client sends have lines in --date-order until the server has found a common base. That means the client will send have lines that are already known by the server to be common, because -they overlap in time with another branch that the server hasn't found -a common base on yet. +they overlap in time with another branch on which the server hasn't found +a common base yet. For example suppose the client has commits in caps that the server doesn't and the server has commits in lower case that the client @@ -76,8 +88,8 @@ interleaved with S-R-Q. multi_ack_detailed ------------------ -This is an extension of multi_ack that permits client to better -understand the server's in-memory state. See pack-protocol.txt, +This is an extension of multi_ack that permits the client to better +understand the server's in-memory state. See linkgit:gitprotocol-pack[5], section "Packfile Negotiation" for more information. no-done @@ -123,7 +135,7 @@ to disable the feature in a backwards-compatible manner. side-band, side-band-64k ------------------------ -This capability means that server can send, and client understand multiplexed +This capability means that the server can send, and the client can understand, multiplexed progress reports and error info interleaved with the packfile itself. These two options are mutually exclusive. A modern client always @@ -151,14 +163,14 @@ Further, with side-band and its up to 1000-byte messages, it's actually same deal, you have up to 65519 bytes of data and 1 byte for the stream code. -The client MUST send only maximum of one of "side-band" and "side- -band-64k". Server MUST diagnose it as an error if client requests +The client MUST send only one of "side-band" and "side- +band-64k". The server MUST diagnose it as an error if client requests both. ofs-delta --------- -Server can send, and client understand PACKv2 with delta referring to +The server can send, and the client can understand, PACKv2 with delta referring to its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile. @@ -240,7 +252,7 @@ the current shallow boundary, instead of the depth from remote refs. no-progress ----------- -The client was started with "git clone -q" or something, and doesn't +The client was started with "git clone -q" or something similar, and doesn't want that side band 2. Basically the client just says "I do not wish to receive stream 2 on sideband, so do not send it to me, and if you did, I will drop it on the floor anyway". However, the sideband @@ -261,7 +273,7 @@ request include-tag only has to do with the client's desires for tag data, whether or not a server had advertised objects in the refs/tags/* namespace. -Servers MUST pack the tags if their referrant is packed and the client +Servers MUST pack the tags if their referent is packed and the client has requested include-tags. Clients MUST be prepared for the case where a server has ignored @@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server will respond with whether the packfile unpacked successfully and if each reference was updated successfully. If any of those were not -successful, it will send back an error message. See pack-protocol.txt +successful, it will send back an error message. See linkgit:gitprotocol-pack[5] for example messages. report-status-v2 @@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by the "proc-receive" hook. The "proc-receive" hook may handle a command for a pseudo-reference which may create or update a reference with different name, new-oid, and old-oid. While the capability -'report-status' cannot report for such case. See pack-protocol.txt +'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5] for details. delete-refs @@ -366,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 @@ -376,5 +388,9 @@ the server as well. Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see -link:api-trace2.html[api-trace2] for details), but this may change and users of -the session ID should not rely on this fact. +link:technical/api-trace2.html[api-trace2] for details), but this may change +and users of the session ID should not rely on this fact. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt index ecedb34..cdc9d6e 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/gitprotocol-common.txt @@ -1,5 +1,20 @@ -Documentation Common to Pack and Http Protocols -=============================================== +gitprotocol-common(5) +===================== + +NAME +---- +gitprotocol-common - Things common to various protocols + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- + +This document defines things common to various over-the-wire +protocols and file formats used in Git. ABNF Notation ------------- @@ -97,3 +112,7 @@ Examples (as C-style strings): "000bfoobar\n" "foobar\n" "0004" "" ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt index cc5126c..ec40a55 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/gitprotocol-http.txt @@ -1,5 +1,19 @@ -HTTP transfer protocols -======================= +gitprotocol-http(5) +=================== + +NAME +---- +gitprotocol-http - Git HTTP-based protocols + + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + + +DESCRIPTION +----------- Git supports two HTTP based transfer protocols. A "dumb" protocol which requires only a standard HTTP server on the server end of the @@ -28,7 +42,7 @@ both the "smart" and "dumb" HTTP protocols used by Git operate by appending additional path components onto the end of the user supplied `$GIT_URL` string. -An example of a dumb client requesting for a loose object: +An example of a dumb client requesting a loose object: $GIT_URL: http://example.com:8080/git/repo.git URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355 @@ -222,7 +236,7 @@ smart server reply: S: 0000 The client may send Extra Parameters (see -Documentation/technical/pack-protocol.txt) as a colon-separated string +linkgit:gitprotocol-pack[5]) as a colon-separated string in the Git-Protocol HTTP header. Uses the `--http-backend-info-refs` option to @@ -365,7 +379,7 @@ C: Place any object seen into set `advertised`. C: Build an empty set, `common`, to hold the objects that are later determined to be on both ends. -C: Build a set, `want`, of the objects from `advertised` the client +C: Build a set, `want`, of the objects from `advertised` that the client wants to fetch, based on what it saw during ref discovery. C: Start a queue, `c_pending`, ordered by commit time (popping newest @@ -377,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 @@ -409,7 +423,7 @@ multiple commands. Object names MUST be given using the object format negotiated through the `object-format` capability (default SHA-1). The `have` list is created by popping the first 32 commits -from `c_pending`. Less can be supplied if `c_pending` empties. +from `c_pending`. Fewer can be supplied if `c_pending` empties. If the client has sent 256 "have" commits and has not yet received one of those back from `s_common`, or the client has @@ -498,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) @@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id. TODO: Document this further. - -References +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] -link:technical/pack-protocol.html -link:technical/protocol-capabilities.html +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 +-------- + +linkgit:gitprotocol-pack[5] +linkgit:gitprotocol-capabilities[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt index e13a2c0..837b691 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/gitprotocol-pack.txt @@ -1,11 +1,23 @@ -Packfile transfer protocols -=========================== +gitprotocol-pack(5) +=================== + +NAME +---- +gitprotocol-pack - How packs are transferred over-the-wire + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same -protocol to transfer data. http is documented in http-protocol.txt. +protocol to transfer data. http is documented in linkgit:gitprotocol-http[5]. The processes invoked in the canonical Git implementation are 'upload-pack' on the server side and 'fetch-pack' on the client side for fetching data; @@ -18,7 +30,7 @@ pkt-line Format --------------- The descriptions below build on the pkt-line format described in -protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless +linkgit:gitprotocol-common[5]. When the grammar indicates `PKT-LINE(...)`, unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present. @@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is -"version" with a value of '1' or '2'. See protocol-v2.txt for more +"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more information on protocol version 2. Git Transport @@ -125,7 +137,7 @@ an absolute path in the remote filesystem. v ssh user@example.com "git-upload-pack '/project.git'" -In a "user@host:path" format URI, its relative to the user's home +In a "user@host:path" format URI, it's relative to the user's home directory, because the Git client will run: git clone user@example.com:project.git @@ -313,7 +325,7 @@ a positive depth, this step is skipped. If the client has requested a positive depth, the server will compute the set of commits which are no deeper than the desired depth. The set -of commits start at the client's wants. +of commits starts at the client's wants. The server writes 'shallow' lines for each commit whose parents will not be sent as a result. The server writes @@ -455,7 +467,7 @@ Now that the client and server have finished negotiation about what the minimal amount of data that needs to be sent to the client is, the server will construct and send the required data in packfile format. -See pack-format.txt for what the packfile itself actually looks like. +See linkgit:gitformat-pack[5] for what the packfile itself actually looks like. If 'side-band' or 'side-band-64k' capabilities have been specified by the client, the server will send the packfile data multiplexed. @@ -707,3 +719,7 @@ An example client/server communication might look like this: S: 0018ok refs/heads/debug\n S: 002ang refs/heads/master non-fast-forward\n ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt index 8a877d2..414bc62 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -1,5 +1,17 @@ -Git Wire Protocol, Version 2 -============================ +gitprotocol-v2(5) +================= + +NAME +---- +gitprotocol-v2 - Git Wire Protocol, Version 2 + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways: @@ -17,7 +29,7 @@ protocol. Protocol v2 will improve upon v1 in the following ways: semantics the http remote helper can simply act as a proxy In protocol v2 communication is command oriented. When first contacting a -server a list of capabilities will advertised. Some of these capabilities +server a list of capabilities will be advertised. Some of these capabilities will be commands which a client can request be executed. Once a command has completed, a client can reuse the connection and request that other commands be executed. @@ -26,8 +38,7 @@ Packet-Line Framing ------------------- All communication is done using packet-line framing, just as in v1. See -`Documentation/technical/pack-protocol.txt` and -`Documentation/technical/protocol-common.txt` for more information. +linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information. In protocol v2 these special packets will have the following semantics: @@ -42,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in `pack-protocol.txt` and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -66,7 +77,7 @@ HTTP Transport ~~~~~~~~~~~~~~ When using the http:// or https:// transport a client makes a "smart" -info/refs request as described in `http-protocol.txt` and requests that +info/refs request as described in linkgit:gitprotocol-http[5] and requests that v2 be used by supplying "version=2" in the `Git-Protocol` header. C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 @@ -188,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: @@ -234,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: @@ -335,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: @@ -350,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 @@ -523,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 @@ -533,8 +546,8 @@ the server as well. Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see -link:api-trace2.html[api-trace2] for details), but this may change and users of -the session ID should not rely on this fact. +link:technical/api-trace2.html[api-trace2] for details), but this may change +and users of the session ID should not rely on this fact. object-info ~~~~~~~~~~~ @@ -566,3 +579,208 @@ and associated requested information, each separated by a single space. attr = "size" obj-info = obj-id SP obj-size + +bundle-uri +~~~~~~~~~~ + +If the 'bundle-uri' capability is advertised, the server supports the +`bundle-uri' command. + +The capability is currently advertised with no value (i.e. not +"bundle-uri=somevalue"), a value may be added in the future for +supporting command-wide extensions. Clients MUST ignore any unknown +capability values and proceed with the 'bundle-uri` dialog they +support. + +The 'bundle-uri' command is intended to be issued before `fetch` to +get URIs to bundle files (see linkgit:git-bundle[1]) to "seed" and +inform the subsequent `fetch` command. + +The client CAN issue `bundle-uri` before or after any other valid +command. To be useful to clients it's expected that it'll be issued +after an `ls-refs` and before `fetch`, but CAN be issued at any time +in the dialog. + +DISCUSSION of bundle-uri +^^^^^^^^^^^^^^^^^^^^^^^^ + +The intent of the feature is optimize for server resource consumption +in the common case by changing the common case of fetching a very +large PACK during linkgit:git-clone[1] into a smaller incremental +fetch. + +It also allows servers to achieve better caching in combination with +an `uploadpack.packObjectsHook` (see linkgit:git-config[1]). + +By having new clones or fetches be a more predictable and common +negotiation against the tips of recently produces *.bundle file(s). +Servers might even pre-generate the results of such negotiations for +the `uploadpack.packObjectsHook` as new pushes come in. + +One way that servers could take advantage of these bundles is that the +server would anticipate that fresh clones will download a known bundle, +followed by catching up to the current state of the repository using ref +tips found in that bundle (or bundles). + +PROTOCOL for bundle-uri +^^^^^^^^^^^^^^^^^^^^^^^ + +A `bundle-uri` request takes no arguments, and as noted above does not +currently advertise a capability value. Both may be added in the +future. + +When the client issues a `command=bundle-uri` request, the response is a +list of key-value pairs provided as packet lines with value +`<key>=<value>`. Each `<key>` should be interpreted as a config key from +the `bundle.*` namespace to construct a list of bundles. These keys are +grouped by a `bundle.<id>.` subsection, where each key corresponding to a +given `<id>` contributes attributes to the bundle defined by that `<id>`. +See linkgit:git-config[1] for the specific details of these keys and how +the Git client will interpret their values. + +Clients MUST parse the line according to the above format, lines that do +not conform to the format SHOULD be discarded. The user MAY be warned in +such a case. + +bundle-uri CLIENT AND SERVER EXPECTATIONS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +URI CONTENTS:: +The content at the advertised URIs MUST be one of two types. ++ +The advertised URI may contain a bundle file that `git bundle verify` +would accept. I.e. they MUST contain one or more reference tips for +use by the client, MUST indicate prerequisites (in any) with standard +"-" prefixes, and MUST indicate their "object-format", if +applicable. ++ +The advertised URI may alternatively contain a plaintext file that `git +config --list` would accept (with the `--file` option). The key-value +pairs in this list are in the `bundle.*` namespace (see +linkgit:git-config[1]). + +bundle-uri CLIENT ERROR RECOVERY:: +A client MUST above all gracefully degrade on errors, whether that +error is because of bad missing/data in the bundle URI(s), because +that client is too dumb to e.g. understand and fully parse out bundle +headers and their prerequisite relationships, or something else. ++ +Server operators should feel confident in turning on "bundle-uri" and +not worry if e.g. their CDN goes down that clones or fetches will run +into hard failures. Even if the server bundle(s) are +incomplete, or bad in some way the client should still end up with a +functioning repository, just as if it had chosen not to use this +protocol extension. ++ +All subsequent discussion on client and server interaction MUST keep +this in mind. + +bundle-uri SERVER TO CLIENT:: +The ordering of the returned bundle uris is not significant. Clients +MUST parse their headers to discover their contained OIDS and +prerequisites. A client MUST consider the content of the bundle(s) +themselves and their header as the ultimate source of truth. ++ +A server MAY even return bundle(s) that don't have any direct +relationship to the repository being cloned (either through accident, +or intentional "clever" configuration), and expect a client to sort +out what data they'd like from the bundle(s), if any. + +bundle-uri CLIENT TO SERVER:: +The client SHOULD provide reference tips found in the bundle header(s) +as 'have' lines in any subsequent `fetch` request. A client MAY also +ignore the bundle(s) entirely if doing so is deemed worse for some +reason, e.g. if the bundles can't be downloaded, it doesn't like the +tips it finds etc. + +WHEN ADVERTISED BUNDLE(S) REQUIRE NO FURTHER NEGOTIATION:: +If after issuing `bundle-uri` and `ls-refs`, and getting the header(s) +of the bundle(s) the client finds that the ref tips it wants can be +retrieved entirely from advertised bundle(s), the client MAY disconnect +from the Git server. The results of such a 'clone' or 'fetch' should be +indistinguishable from the state attained without using bundle-uri. + +EARLY CLIENT DISCONNECTIONS AND ERROR RECOVERY:: +A client MAY perform an early disconnect while still downloading the +bundle(s) (having streamed and parsed their headers). In such a case +the client MUST gracefully recover from any errors related to +finishing the download and validation of the bundle(s). ++ +I.e. a client might need to re-connect and issue a 'fetch' command, +and possibly fall back to not making use of 'bundle-uri' at all. ++ +This "MAY" behavior is specified as such (and not a "SHOULD") on the +assumption that a server advertising bundle uris is more likely than +not to be serving up a relatively large repository, and to be pointing +to URIs that have a good chance of being in working order. A client +MAY e.g. look at the payload size of the bundles as a heuristic to see +if an early disconnect is worth it, should falling back on a full +"fetch" dialog be necessary. + +WHEN ADVERTISED BUNDLE(S) REQUIRE FURTHER NEGOTIATION:: +A client SHOULD commence a negotiation of a PACK from the server via +the "fetch" command using the OID tips found in advertised bundles, +even if's still in the process of downloading those bundle(s). ++ +This allows for aggressive early disconnects from any interactive +server dialog. The client blindly trusts that the advertised OID tips +are relevant, and issues them as 'have' lines, it then requests any +tips it would like (usually from the "ls-refs" advertisement) via +'want' lines. The server will then compute a (hopefully small) PACK +with the expected difference between the tips from the bundle(s) and +the data requested. ++ +The only connection the client then needs to keep active is to the +concurrently downloading static bundle(s), when those and the +incremental PACK are retrieved they should be inflated and +validated. Any errors at this point should be gracefully recovered +from, see above. + +bundle-uri PROTOCOL FEATURES +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The client constructs a bundle list from the `<key>=<value>` pairs +provided by the server. These pairs are part of the `bundle.*` namespace +as documented in linkgit:git-config[1]. In this section, we discuss some +of these keys and describe the actions the client will do in response to +this information. + +In particular, the `bundle.version` key specifies an integer value. The +only accepted value at the moment is `1`, but if the client sees an +unexpected value here then the client MUST ignore the bundle list. + +As long as `bundle.version` is understood, all other unknown keys MAY be +ignored by the client. The server will guarantee compatibility with older +clients, though newer clients may be better able to use the extra keys to +minimize downloads. + +Any backwards-incompatible addition of pre-URI key-value will be +guarded by a new `bundle.version` value or values in 'bundle-uri' +capability advertisement itself, and/or by new future `bundle-uri` +request arguments. + +Some example key-value pairs that are not currently implemented but could +be implemented in the future include: + + * Add a "hash=<val>" or "size=<bytes>" advertise the expected hash or + size of the bundle file. + + * Advertise that one or more bundle files are the same (to e.g. have + clients round-robin or otherwise choose one of N possible files). + + * A "oid=<OID>" shortcut and "prerequisite=<OID>" shortcut. For + expressing the common case of a bundle with one tip and no + prerequisites, or one tip and one prerequisite. ++ +This would allow for optimizing the common case of servers who'd like +to provide one "big bundle" containing only their "main" branch, +and/or incremental updates thereof. ++ +A client receiving such a a response MAY assume that they can skip +retrieving the header from a bundle at the indicated URI, and thus +save themselves and the server(s) the request(s) needed to inspect the +headers of that bundle or bundles. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 6f1e269..d0be008 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -168,6 +168,9 @@ Supported commands: 'list', 'import'. Can guarantee that when a clone is requested, the received pack is self contained and is connected. +'get':: + Can use the 'get' command to download a file from a given URI. + If a helper advertises 'connect', Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the 'connect' command under COMMANDS). @@ -418,6 +421,12 @@ Supported if the helper has the "connect" capability. + Supported if the helper has the "stateless-connect" capability. +'get' <uri> <path>:: + Downloads the file from the given `<uri>` to the given `<path>`. If + `<path>.temp` exists, then Git assumes that the `.temp` file is a + partial download from a previous attempt and will resume the + download from that position. + If a fatal error occurs, the program writes the error message to stderr and exits. The caller should expect that a suitable error message has been printed if the child closes the connection without @@ -470,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". @@ -517,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. @@ -533,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 941858a..f7b5a25 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -78,7 +78,7 @@ Submodule operations can be configured using the following mechanisms * The command line for those commands that support taking submodules as part of their pathspecs. Most commands have a boolean flag - `--recurse-submodules` which specify whether to recurse into submodules. + `--recurse-submodules` which specifies whether to recurse into submodules. Examples are `grep` and `checkout`. Some commands take enums, such as `fetch` and `push`, where you can specify how submodules are affected. @@ -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 @@ -192,7 +192,7 @@ For example: [submodule "baz"] url = https://example.org/baz -In the above config only the submodule 'bar' and 'baz' are active, +In the above config only the submodules 'bar' and 'baz' are active, 'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because (1) takes precedence over (3) @@ -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" @@ -274,7 +274,7 @@ will not be checked out by default; you can instruct `clone` to recurse into submodules. The `init` and `update` subcommands of `git submodule` will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set `submodule.recurse` to have -`checkout` recursing into submodules (note that `submodule.recurse` also +`checkout` recurse into submodules (note that `submodule.recurse` also affects other Git commands, see linkgit:git-config[1] for a complete list). diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 0e0b863..4759408 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -49,7 +49,7 @@ $ git config --global user.email you@yourdomain.example.com Importing a new project ----------------------- -Assume you have a tarball project.tar.gz with your initial work. You +Assume you have a tarball `project.tar.gz` with your initial work. You can place it under Git revision control as follows. ------------------------------------------------ @@ -65,10 +65,10 @@ Initialized empty Git repository in .git/ ------------------------------------------------ You've now initialized the working directory--you may notice a new -directory created, named ".git". +directory created, named `.git`. Next, tell Git to take a snapshot of the contents of all files under the -current directory (note the '.'), with 'git add': +current directory (note the `.`), with `git add`: ------------------------------------------------ $ git add . @@ -76,7 +76,7 @@ $ git add . This snapshot is now stored in a temporary staging area which Git calls the "index". You can permanently store the contents of the index in the -repository with 'git commit': +repository with `git commit`: ------------------------------------------------ $ git commit @@ -95,21 +95,20 @@ $ git add file1 file2 file3 ------------------------------------------------ You are now ready to commit. You can see what is about to be committed -using 'git diff' with the --cached option: +using `git diff` with the `--cached` option: ------------------------------------------------ $ git diff --cached ------------------------------------------------ -(Without --cached, 'git diff' will show you any changes that +(Without `--cached`, `git diff` will show you any changes that you've made but not yet added to the index.) You can also get a brief -summary of the situation with 'git status': +summary of the situation with `git status`: ------------------------------------------------ $ git status On branch master Changes to be committed: -Your branch is up to date with 'origin/master'. (use "git restore --staged <file>..." to unstage) modified: file1 @@ -128,7 +127,7 @@ $ git commit This will again prompt you for a message describing the change, and then record a new version of the project. -Alternatively, instead of running 'git add' beforehand, you can use +Alternatively, instead of running `git add` beforehand, you can use ------------------------------------------------ $ git commit -a @@ -138,10 +137,10 @@ which will automatically notice any modified (but not new) files, add them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to -begin the commit message with a single short (less than 50 character) -line summarizing the change, followed by a blank line and then a more -thorough description. The text up to the first blank line in a commit -message is treated as the commit title, and that title is used +begin the commit message with a single short (no more than 50 +characters) line summarizing the change, followed by a blank line and +then a more thorough description. The text up to the first blank line in +a commit message is treated as the commit title, and that title is used throughout Git. For example, linkgit:git-format-patch[1] turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body. @@ -151,7 +150,7 @@ Git tracks content not files Many revision control systems provide an `add` command that tells the system to start tracking changes to a new file. Git's `add` command -does something simpler and more powerful: 'git add' is used both for new +does something simpler and more powerful: `git add` is used both for new and newly modified files, and in both cases it takes a snapshot of the given files and stages that content in the index, ready for inclusion in the next commit. @@ -182,7 +181,7 @@ Managing branches ----------------- A single Git repository can maintain multiple branches of -development. To create a new branch named "experimental", use +development. To create a new branch named `experimental`, use ------------------------------------------------ $ git branch experimental @@ -201,8 +200,8 @@ you'll get a list of all existing branches: * master ------------------------------------------------ -The "experimental" branch is the one you just created, and the -"master" branch is a default branch that was created for you +The `experimental` branch is the one you just created, and the +`master` branch is a default branch that was created for you automatically. The asterisk marks the branch you are currently on; type @@ -210,8 +209,8 @@ type $ git switch experimental ------------------------------------------------ -to switch to the experimental branch. Now edit a file, commit the -change, and switch back to the master branch: +to switch to the `experimental` branch. Now edit a file, commit the +change, and switch back to the `master` branch: ------------------------------------------------ (edit file) @@ -220,9 +219,9 @@ $ git switch master ------------------------------------------------ Check that the change you made is no longer visible, since it was -made on the experimental branch and you're back on the master branch. +made on the `experimental` branch and you're back on the `master` branch. -You can make a different change on the master branch: +You can make a different change on the `master` branch: ------------------------------------------------ (edit file) @@ -230,7 +229,7 @@ $ git commit -a ------------------------------------------------ at this point the two branches have diverged, with different changes -made in each. To merge the changes made in experimental into master, run +made in each. To merge the changes made in `experimental` into `master`, run ------------------------------------------------ $ git merge experimental @@ -258,16 +257,16 @@ $ gitk will show a nice graphical representation of the resulting history. -At this point you could delete the experimental branch with +At this point you could delete the `experimental` branch with ------------------------------------------------ $ git branch -d experimental ------------------------------------------------ -This command ensures that the changes in the experimental branch are +This command ensures that the changes in the `experimental` branch are already in the current branch. -If you develop on a branch crazy-idea, then regret it, you can always +If you develop on a branch `crazy-idea`, then regret it, you can always delete the branch with ------------------------------------- @@ -281,7 +280,7 @@ Using Git for collaboration --------------------------- Suppose that Alice has started a new project with a Git repository in -/home/alice/project, and that Bob, who has a home directory on the +`/home/alice/project`, and that Bob, who has a home directory on the same machine, wants to contribute. Bob begins with: @@ -290,7 +289,7 @@ Bob begins with: bob$ git clone /home/alice/project myrepo ------------------------------------------------ -This creates a new directory "myrepo" containing a clone of Alice's +This creates a new directory `myrepo` containing a clone of Alice's repository. The clone is on an equal footing with the original project, possessing its own copy of the original project's history. @@ -303,31 +302,31 @@ bob$ git commit -a ------------------------------------------------ When he's ready, he tells Alice to pull changes from the repository -at /home/bob/myrepo. She does this with: +at `/home/bob/myrepo`. She does this with: ------------------------------------------------ alice$ cd /home/alice/project alice$ git pull /home/bob/myrepo master ------------------------------------------------ -This merges the changes from Bob's "master" branch into Alice's +This merges the changes from Bob's `master` branch into Alice's current branch. If Alice has made her own changes in the meantime, then she may need to manually fix any conflicts. -The "pull" command thus performs two operations: it fetches changes +The `pull` command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. Note that in general, Alice would want her local changes committed before -initiating this "pull". If Bob's work conflicts with what Alice did since +initiating this `pull`. If Bob's work conflicts with what Alice did since their histories forked, Alice will use her working tree and the index to resolve conflicts, and existing local changes will interfere with the conflict resolution process (Git will still perform the fetch but will refuse to merge -- Alice will have to get rid of her local changes in some way and pull again when this happens). -Alice can peek at what Bob did without merging first, using the "fetch" +Alice can peek at what Bob did without merging first, using the `fetch` command; this allows Alice to inspect what Bob did, using a special -symbol "FETCH_HEAD", in order to determine if he has anything worth +symbol `FETCH_HEAD`, in order to determine if he has anything worth pulling, like this: ------------------------------------------------ @@ -336,10 +335,10 @@ alice$ git log -p HEAD..FETCH_HEAD ------------------------------------------------ This operation is safe even if Alice has uncommitted local changes. -The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable -from the FETCH_HEAD but exclude anything that is reachable from HEAD". -Alice already knows everything that leads to her current state (HEAD), -and reviews what Bob has in his state (FETCH_HEAD) that she has not +The range notation `HEAD..FETCH_HEAD` means "show everything that is reachable +from the `FETCH_HEAD` but exclude anything that is reachable from `HEAD`". +Alice already knows everything that leads to her current state (`HEAD`), +and reviews what Bob has in his state (`FETCH_HEAD`) that she has not seen with this command. If Alice wants to visualize what Bob did since their histories forked @@ -349,7 +348,7 @@ she can issue the following command: $ gitk HEAD..FETCH_HEAD ------------------------------------------------ -This uses the same two-dot range notation we saw earlier with 'git log'. +This uses the same two-dot range notation we saw earlier with `git log`. Alice may want to view what both of them did since they forked. She can use three-dot form instead of the two-dot form: @@ -361,13 +360,13 @@ $ gitk HEAD...FETCH_HEAD This means "show everything that is reachable from either one, but exclude anything that is reachable from both of them". -Please note that these range notation can be used with both gitk -and "git log". +Please note that these range notation can be used with both `gitk` +and `git log`. After inspecting what Bob did, if there is nothing urgent, Alice may decide to continue working without pulling from Bob. If Bob's history does have something Alice would immediately need, Alice may choose to -stash her work-in-progress first, do a "pull", and then finally unstash +stash her work-in-progress first, do a `pull`, and then finally unstash her work-in-progress on top of the resulting history. When you are working in a small closely knit group, it is not @@ -379,8 +378,8 @@ it easier: alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, Alice can perform the first part of the "pull" operation -alone using the 'git fetch' command without merging them with her own +With this, Alice can perform the first part of the `pull` operation +alone using the `git fetch` command without merging them with her own branch, using: ------------------------------------- @@ -388,7 +387,7 @@ alice$ git fetch bob ------------------------------------- Unlike the longhand form, when Alice fetches from Bob using a -remote repository shorthand set up with 'git remote', what was +remote repository shorthand set up with `git remote`, what was fetched is stored in a remote-tracking branch, in this case `bob/master`. So after this: @@ -397,10 +396,10 @@ alice$ git log -p master..bob/master ------------------------------------- shows a list of all the changes that Bob made since he branched from -Alice's master branch. +Alice's `master` branch. After examining those changes, Alice -could merge the changes into her master branch: +could merge the changes into her `master` branch: ------------------------------------- alice$ git merge bob/master @@ -432,12 +431,12 @@ bob$ git config --get remote.origin.url /home/alice/project ------------------------------------- -(The complete configuration created by 'git clone' is visible using +(The complete configuration created by `git clone` is visible using `git config -l`, and the linkgit:git-config[1] man page explains the meaning of each option.) -Git also keeps a pristine copy of Alice's master branch under the -name "origin/master": +Git also keeps a pristine copy of Alice's `master` branch under the +name `origin/master`: ------------------------------------- bob$ git branch -r @@ -462,8 +461,8 @@ Exploring history ----------------- Git history is represented as a series of interrelated commits. We -have already seen that the 'git log' command can list those commits. -Note that first line of each git log entry also gives a name for the +have already seen that the `git log` command can list those commits. +Note that first line of each `git log` entry also gives a name for the commit: ------------------------------------- @@ -475,7 +474,7 @@ Date: Tue May 16 17:18:22 2006 -0700 merge-base: Clarify the comments on post processing. ------------------------------------- -We can give this name to 'git show' to see the details about this +We can give this name to `git show` to see the details about this commit. ------------------------------------- @@ -514,7 +513,7 @@ You can also give commits names of your own; after running $ git tag v2.5 1b2e1d63ff ------------------------------------- -you can refer to 1b2e1d63ff by the name "v2.5". If you intend to +you can refer to `1b2e1d63ff` by the name `v2.5`. If you intend to share this name with other people (for example, to identify a release version), you should create a "tag" object, and perhaps sign it; see linkgit:git-tag[1] for details. @@ -533,22 +532,22 @@ $ git reset --hard HEAD^ # reset your current branch and working Be careful with that last command: in addition to losing any changes in the working directory, it will also remove all later commits from this branch. If this branch is the only branch containing those -commits, they will be lost. Also, don't use 'git reset' on a +commits, they will be lost. Also, don't use `git reset` on a publicly-visible branch that other developers pull from, as it will force needless merges on other developers to clean up the history. -If you need to undo changes that you have pushed, use 'git revert' +If you need to undo changes that you have pushed, use `git revert` instead. -The 'git grep' command can search for strings in any version of your +The `git grep` command can search for strings in any version of your project, so ------------------------------------- $ git grep "hello" v2.5 ------------------------------------- -searches for all occurrences of "hello" in v2.5. +searches for all occurrences of "hello" in `v2.5`. -If you leave out the commit name, 'git grep' will search any of the +If you leave out the commit name, `git grep` will search any of the files it manages in your current directory. So ------------------------------------- @@ -558,7 +557,7 @@ $ git grep "hello" is a quick way to search just the files that are tracked by Git. Many Git commands also take sets of commits, which can be specified -in a number of ways. Here are some examples with 'git log': +in a number of ways. Here are some examples with `git log`: ------------------------------------- $ git log v2.5..v2.6 # commits between v2.5 and v2.6 @@ -568,16 +567,16 @@ $ git log v2.5.. Makefile # commits since v2.5 which modify # Makefile ------------------------------------- -You can also give 'git log' a "range" of commits where the first is not +You can also give `git log` a "range" of commits where the first is not necessarily an ancestor of the second; for example, if the tips of -the branches "stable" and "master" diverged from a common +the branches `stable` and `master` diverged from a common commit some time ago, then ------------------------------------- $ git log stable..master ------------------------------------- -will list commits made in the master branch but not in the +will list commits made in the `master` branch but not in the stable branch, while ------------------------------------- @@ -585,15 +584,15 @@ $ git log master..stable ------------------------------------- will show the list of commits made on the stable branch but not -the master branch. +the `master` branch. -The 'git log' command has a weakness: it must present commits in a +The `git log` command has a weakness: it must present commits in a list. When the history has lines of development that diverged and -then merged back together, the order in which 'git log' presents +then merged back together, the order in which `git log` presents those commits is meaningless. Most projects with multiple contributors (such as the Linux kernel, -or Git itself) have frequent merges, and 'gitk' does a better job of +or Git itself) have frequent merges, and `gitk` does a better job of visualizing their history. For example, ------------------------------------- @@ -601,7 +600,7 @@ $ gitk --since="2 weeks ago" drivers/ ------------------------------------- allows you to browse any commits from the last 2 weeks of commits -that modified files under the "drivers" directory. (Note: you can +that modified files under the `drivers` directory. (Note: you can adjust gitk's fonts by holding down the control key while pressing "-" or "+".) @@ -613,7 +612,7 @@ of the file: $ git diff v2.5:Makefile HEAD:Makefile.in ------------------------------------- -You can also use 'git show' to see any such file: +You can also use `git show` to see any such file: ------------------------------------- $ git show v2.5:Makefile @@ -649,7 +648,7 @@ digressions that may be interesting at this point are: * linkgit:git-bisect[1]: When there is a regression in your project, one way to track down the bug is by searching through - the history to find the exact commit that's to blame. Git bisect + the history to find the exact commit that's to blame. `git bisect` can help you perform a binary search for that commit. It is smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches. diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 34b1d6e..8598358 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -53,7 +53,7 @@ following order: `/etc/gitweb-common.conf`), * either per-instance configuration file (defaults to 'gitweb_config.perl' - in the same directory as the installed gitweb), or if it does not exists + in the same directory as the installed gitweb), or if it does not exist then fallback system-wide configuration file (defaults to `/etc/gitweb.conf`). Values obtained in later configuration files override values obtained earlier @@ -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 7cee9d3..56d24a3 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -8,7 +8,7 @@ gitweb - Git web interface (web frontend to Git repositories) SYNOPSIS -------- To get started with gitweb, run linkgit:git-instaweb[1] from a Git repository. -This would configure and start your web server, and run web browser pointing to +This will configure and start your web server, and run a web browser pointing to gitweb. @@ -20,15 +20,15 @@ Gitweb provides a web interface to Git repositories. Its features include: * Browsing every revision of the repository. * Viewing the contents of files in the repository at any revision. * Viewing the revision log of branches, history of files and directories, - see what was changed when, by who. + seeing what was changed, when, and by whom. * Viewing the blame/annotation details of any file (if enabled). * Generating RSS and Atom feeds of commits, for any branch. The feeds are auto-discoverable in modern web browsers. -* Viewing everything that was changed in a revision, and step through +* Viewing everything that was changed in a revision, and stepping through revisions one at a time, viewing the history of the repository. -* Finding commits which commit messages matches given search term. +* 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. @@ -41,9 +41,9 @@ for details. Repositories ~~~~~~~~~~~~ Gitweb can show information from one or more Git repositories. These -repositories have to be all on local filesystem, and have to share common +repositories have to be all on local filesystem, and have to share a common repository root, i.e. be all under a single parent repository (but see also -"Advanced web server setup" section, "Webserver configuration with multiple +the "Advanced web server setup" section, "Webserver configuration with multiple projects' root" subsection). ----------------------------------------------------------------------- @@ -51,7 +51,7 @@ our $projectroot = '/path/to/parent/directory'; ----------------------------------------------------------------------- The default value for `$projectroot` is `/pub/git`. You can change it during -building gitweb via `GITWEB_PROJECTROOT` build configuration variable. +building gitweb via the `GITWEB_PROJECTROOT` build configuration variable. By default all Git repositories under `$projectroot` are visible and available to gitweb. The list of projects is generated by default by scanning the @@ -66,7 +66,7 @@ found at "$projectroot/$repo". Projects list file format ~~~~~~~~~~~~~~~~~~~~~~~~~ -Instead of having gitweb find repositories by scanning filesystem +Instead of having gitweb find repositories by scanning the filesystem starting from $projectroot, you can provide a pre-generated list of visible projects by setting `$projects_list` to point to a plain text file with a list of projects (with some additional info). @@ -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> ----------------------------------------------------------------------- @@ -503,7 +503,7 @@ repositories, you can configure Apache like this: The above configuration expects your public repositories to live under `/pub/git` and will serve them as `http://git.domain.org/dir-under-pub-git`, -both as clonable Git URL and as browseable gitweb interface. If you then +both as clonable Git URL and as browsable gitweb interface. If you then start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` then you can even use the `git://` URL with exactly the same path. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index aa2f41f..d71b199 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -20,7 +20,7 @@ [[def_branch]]branch:: A "branch" is a line of development. The most recent <<def_commit,commit>> on a branch is referred to as the tip of - that branch. The tip of the branch is referenced by a branch + that branch. The tip of the branch is <<def_ref,referenced>> by a branch <<def_head,head>>, which moves forward as additional development is done on the branch. A single Git <<def_repository,repository>> can track an arbitrary number of @@ -75,6 +75,21 @@ state in the Git history, by creating a new commit representing the current state of the <<def_index,index>> and advancing <<def_HEAD,HEAD>> to point at the new commit. +[[def_commit_graph_general]]commit graph concept, representations and usage:: + A synonym for the <<def_DAG,DAG>> structure formed by the commits + in the object database, <<def_ref,referenced>> by branch tips, + using their <<def_chain,chain>> of linked commits. + This structure is the definitive commit graph. The + graph can be represented in other ways, e.g. the + <<def_commit_graph_file,"commit-graph" file>>. + +[[def_commit_graph_file]]commit-graph file:: + The "commit-graph" (normally hyphenated) file is a supplemental + representation of the <<def_commit_graph_general,commit graph>> + which accelerates commit graph walks. The "commit-graph" file is + stored either in the .git/objects/info directory or in the info + directory of an alternate object database. + [[def_commit_object]]commit object:: An <<def_object,object>> which contains the information about a particular <<def_revision,revision>>, such as <<def_parent,parents>>, committer, @@ -83,9 +98,8 @@ to point at the new commit. revision. [[def_commit-ish]]commit-ish (also committish):: - A <<def_commit_object,commit object>> or an - <<def_object,object>> that can be recursively dereferenced to - a commit object. + A <<def_commit_object,commit object>> or an <<def_object,object>> that + can be recursively <<def_dereference,dereferenced>> to a commit object. The following are all commit-ishes: a commit object, a <<def_tag_object,tag object>> that points to a commit @@ -110,6 +124,25 @@ to point at the new commit. dangling object has no references to it from any reference or <<def_object,object>> in the <<def_repository,repository>>. +[[def_dereference]]dereference:: + Referring to a <<def_symref,symbolic ref>>: the action of accessing the + <<def_ref,reference>> pointed at by a symbolic ref. Recursive + dereferencing involves repeating the aforementioned process on the + resulting ref until a non-symbolic reference is found. ++ +Referring to a <<def_tag_object,tag object>>: the action of accessing the +<<def_object,object>> a tag points at. Tags are recursively dereferenced by +repeating the operation on the result object until the result has either a +specified <<def_object_type,object type>> (where applicable) or any non-"tag" +object type. A synonym for "recursive dereference" in the context of tags is +"<<def_peel,peel>>". ++ +Referring to a <<def_commit_object,commit object>>: the action of accessing +the commit's tree object. Commits cannot be dereferenced recursively. ++ +Unless otherwise specified, "dereferencing" as it used in the context of Git +commands or protocols is implicitly recursive. + [[def_detached_HEAD]]detached HEAD:: Normally the <<def_HEAD,HEAD>> stores the name of a <<def_branch,branch>>, and commands that operate on the @@ -169,9 +202,11 @@ 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 enables two otherwise different lines of development to be joined + Grafts enable two otherwise different lines of development to be joined together by recording fake ancestry information for commits. This way you can make Git pretend the set of <<def_parent,parents>> a <<def_commit,commit>> has is different from what was recorded when the commit was @@ -262,7 +297,7 @@ This commit is referred to as a "merge commit", or sometimes just a identified by its <<def_object_name,object name>>. The objects usually live in `$GIT_DIR/objects/`. -[[def_object_identifier]]object identifier:: +[[def_object_identifier]]object identifier (oid):: Synonym for <<def_object_name,object name>>. [[def_object_name]]object name:: @@ -279,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 @@ -429,6 +470,10 @@ exclude;; of the logical predecessor(s) in the line of development, i.e. its parents. +[[def_peel]]peel:: + The action of recursively <<def_dereference,dereferencing>> a + <<def_tag_object,tag object>>. + [[def_pickaxe]]pickaxe:: The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore routines that help select changes that add or delete a given text @@ -493,6 +538,14 @@ exclude;; <<def_tree_object,trees>> to the trees or <<def_blob_object,blobs>> that they contain. +[[def_reachability_bitmap]]reachability bitmaps:: + Reachability bitmaps store information about the + <<def_reachable,reachability>> of a selected set of commits in + a packfile, or a multi-pack index (MIDX), to speed up object search. + The bitmaps are stored in a ".bitmap" file. A repository may have at + most one bitmap file in use. The bitmap file may belong to either one + pack, or the repository's multi-pack index (if it exists). + [[def_rebase]]rebase:: To reapply a series of changes from a <<def_branch,branch>> to a different base, and reset the <<def_head,head>> of that branch @@ -585,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 @@ -597,12 +664,11 @@ The most notable example is `HEAD`. copies of) commit objects of the contained submodules. [[def_symref]]symref:: - Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> - id itself, it is of the format 'ref: refs/some/thing' and when - referenced, it recursively dereferences to this reference. - '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic - references are manipulated with the linkgit:git-symbolic-ref[1] - command. + Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id + itself, it is of the format 'ref: refs/some/thing' and when referenced, + it recursively <<def_dereference,dereferences>> to this reference. + '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references + are manipulated with the linkgit:git-symbolic-ref[1] command. [[def_tag]]tag:: A <<def_ref,ref>> under `refs/tags/` namespace that points to an @@ -638,11 +704,11 @@ The most notable example is `HEAD`. <<def_tree,tree>> is equivalent to a <<def_directory,directory>>. [[def_tree-ish]]tree-ish (also treeish):: - A <<def_tree_object,tree object>> or an <<def_object,object>> - that can be recursively dereferenced to a tree object. - Dereferencing a <<def_commit_object,commit object>> yields the - tree object corresponding to the <<def_revision,revision>>'s - top <<def_directory,directory>>. + A <<def_tree_object,tree object>> or an <<def_object,object>> that can + be recursively <<def_dereference,dereferenced>> to a tree object. + Dereferencing a <<def_commit_object,commit object>> yields the tree + object corresponding to the <<def_revision,revision>>'s top + <<def_directory,directory>>. The following are all tree-ishes: a <<def_commit-ish,commit-ish>>, a tree object, @@ -651,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/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt index 601aae8..b9cb95e 100644 --- a/Documentation/howto/coordinate-embargoed-releases.txt +++ b/Documentation/howto/coordinate-embargoed-releases.txt @@ -1,9 +1,10 @@ Content-type: text/asciidoc -Abstract: When a critical vulnerability is discovered and fixed, we follow this - script to coordinate a public release. +Abstract: When a vulnerability is reported, we follow these guidelines to + assess the vulnerability, create and review a fix, and coordinate embargoed + security releases. How we coordinate embargoed releases -==================================== +------------------------------------ To protect Git users from critical vulnerabilities, we do not just release fixed versions like regular maintenance releases. Instead, we coordinate @@ -11,33 +12,147 @@ releases with packagers, keeping the fixes under an embargo until the release date. That way, users will have a chance to upgrade on that date, no matter what Operating System or distribution they run. -Open a Security Advisory draft ------------------------------- +The `git-security` mailing list +------------------------------- + +Responsible disclosures of vulnerabilities, analysis, proposed fixes as +well as the orchestration of coordinated embargoed releases all happen on the +`git-security` mailing list at <git-security@googlegroups.com>. + +In this context, the term "embargo" refers to the time period that information +about a vulnerability is kept under wraps and only shared on a need-to-know +basis. This is necessary to protect Git's users from bad actors who would +otherwise be made aware of attack vectors that could be exploited. "Lifting the +embargo" refers to publishing the version that fixes the vulnerabilities. + +Audience of the `git-security` mailing list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Anybody may contact the `git-security` mailing list by sending an email +to <git-security@googlegroups.com>, though the archive is closed to the +public and only accessible to subscribed members. + +There are a few dozen subscribed members: core Git developers who are trusted +with addressing vulnerabilities, and stakeholders (i.e. owners of products +affected by security vulnerabilities in Git). + +Most of the discussions revolve around assessing the severity of the reported +issue (including the decision whether the report is security-relevant or can be +redirected to the public mailing list), how to remediate the issue, determining +the timeline of the disclosure as well as aligning priorities and +requirements. -The first step is to https://github.com/git/git/security/advisories/new[open an -advisory]. Technically, it is not necessary, but it is convenient and saves a -bit of hassle. This advisory can also be used to obtain the CVE number and it -will give us a private fork associated with it that can be used to collaborate -on a fix. +Communications +~~~~~~~~~~~~~~ -Release date of the embargoed version -------------------------------------- +If you are a stakeholder, it is a good idea to pay close attention to the +discussions, as pertinent information may be buried in the middle of a lively +conversation that might not look relevant to your interests. For example, the +tentative timeline might be agreed upon in the middle of discussing code +comment formatting in one of the patches and whether or not to combine fixes +for multiple, separate vulnerabilities into the same embargoed release. Most +mail threads are not usually structured specifically to communicate +agreements, assessments or timelines. -If the vulnerability affects Windows users, we want to have our friends over at -Visual Studio on board. This means we need to target a "Patch Tuesday" (i.e. a -second Tuesday of the month), at the minimum three weeks from heads-up to -coordinated release. +Typical timeline +---------------- -If the vulnerability affects the server side, or can benefit from scans on the -server side (i.e. if `git fsck` can detect an attack), it is important to give -all involved Git repository hosting sites enough time to scan all of those -repositories. +- A potential vulnerability is reported to the `git-security` mailing list. + +- The members of the git-security list start a discussion to give an initial + assessment of the severity of the reported potential vulnerability. + We aspire to do so within a few days. + +- After discussion, if consensus is reached that it is not critical enough + to warrant any embargo, the reporter is redirected to the public Git mailing + list. This ends the reporter's interaction with the `git-security` list. + +- If it is deemed critical enough for an embargo, ideas are presented on how to + address the vulnerability. + +- Usually around that time, the Git maintainer or their delegate(s) open a draft + security advisory in the `git/git` repository on GitHub (see below for more + details). + +- Code review can take place in a variety of different locations, + depending on context. These are: patches sent inline on the git-security list, + a private fork on GitHub associated with the draft security advisory, or the + git/cabal repository. + +- Contributors working on a fix should consider beginning by sending + patches to the git-security list (inline with the original thread), since they + are accessible to all subscribers, along with the original reporter. + +- Once the review has settled and everyone involved in the review agrees that + the patches are nearing the finish line, the Git maintainer, and others + determine a release date as well as the release trains that are serviced. The + decision regarding which versions need a backported fix is based on input from + the reporter, the contributor who worked on the patches, and from + stakeholders. Operators of hosting sites who may want to analyze whether the + given issue is exploited via any of the repositories they host, and binary + packagers who want to make sure their product gets patched adequately against + the vulnerability, for example, may want to give their input at this stage. + +- While the Git community does its best to accommodate the specific timeline + requests of the various binary packagers, the nature of the issue may preclude + a prolonged release schedule. For fixes deemed urgent, it may be in the best + interest of the Git users community to shorten the disclosure and release + timeline, and packagers may need to adapt accordingly. + +- Subsequently, branches with the fixes are pushed to the git/cabal repository. + +- The tags are created by the Git maintainer and pushed to the same repository. + +- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepare the + corresponding release artifacts, based on the tags created that have been + prepared by the Git maintainer. + +- The release artifacts prepared by various binary packagers can be + made available to stakeholders under embargo via a mail to the + `git-security` list. + +- Less than a week before the release, a mail with the relevant information is + sent to <distros@vs.openwall.org> (see below), a list used to pre-announce + embargoed releases of open source projects to the stakeholders of all major + distributions of Linux as well as other OSes. + +- Public communication is then prepared in advance of the release date. This + includes blog posts and mails to the Git and Git for Windows mailing lists. + +- On the day of the release, at around 10am Pacific Time, the Git maintainer + pushes the tag and the `master` branch to the public repository, then sends + out an announcement mail. + +- Once the tag is pushed, the Git for Windows maintainer publishes the + corresponding tag and creates a GitHub Release with the associated release + artifacts (Git for Windows installer, Portable Git, MinGit, etc). + +- Git for Windows release is then announced via a mail to the public Git and + Git for Windows mailing lists as well as via a tweet. + +- Ditto for distribution packagers for Linux and other platforms: + their releases are announced via their preferred channels. + +- A mail to <oss-security@lists.openwall.org> (see below for details) is sent + as a follow-up to the <distros@vs.openwall.org> one, describing the + vulnerability in detail, often including a proof of concept of an exploit. + +Note: The Git project makes no guarantees about timelines, but aims to keep +embargoes reasonably short in the interest of keeping Git's users safe. + +Opening a Security Advisory draft +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first step is to https://github.com/git/git/security/advisories/new[open +an advisory]. Technically, this is not necessary. However, it is the most +convenient way to obtain the CVE number and it gives us a private repository +associated with it that can be used to collaborate on a fix. Notifying the Linux distributions ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At most two weeks before release date, we need to send a notification to -distros@vs.openwall.org, preferably less than 7 days before the release date. +<distros@vs.openwall.org>, preferably less than 7 days before the release date. This will reach most (all?) Linux distributions. See an example below, and the guidelines for this mailing list at https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists[here]. @@ -65,7 +180,7 @@ created using a command like this: tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle Example mail to distros@vs.openwall.org ---------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .... To: distros@vs.openwall.org @@ -101,7 +216,7 @@ Thanks, .... Example mail to oss-security@lists.openwall.com ------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .... To: oss-security@lists.openwall.com @@ -128,4 +243,4 @@ it goes to <developer>. Thanks, <name> -.... +....
\ No newline at end of file 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/maintain-git.txt b/Documentation/howto/maintain-git.txt index a67130d..013014b 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -104,7 +104,7 @@ by doing the following: files in mbox format). - Write his own patches to address issues raised on the list but - nobody has stepped up solving. Send it out just like other + nobody has stepped up to solve. Send it out just like other contributors do, and pick them up just like patches from other contributors (see above). @@ -231,7 +231,7 @@ by doing the following: - Prepare 'jch' branch, which is used to represent somewhere between 'master' and 'seen' and often is slightly ahead of 'next'. - $ Meta/Reintegrate master..seen >Meta/redo-jch.sh + $ Meta/Reintegrate master..jch >Meta/redo-jch.sh The result is a script that lists topics to be merged in order to rebuild 'seen' as the input to Meta/Reintegrate script. Remove @@ -256,7 +256,7 @@ by doing the following: merged to 'next', add it at the end of the list. Then: $ git checkout -B jch master - $ Meta/redo-jch.sh -c1 + $ sh Meta/redo-jch.sh -c1 to rebuild the 'jch' branch from scratch. "-c1" tells the script to stop merging at the first line that begins with '###' @@ -283,6 +283,11 @@ by doing the following: $ git diff jch next + Then build the rest of 'jch': + + $ git checkout jch + $ sh Meta/redo-jch.sh + When all is well, clean up the redo-jch.sh script with $ sh Meta/redo-jch.sh -u @@ -293,7 +298,7 @@ by doing the following: - Rebuild 'seen'. - $ Meta/Reintegrate master..seen >Meta/redo-seen.sh + $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh Edit the result by adding new topics that are not still in 'seen' in the script. Then @@ -406,13 +411,13 @@ Preparing a "merge-fix" A merge of two topics may not textually conflict but still have conflict at the semantic level. A classic example is for one topic -to rename an variable and all its uses, while another topic adds a +to rename a variable and all its uses, while another topic adds a new use of the variable under its old name. When these two topics are merged together, the reference to the variable newly added by the latter topic will still use the old name in the result. The Meta/Reintegrate script that is used by redo-jch and redo-seen -scripts implements a crude but usable way to work this issue around. +scripts implements a crude but usable way to work around this issue. When the script merges branch $X, it checks if "refs/merge-fix/$X" exists, and if so, the effect of it is squashed into the result of the mechanical merge. In other words, diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index 15a4c80..880c511 100644 --- a/Documentation/howto/new-command.txt +++ b/Documentation/howto/new-command.txt @@ -1,13 +1,13 @@ From: Eric S. Raymond <esr@thyrsus.com> Abstract: This is how-to documentation for people who want to add extension - commands to Git. It should be read alongside api-builtin.txt. + commands to Git. It should be read alongside builtin.h. Content-type: text/asciidoc How to integrate new subcommands ================================ This is how-to documentation for people who want to add extension -commands to Git. It should be read alongside api-builtin.txt. +commands to Git. It should be read alongside builtin.h. Runtime environment ------------------- diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt index 8994e25..5efb4fe 100644 --- a/Documentation/howto/recover-corrupted-object-harder.txt +++ b/Documentation/howto/recover-corrupted-object-harder.txt @@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it has the git packed object header, which is variable-length. We want to strip that off so we can start playing with the zlib data directly. You can either work your way through it manually (the format is described in -link:../technical/pack-format.html[Documentation/technical/pack-format.txt]), +linkgit:gitformat-pack[5]), or you can walk through it in a debugger. I did the latter, creating a valid pack like: 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/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt index 7af2e52..2cad9b3 100644 --- a/Documentation/howto/use-git-daemon.txt +++ b/Documentation/howto/use-git-daemon.txt @@ -4,7 +4,7 @@ How to use git-daemon ===================== Git can be run in inetd mode and in stand alone mode. But all you want is -let a coworker pull from you, and therefore need to set up a Git server +to let a coworker pull from you, and therefore need to set up a Git server real quick, right? Note that git-daemon is not really chatty at the moment, especially when diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index a499a94..3bd581a 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -11,7 +11,7 @@ Message-ID: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE> How to use the subtree merge strategy ===================================== -There are situations where you want to include contents in your project +There are situations where you want to include content in your project from an independently developed project. You can just pull from the other project as long as there are no conflicting paths. diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index 6c6baee..3a866af 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -34,7 +34,7 @@ project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind. -. 'git commit' and 'git commit-tree' issues +. 'git commit' and 'git commit-tree' issue a warning if the commit log message given to it does not look like a valid UTF-8 string, unless you explicitly say your project uses a legacy encoding. The way to say this is to @@ -46,7 +46,7 @@ mind. ------------ + Commit objects created with the above setting record the value -of `i18n.commitEncoding` in its `encoding` header. This is to +of `i18n.commitEncoding` in their `encoding` header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8. diff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.txt new file mode 100644 index 0000000..296a239 --- /dev/null +++ b/Documentation/includes/cmd-config-section-all.txt @@ -0,0 +1,3 @@ +Everything below this line in this section is selectively included +from the linkgit:git-config[1] documentation. The content is the same +as what's found there: diff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.txt new file mode 100644 index 0000000..b1e7682 --- /dev/null +++ b/Documentation/includes/cmd-config-section-rest.txt @@ -0,0 +1,3 @@ +Everything above this line in this section isn't included from the +linkgit:git-config[1] documentation. The content that follows is the +same as what's found there: diff --git a/Documentation/lint-fsck-msgids.perl b/Documentation/lint-fsck-msgids.perl new file mode 100755 index 0000000..1233ffe --- /dev/null +++ b/Documentation/lint-fsck-msgids.perl @@ -0,0 +1,70 @@ +#!/usr/bin/perl + +my ($fsck_h, $fsck_msgids_txt, $okfile) = @ARGV; + +my (%in_fsck_h, $fh, $bad); + +open($fh, "<", "$fsck_h") or die; +while (<$fh>) { + if (/^\s+FUNC\(([0-9A-Z_]+), ([A-Z]+)\)/) { + my ($name, $severity) = ($1, $2); + my ($first) = 1; + $name = join('', + map { + y/A-Z/a-z/; + if (!$first) { + s/^(.)/uc($1)/e; + } else { + $first = 0; + } + $_; + } + split(/_/, $name)); + $in_fsck_h{$name} = $severity; + } +} +close($fh); + +open($fh, "<", "$fsck_msgids_txt") or die; +my ($previous, $current); +while (<$fh>) { + if (!defined $current) { + if (/^\`([a-zA-Z0-9]*)\`::/) { + $current = $1; + if ((defined $previous) && + ($current le $previous)) { + print STDERR "$previous >= $current in doc\n"; + $bad = 1; + } + } + } elsif (/^\s+\(([A-Z]+)\) /) { + my ($level) = $1; + if (!exists $in_fsck_h{$current}) { + print STDERR "$current does not exist in fsck.h\n"; + $bad = 1; + } elsif ($in_fsck_h{$current} eq "") { + print STDERR "$current defined twice\n"; + $bad = 1; + } elsif ($in_fsck_h{$current} ne $level) { + print STDERR "$current severity $level != $in_fsck_h{$current}\n"; + $bad = 1; + } + $previous = $current; + $in_fsck_h{$current} = ""; # mark as seen. + undef $current; + } +} +close($fh); + +for my $key (keys %in_fsck_h) { + if ($in_fsck_h{$key} ne "") { + print STDERR "$key not explained in doc.\n"; + $bad = 1; + } +} + +die if ($bad); + +open($fh, ">", "$okfile"); +print $fh "good\n"; +close($fh); diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl index 425377d..02408a0 100755 --- a/Documentation/lint-man-section-order.perl +++ b/Documentation/lint-man-section-order.perl @@ -32,6 +32,9 @@ my %SECTIONS; 'SEE ALSO' => { order => $order++, }, + 'FILE FORMAT' => { + order => $order++, + }, 'GIT' => { required => 1, order => $order++, diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in deleted file mode 100644 index e800904..0000000 --- a/Documentation/manpage-base-url.xsl.in +++ /dev/null @@ -1,10 +0,0 @@ -<!-- manpage-base-url.xsl: - special settings for manpages rendered from newer docbook --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- set a base URL for relative links --> -<xsl:param name="man.base.url.for.relative.links" - >@@MAN_BASE_URL@@</xsl:param> - -</xsl:stylesheet> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl index a9c7ec6..beb5ff8 100644 --- a/Documentation/manpage-normal.xsl +++ b/Documentation/manpage-normal.xsl @@ -8,19 +8,7 @@ <xsl:param name="man.output.quietly" select="1"/> <xsl:param name="refentry.meta.get.quietly" select="1"/> -<!-- convert asciidoc callouts to man page format --> -<xsl:template match="co"> - <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/> -</xsl:template> -<xsl:template match="calloutlist"> - <xsl:text>.sp </xsl:text> - <xsl:apply-templates/> - <xsl:text> </xsl:text> -</xsl:template> -<xsl:template match="callout"> - <xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/> - <xsl:apply-templates/> - <xsl:text>.br </xsl:text> -</xsl:template> +<!-- unset maximum length of title --> +<xsl:param name="man.th.title.max.length"/> </xsl:stylesheet> diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl deleted file mode 100644 index aeb8839..0000000 --- a/Documentation/manpage-quote-apos.xsl +++ /dev/null @@ -1,16 +0,0 @@ -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- work around newer groff/man setups using a prettier apostrophe - that unfortunately does not quote anything when cut&pasting - examples to the shell --> -<xsl:template name="escape.apostrophe"> - <xsl:param name="content"/> - <xsl:call-template name="string.subst"> - <xsl:with-param name="string" select="$content"/> - <xsl:with-param name="target">'</xsl:with-param> - <xsl:with-param name="replacement">\(aq</xsl:with-param> - </xsl:call-template> -</xsl:template> - -</xsl:stylesheet> 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 2d631e9..befa86d 100644 --- a/Documentation/mergetools/vimdiff.txt +++ b/Documentation/mergetools/vimdiff.txt @@ -32,10 +32,10 @@ have special meaning: - `+` is used to "open a new tab" - `,` is used to "open a new vertical split" - `/` is used to "open a new horizontal split" - - `@` is used to indicate which is the file containing the final version after + - `@` is used to indicate the file containing the final version after solving the conflicts. If not present, `MERGED` will be used by default. -The precedence of the operators is this one (you can use parentheses to change +The precedence of the operators is as follows (you can use parentheses to change it): `@` > `+` > `/` > `,` @@ -162,7 +162,7 @@ information as the first tab, with a different layout. | REMOTE | | --------------------------------------------- .... -Note how in the third tab definition we need to use parenthesis to make `,` +Note how in the third tab definition we need to use parentheses to make `,` have precedence over `/`. -- @@ -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/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt index 4cb106f..e561e66 100644 --- a/Documentation/object-format-disclaimer.txt +++ b/Documentation/object-format-disclaimer.txt @@ -1,6 +1,9 @@ -THIS OPTION IS EXPERIMENTAL! SHA-256 support is experimental and still -in an early stage. A SHA-256 repository will in general not be able to -share work with "regular" SHA-1 repositories. It should be assumed -that, e.g., Git internal file formats in relation to SHA-256 -repositories may change in backwards-incompatible ways. Only use -`--object-format=sha256` for testing purposes. +Note: At present, there is no interoperability between SHA-256 +repositories and SHA-1 repositories. + +Historically, we warned that SHA-256 repositories may later need +backward incompatible changes when we introduce such interoperability +features. Today, we only expect compatible changes. Furthermore, if such +changes prove to be necessary, it can be expected that SHA-256 repositories +created with today's Git will be usable by future versions of Git +without data loss. diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 0b4c1c8..8ee940b 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -122,7 +122,9 @@ The placeholders are: - Placeholders that expand to a single literal character: '%n':: newline '%%':: a raw '%' -'%x00':: print a byte from a hex code +'%x00':: '%x' followed by two hexadecimal digits is replaced with a + byte with the hexadecimal digits' value (we will call this + "literal formatting code" in the rest of this document). - Placeholders that affect formatting of later placeholders: '%Cred':: switch color to red @@ -146,24 +148,34 @@ The placeholders are: '%m':: left (`<`), right (`>`) or boundary (`-`) mark '%w([<w>[,<i1>[,<i2>]]])':: switch line wrapping, like the -w option of linkgit:git-shortlog[1]. -'%<(<N>[,trunc|ltrunc|mtrunc])':: make the next placeholder take at - least N columns, padding spaces on +'%<( <N> [,trunc|ltrunc|mtrunc])':: make the next placeholder take at + least N column widths, padding spaces on the right if necessary. Optionally - truncate at the beginning (ltrunc), - the middle (mtrunc) or the end - (trunc) if the output is longer than - N columns. Note that truncating + truncate (with ellipsis '..') at the left (ltrunc) `..ft`, + the middle (mtrunc) `mi..le`, or the end + (trunc) `rig..`, if the output is longer than + N columns. + Note 1: that truncating only works correctly with N >= 2. -'%<|(<N>)':: make the next placeholder take at least until Nth - columns, padding spaces on the right if necessary -'%>(<N>)', '%>|(<N>)':: similar to '%<(<N>)', '%<|(<N>)' respectively, + Note 2: spaces around the N and M (see below) + values are optional. + Note 3: Emojis and other wide characters + will take two display columns, which may + over-run column boundaries. + Note 4: decomposed character combining marks + may be misplaced at padding boundaries. +'%<|( <M> )':: make the next placeholder take at least until Mth + display column, padding spaces on the right if necessary. + Use negative M values for column positions measured + from the right hand edge of the terminal window. +'%>( <N> )', '%>|( <M> )':: similar to '%<( <N> )', '%<|( <M> )' respectively, but padding spaces on the left -'%>>(<N>)', '%>>|(<N>)':: similar to '%>(<N>)', '%>|(<N>)' +'%>>( <N> )', '%>>|( <M> )':: similar to '%>( <N> )', '%>|( <M> )' respectively, except that if the next placeholder takes more spaces than given and there are spaces on its left, use those spaces -'%><(<N>)', '%><|(<N>)':: similar to '%<(<N>)', '%<|(<N>)' +'%><( <N> )', '%><|( <M> )':: similar to '%<( <N> )', '%<|( <M> )' respectively, but padding both sides (i.e. the text is centered) @@ -212,13 +224,30 @@ The placeholders are: linkgit:git-rev-list[1]) '%d':: ref names, like the --decorate option of linkgit:git-log[1] '%D':: ref names without the " (", ")" wrapping. -'%(describe[:options])':: human-readable name, like - linkgit:git-describe[1]; empty string for - undescribable commits. The `describe` string - may be followed by a colon and zero or more - comma-separated options. Descriptions can be - inconsistent when tags are added or removed at - the same time. +'%(decorate[:<options>])':: +ref names with custom decorations. The `decorate` string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (`%x2C`) and closing +parentheses (`%x29`), due to their role in the option syntax. ++ +** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`". +** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`". +** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}". +** 'pointer=<value>': Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}`->`{nbsp}". +** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}". + ++ +For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators: ++ +`%(decorate:prefix=,suffix=,tag=,separator= )` + +'%(describe[:<options>])':: +human-readable name, like linkgit:git-describe[1]; empty string for +undescribable commits. The `describe` string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time. + ** 'tags[=<bool-value>]': Instead of only considering annotated tags, consider lightweight tags as well. @@ -271,13 +300,11 @@ endif::git-rev-list[] '%gE':: reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) '%gs':: reflog subject -'%(trailers[:options])':: display the trailers of the body as - interpreted by - linkgit:git-interpret-trailers[1]. The - `trailers` string may be followed by a colon - and zero or more comma-separated options. - If any option is provided multiple times the - last occurrence wins. +'%(trailers[:<options>])':: +display the trailers of the body as interpreted by +linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins. + ** 'key=<key>': only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is @@ -289,9 +316,8 @@ endif::git-rev-list[] `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 )` @@ -302,10 +328,9 @@ endif::git-rev-list[] `%(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/pretty-options.txt b/Documentation/pretty-options.txt index dc685be..23888cd 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -48,7 +48,7 @@ people using 80-column terminals. --expand-tabs:: --no-expand-tabs:: Perform a tab expansion (replace each tab with enough spaces - to fill to the next display column that is multiple of '<n>') + to fill to the next display column that is a multiple of '<n>') in the log message before showing it in the output. `--expand-tabs` is a short-hand for `--expand-tabs=8`, and `--no-expand-tabs` is a short-hand for `--expand-tabs=0`, @@ -73,7 +73,7 @@ environment overrides). See linkgit:git-config[1] for more details. With an optional '<ref>' argument, use the ref to find the notes to display. The ref can specify the full refname when it begins with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise -`refs/notes/` is prefixed to form a full name of the ref. +`refs/notes/` is prefixed to form the full name of the ref. + Multiple --notes options can be combined to control which notes are being displayed. Examples: "--notes=foo" will show only notes from @@ -87,6 +87,10 @@ being displayed. Examples: "--notes=foo" will show only notes from "--notes --notes=foo --no-notes --notes=bar" will only show notes from "refs/notes/bar". +--show-notes-by-default:: + Show the default notes unless options for displaying specific + notes are given. + --show-notes[=<ref>]:: --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 95a7390..c718f79 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -71,7 +71,7 @@ refspec (or `--force`). Unlike when pushing with linkgit:git-push[1], any updates outside of `refs/{tags,heads}/*` will be accepted without `+` in the refspec (or `--force`), whether that's swapping e.g. a tree object for a blob, or -a commit for another commit that's doesn't have the previous commit as +a commit for another commit that doesn't have the previous commit as an ancestor etc. + Unlike when pushing with linkgit:git-push[1], there is no @@ -80,7 +80,7 @@ configuration which'll amend these rules, and nothing like a + As with pushing with linkgit:git-push[1], all of the rules described above about what's not allowed as an update can be overridden by -adding an the optional leading `+` to a refspec (or using `--force` +adding an optional leading `+` to a refspec (or using the `--force` command line option). The only exception to this is that no amount of forcing will make the `refs/heads/*` namespace accept a non-commit object. @@ -88,7 +88,7 @@ object. [NOTE] When the remote branch you want to fetch is known to be rewound and rebased regularly, it is expected that -its new tip will not be descendant of its previous tip +its new tip will not be a descendant of its previous tip (as stored in your remote-tracking branch the last time you fetched). You would want to use the `+` sign to indicate non-fast-forward updates 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/rerere-options.txt b/Documentation/rerere-options.txt new file mode 100644 index 0000000..c3321dd --- /dev/null +++ b/Documentation/rerere-options.txt @@ -0,0 +1,9 @@ +--rerere-autoupdate:: +--no-rerere-autoupdate:: + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. `--no-rerere-autoupdate` is a good way to + double-check what `rerere` did and catch potential + mismerges, before committing the result to the index with a + separate `git add`. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 195e74e..00ccf68 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -56,7 +56,7 @@ endif::git-rev-list[] error to use this option unless `--walk-reflogs` is in use. --grep=<pattern>:: - Limit the commits output to ones with log message that + Limit the commits output to ones with a log message that matches the specified pattern (regular expression). With more than one `--grep=<pattern>`, commits whose message matches any of the given patterns are chosen (but see @@ -72,7 +72,7 @@ endif::git-rev-list[] instead of ones that match at least one. --invert-grep:: - Limit the commits output to ones with log message that do not + Limit the commits output to ones with a log message that do not match the pattern specified with `--grep=<pattern>`. -i:: @@ -151,6 +151,10 @@ endif::git-log[] --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. + When used on the command line before --stdin, the revisions passed + through stdin will not be affected by it. Conversely, when passed + via standard input, the revisions passed on the command line will + not be affected by it. --all:: Pretend as if all the refs in `refs/`, along with `HEAD`, are @@ -195,6 +199,14 @@ 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]:: + 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` + configuration along with `transfer.hideRefs` (see + linkgit:git-config[1]). This option affects the next pseudo-ref option + `--all` or `--glob` and is cleared after processing them. + --reflog:: Pretend as if all objects mentioned by reflogs are listed on the command line as `<commit>`. @@ -228,10 +240,13 @@ ifndef::git-rev-list[] endif::git-rev-list[] --stdin:: - In addition to the '<commit>' listed on the command - line, read them from the standard input. If a `--` separator is - seen, stop reading commits and start reading paths to limit the - result. + In addition to getting arguments from the command line, read + them from standard input as well. This accepts commits and + pseudo-options like `--all` and `--glob=`. When a `--` separator + is seen, the following input is treated as paths and used to + limit the result. Flags like `--not` which are read via standard input + are only respected for arguments passed in the same way and will not + influence any subsequent command line arguments. ifdef::git-rev-list[] --quiet:: @@ -242,6 +257,7 @@ ifdef::git-rev-list[] to `/dev/null` as the output does not have to be formatted. --disk-usage:: +--disk-usage=human:: Suppress normal output; instead, print the sum of the bytes used for on-disk storage by the selected commits or objects. This is equivalent to piping the output into `git cat-file @@ -249,6 +265,8 @@ ifdef::git-rev-list[] faster (especially with `--use-bitmap-index`). See the `CAVEATS` section in linkgit:git-cat-file[1] for the limitations of what "on-disk storage" means. + With the optional value `human`, on-disk storage size is shown + in human-readable string(e.g. 12.24 Kib, 3.50 Mib). endif::git-rev-list[] --cherry-mark:: @@ -298,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 @@ -323,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 @@ -389,12 +410,14 @@ Default mode:: merges from the resulting history, as there are no selected commits contributing to this merge. ---ancestry-path:: +--ancestry-path[=<commit>]:: When given a range of commits to display (e.g. 'commit1..commit2' - or 'commit2 {caret}commit1'), only display commits that exist - directly on the ancestry chain between the 'commit1' and - 'commit2', i.e. commits that are both descendants of 'commit1', - and ancestors of 'commit2'. + or 'commit2 {caret}commit1'), only display commits in that range + that are ancestors of <commit>, descendants of <commit>, or + <commit> itself. If no commit is specified, use 'commit1' (the + excluded part of the range) as <commit>. Can be passed multiple + times; if so, a commit is included if it is any of the commits + given or if it is an ancestor or descendant of one of them. A more detailed explanation follows. @@ -568,11 +591,10 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`: There is another simplification mode available: ---ancestry-path:: - Limit the displayed commits to those directly on the ancestry - chain between the ``from'' and ``to'' commits in the given commit - range. I.e. only display commits that are ancestor of the ``to'' - commit and descendants of the ``from'' commit. +--ancestry-path[=<commit>]:: + Limit the displayed commits to those which are an ancestor of + <commit>, or which are a descendant of <commit>, or are <commit> + itself. + As an example use case, consider the following commit history: + @@ -604,6 +626,29 @@ option does. Applied to the 'D..M' range, it results in: \ L--M ----------------------------------------------------------------------- ++ +We can also use `--ancestry-path=D` instead of `--ancestry-path` which +means the same thing when applied to the 'D..M' range but is just more +explicit. ++ +If we instead are interested in a given topic within this range, and all +commits affected by that topic, we may only want to view the subset of +`D..M` which contain that topic in their ancestry path. So, using +`--ancestry-path=H D..M` for example would result in: ++ +----------------------------------------------------------------------- + E + \ + G---H---I---J + \ + L--M +----------------------------------------------------------------------- ++ +Whereas `--ancestry-path=K D..M` would result in ++ +----------------------------------------------------------------------- + K---------------L--M +----------------------------------------------------------------------- Before discussing another option, `--show-pulls`, we need to create a new example history. @@ -659,7 +704,7 @@ Here, the merge commits `O` and `P` contribute extra noise, as they did not actually contribute a change to `file.txt`. They only merged a topic that was based on an older version of `file.txt`. This is a common issue in repositories using a workflow where many contributors work in -parallel and merge their topic branches along a single trunk: manu +parallel and merge their topic branches along a single trunk: many unrelated merges appear in the `--full-history` results. When using the `--simplify-merges` option, the commits `O` and `P` @@ -855,7 +900,7 @@ ifdef::git-rev-list[] Print the object IDs of any object referenced by the listed commits. `--objects foo ^bar` thus means ``send me all object IDs which I need to download if I have the commit - object _bar_ but not _foo_''. + object _bar_ but not _foo_''. See also `--object-names` below. --in-commit-order:: Print tree and blob ids in order of the commits. The tree @@ -885,7 +930,12 @@ ifdef::git-rev-list[] --object-names:: Only useful with `--objects`; print the names of the object IDs - that are found. This is the default behavior. + that are found. This is the default behavior. Note that the + "name" of each object is ambiguous, and mostly intended as a + hint for packing objects. In particular: no distinction is made between + the names of tags, trees, and blobs; path names may be modified + to remove newlines; and if an object would appear multiple times + with different names, only one name is shown. --no-object-names:: Only useful with `--objects`; does not print the names of the object @@ -900,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. @@ -972,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 @@ -1066,12 +1120,12 @@ preferred format. See the `strftime` manual for a complete list of format placeholders. When using `-local`, the correct syntax is `--date=format-local:...`. -`--date=default` is the default format, and is similar to -`--date=rfc2822`, with a few exceptions: +`--date=default` is the default format, and is based on ctime(3) +output. It shows a single line with three-letter day of the week, +three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS" +format, followed by 4-digit year, plus timezone information, unless +the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`. -- - - there is no comma after the day-of-week - - - the time zone is omitted when the local time zone is used ifdef::git-rev-list[] --header:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index f5f17b6..6ea6c7c 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -30,10 +30,11 @@ characters and to avoid word splitting. explicitly say 'heads/master' to tell Git which one you mean. When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - ++ . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` - and `CHERRY_PICK_HEAD`); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD` + and `AUTO_MERGE`); . otherwise, 'refs/<refname>' if it exists; @@ -44,18 +45,38 @@ characters and to avoid word splitting. . otherwise, 'refs/remotes/<refname>' if it exists; . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + + -`HEAD` names the commit on which you based the changes in the working tree. -`FETCH_HEAD` records the branch which you fetched from a remote repository -with your last `git fetch` invocation. -`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way, to record the position of the `HEAD` before their operation, so that -you can easily change the tip of the branch back to the state before you ran -them. -`MERGE_HEAD` records the commit(s) which you are merging into your branch -when you run `git merge`. -`CHERRY_PICK_HEAD` records the commit which you are cherry-picking -when you run `git cherry-pick`. + `HEAD`::: + names the commit on which you based the changes in the working tree. + `FETCH_HEAD`::: + records the branch which you fetched from a remote repository with + your last `git fetch` invocation. + `ORIG_HEAD`::: + is created by commands that move your `HEAD` in a drastic way (`git + am`, `git merge`, `git rebase`, `git reset`), to record the position + of the `HEAD` before their operation, so that you can easily change + the tip of the branch back to the state before you ran them. + `MERGE_HEAD`::: + records the commit(s) which you are merging into your branch when you + run `git merge`. + `REBASE_HEAD`::: + during a rebase, records the commit at which the operation is + currently stopped, either because of conflicts or an `edit` command in + an interactive rebase. + `REVERT_HEAD`::: + records the commit which you are reverting when you run `git revert`. + `CHERRY_PICK_HEAD`::: + records the commit which you are cherry-picking when you run `git + cherry-pick`. + `BISECT_HEAD`::: + records the current commit to be tested when you run `git bisect + --no-checkout`. + `AUTO_MERGE`::: + records a tree object corresponding to the state the + 'ort' merge strategy wrote to the working tree when a merge operation + resulted in conflicts. + + Note that any of the 'refs/*' cases above may come either from the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. @@ -96,19 +117,16 @@ some output processing may assume ref names in UTF-8. before the current one. '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: - The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') - refers to the branch that the branch specified by branchname is set to build on - top of (configured with `branch.<name>.remote` and - `branch.<name>.merge`). A missing branchname defaults to the - current one. These suffixes are also accepted when spelled in uppercase, and - they mean the same thing no matter the case. + A branch B may be set up to build on top of a branch X (configured with + `branch.<name>.merge`) at a remote R (configured with + `branch.<name>.remote`). B@{u} refers to the remote-tracking branch for + the branch X taken from remote R, typically found at `refs/remotes/R/X`. '[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: The suffix '@\{push}' reports the branch "where we would push to" if `git push` were run while `branchname` was checked out (or the current - `HEAD` if no branchname is specified). Since our push destination is - in a remote repository, of course, we report the local tracking branch - that corresponds to that branch (i.e., something in `refs/remotes/`). + `HEAD` if no branchname is specified). Like for '@\{upstream\}', we report + the remote-tracking branch that corresponds to that branch at the remote. + Here's an example to make it more clear: + @@ -283,7 +301,7 @@ The '..' (two-dot) Range Notation:: for commits that are reachable from r2 excluding those that are reachable from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. -The '...' (three-dot) Symmetric Difference Notation:: +The '\...' (three-dot) Symmetric Difference Notation:: A similar notation 'r1\...r2' is called symmetric difference of 'r1' and 'r2' and is defined as 'r1 r2 --not $(git merge-base --all r1 r2)'. @@ -366,7 +384,7 @@ Revision Range Summary '<rev>{caret}!', e.g. 'HEAD{caret}!':: A suffix '{caret}' followed by an exclamation mark is the same - as giving commit '<rev>' and then all its parents prefixed with + as giving commit '<rev>' and all its parents prefixed with '{caret}' to exclude them (and their ancestors). '<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2':: diff --git a/Documentation/scalar.txt b/Documentation/scalar.txt new file mode 100644 index 0000000..361f51a --- /dev/null +++ b/Documentation/scalar.txt @@ -0,0 +1,172 @@ +scalar(1) +========= + +NAME +---- +scalar - A tool for managing large Git repositories + +SYNOPSIS +-------- +[verse] +scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] + [--[no-]src] <url> [<enlistment>] +scalar list +scalar register [<enlistment>] +scalar unregister [<enlistment>] +scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>] +scalar reconfigure [ --all | <enlistment> ] +scalar diagnose [<enlistment>] +scalar delete <enlistment> + +DESCRIPTION +----------- + +Scalar is a repository management tool that optimizes Git for use in large +repositories. Scalar improves performance by configuring advanced Git settings, +maintaining repositories in the background, and helping to reduce data sent +across the network. + +An important Scalar concept is the enlistment: this is the top-level directory +of the project. It usually contains the subdirectory `src/` which is a Git +worktree. This encourages the separation between tracked files (inside `src/`) +and untracked files, such as build artifacts (outside `src/`). When registering +an existing Git worktree with Scalar whose name is not `src`, the enlistment +will be identical to the worktree. + +The `scalar` command implements various subcommands, and different options +depending on the subcommand. With the exception of `clone`, `list` and +`reconfigure --all`, all subcommands expect to be run in an enlistment. + +The following options can be specified _before_ the subcommand: + +-C <directory>:: + Before running the subcommand, change the working directory. This + option imitates the same option of linkgit:git[1]. + +-c <key>=<value>:: + For the duration of running the specified subcommand, configure this + setting. This option imitates the same option of linkgit:git[1]. + +COMMANDS +-------- + +Clone +~~~~~ + +clone [<options>] <url> [<enlistment>]:: + Clones the specified repository, similar to linkgit:git-clone[1]. By + default, only commit and tree objects are cloned. Once finished, the + worktree is located at `<enlistment>/src`. ++ +The sparse-checkout feature is enabled (except when run with `--full-clone`) +and the only files present are those in the top-level directory. Use +`git sparse-checkout set` to expand the set of directories you want to see, +or `git sparse-checkout disable` to expand to all files (see +linkgit:git-sparse-checkout[1] for more details). You can explore the +subdirectories outside your sparse-checkout by using `git ls-tree +HEAD[:<directory>]`. + +-b <name>:: +--branch <name>:: + Instead of checking out the branch pointed to by the cloned + repository's HEAD, check out the `<name>` branch instead. + +--[no-]single-branch:: + Clone only the history leading to the tip of a single branch, either + specified by the `--branch` option or the primary branch remote's + `HEAD` points at. ++ +Further fetches into the resulting repository will only update the +remote-tracking branch for the branch this option was used for the initial +cloning. If the HEAD at the remote did not point at any branch when +`--single-branch` clone was made, no remote-tracking branch is created. + +--[no-]src:: + By default, `scalar clone` places the cloned repository within a + `<entlistment>/src` directory. Use `--no-src` to place the cloned + repository directly in the `<enlistment>` directory. + +--[no-]full-clone:: + A sparse-checkout is initialized by default. This behavior can be + turned off via `--full-clone`. + +List +~~~~ + +list:: + List enlistments that are currently registered by Scalar. This + subcommand does not need to be run inside an enlistment. + +Register +~~~~~~~~ + +register [<enlistment>]:: + Adds the enlistment's repository to the list of registered repositories + and starts background maintenance. If `<enlistment>` is not provided, + then the enlistment associated with the current working directory is + registered. ++ +Note: when this subcommand is called in a worktree that is called `src/`, its +parent directory is considered to be the Scalar enlistment. If the worktree is +_not_ called `src/`, it itself will be considered to be the Scalar enlistment. + +Unregister +~~~~~~~~~~ + +unregister [<enlistment>]:: + Remove the specified repository from the list of repositories + registered with Scalar and stop the scheduled background maintenance. + +Run +~~~ + +scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]:: + Run the given maintenance task (or all tasks, if `all` was specified). + Except for `all` and `config`, this subcommand simply hands off to + linkgit:git-maintenance[1] (mapping `fetch` to `prefetch` and + `pack-files` to `incremental-repack`). ++ +These tasks are run automatically as part of the scheduled maintenance, +as soon as the repository is registered with Scalar. It should therefore +not be necessary to run this subcommand manually. ++ +The `config` task is specific to Scalar and configures all those +opinionated default settings that make Git work more efficiently with +large repositories. As this task is run as part of `scalar clone` +automatically, explicit invocations of this task are rarely needed. + +Reconfigure +~~~~~~~~~~~ + +After a Scalar upgrade, or when the configuration of a Scalar enlistment +was somehow corrupted or changed by mistake, this subcommand allows to +reconfigure the enlistment. + +With the `--all` option, all enlistments currently registered with Scalar +will be reconfigured. Use this option after each Scalar upgrade. + +Diagnose +~~~~~~~~ + +diagnose [<enlistment>]:: + When reporting issues with Scalar, it is often helpful to provide the + information gathered by this command, including logs and certain + statistics describing the data shape of the current enlistment. ++ +The output of this command is a `.zip` file that is written into +a directory adjacent to the worktree in the `src` directory. + +Delete +~~~~~~ + +delete <enlistment>:: + This subcommand lets you delete an existing Scalar enlistment from your + local file system, unregistering the repository. + +SEE ALSO +-------- +linkgit:git-clone[1], linkgit:git-maintenance[1]. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/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/api-error-handling.txt b/Documentation/technical/api-error-handling.txt index 70bf1d3..665c496 100644 --- a/Documentation/technical/api-error-handling.txt +++ b/Documentation/technical/api-error-handling.txt @@ -46,7 +46,7 @@ parse-options.c. returns -1 after reporting the situation to the caller. These reports will be logged via the trace2 facility. See the "error" -event in link:api-trace2.txt[trace2 API]. +event in link:api-trace2.html[trace2 API]. Customizable error handlers --------------------------- diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt index eda8c19..7780a76 100644 --- a/Documentation/technical/api-index-skel.txt +++ b/Documentation/technical/api-index-skel.txt @@ -1,7 +1,7 @@ Git API Documents ================= -Git has grown a set of internal API over time. This collection +Git has grown a set of internal APIs over time. This collection documents them. //////////////////////////////////////////////////////////////// diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 487d4d8..c2ba018 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -28,9 +28,9 @@ and `diff.c` for examples. * `struct ll_merge_options` -Check ll-merge.h for details. +Check merge-ll.h for details. Low-level (single file) merge ----------------------------- -Check ll-merge.h for details. +Check merge-ll.h for details. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index acfd5dc..61fa6ee 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -8,7 +8,8 @@ Basics ------ The argument vector `argv[]` may usually contain mandatory or optional -'non-option arguments', e.g. a filename or a branch, and 'options'. +'non-option arguments', e.g. a filename or a branch, 'options', and +'subcommands'. Options are optional arguments that start with a dash and that allow to change the behavior of a command. @@ -48,6 +49,33 @@ The parse-options API allows: option, e.g. `-a -b --option -- --this-is-a-file` indicates that `--this-is-a-file` must not be processed as an option. +Subcommands are special in a couple of ways: + +* Subcommands only have long form, and they have no double dash prefix, no + negated form, and no description, and they don't take any arguments, and + can't be abbreviated. + +* There must be exactly one subcommand among the arguments, or zero if the + command has a default operation mode. + +* All arguments following the subcommand are considered to be arguments of + the subcommand, and, conversely, arguments meant for the subcommand may + not precede the subcommand. + +Therefore, if the options array contains at least one subcommand and +`parse_options()` encounters the first dashless argument, it will either: + +* stop and return, if that dashless argument is a known subcommand, setting + `value` to the function pointer associated with that subcommand, storing + the name of the subcommand in argv[0], and leaving the rest of the + arguments unprocessed, or + +* stop and return, if it was invoked with the `PARSE_OPT_SUBCOMMAND_OPTIONAL` + flag and that dashless argument doesn't match any subcommands, leaving + `value` unchanged and the rest of the arguments unprocessed, or + +* show error and usage, and abort. + Steps to parse options ---------------------- @@ -90,8 +118,8 @@ Flags are the bitwise-or of: Keep the first argument, which contains the program name. It's removed from argv[] by default. -`PARSE_OPT_KEEP_UNKNOWN`:: - Keep unknown arguments instead of erroring out. This doesn't +`PARSE_OPT_KEEP_UNKNOWN_OPT`:: + Keep unknown options instead of erroring out. This doesn't work for all combinations of arguments as users might expect it to do. E.g. if the first argument in `--unknown --known` takes a value (which we can't know), the second one is @@ -101,6 +129,8 @@ Flags are the bitwise-or of: non-option, not as a value belonging to the unknown option, the parser early. That's why parse_options() errors out if both options are set. + Note that non-option arguments are always kept, even without + this flag. `PARSE_OPT_NO_INTERNAL_HELP`:: By default, parse_options() handles `-h`, `--help` and @@ -108,6 +138,13 @@ Flags are the bitwise-or of: turns it off and allows one to add custom handlers for these options, or to just leave them unknown. +`PARSE_OPT_SUBCOMMAND_OPTIONAL`:: + Don't error out when no subcommand is specified. + +Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands; +while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be +used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`. + Data Structure -------------- @@ -236,10 +273,14 @@ There are some macros to easily define options: `OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: Define an "operation mode" option, only one of which in the same group of "operating mode" options that share the same `int_var` - can be given by the user. `enum_val` is set to `int_var` when the + can be given by the user. `int_var` is set to `enum_val` when the option is used, but an error is reported if other "operating mode" option has already set its value to the same `int_var`. + In new commands consider using subcommands instead. +`OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`:: + Define a subcommand. `subcommand_fn` is put into `fn_ptr` when + this subcommand is used. The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt index d79ad32..c4fb152 100644 --- a/Documentation/technical/api-simple-ipc.txt +++ b/Documentation/technical/api-simple-ipc.txt @@ -2,7 +2,7 @@ Simple-IPC API ============== The Simple-IPC API is a collection of `ipc_` prefixed library routines -and a basic communication protocol that allow an IPC-client process to +and a basic communication protocol that allows an IPC-client process to send an application-specific IPC-request message to an IPC-server process and receive an application-specific IPC-response message. @@ -20,12 +20,12 @@ IPC-client. The IPC-client routines within a client application process connect to the IPC-server and send a request message and wait for a response. -When received, the response is returned back the caller. +When received, the response is returned back to the caller. For example, the `fsmonitor--daemon` feature will be built as a server application on top of the IPC-server library routines. It will have threads watching for file system events and a thread pool waiting for -client connections. Clients, such as `git status` will request a list +client connections. Clients, such as `git status`, will request a list of file system events since a point in time and the server will respond with a list of changed files and directories. The formats of the request and response are application-specific; the IPC-client and @@ -37,7 +37,7 @@ Comparison with sub-process model The Simple-IPC mechanism differs from the existing `sub-process.c` model (Documentation/technical/long-running-process-protocol.txt) and -used by applications like Git-LFS. In the LFS-style sub-process model +used by applications like Git-LFS. In the LFS-style sub-process model, the helper is started by the foreground process, communication happens via a pair of file descriptors bound to the stdin/stdout of the sub-process, the sub-process only serves the current foreground @@ -78,7 +78,7 @@ client and an optional response message from the server. Both the client and server messages are unlimited in length and are terminated with a flush packet. -The pkt-line routines (Documentation/technical/protocol-common.txt) +The pkt-line routines (linkgit:gitprotocol-common[5]) are used to simplify buffer management during message generation, transmission, and reception. A flush packet is used to mark the end of the message. This allows the sender to incrementally generate and @@ -102,4 +102,4 @@ stateless request, receive an application-specific response, and disconnect. It is a one round trip facility for querying the server. The Simple-IPC routines hide the socket, named pipe, and thread pool details and allow the application -layer to focus on the application at hand. +layer to focus on the task at hand. diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 77a150b..de5fc25 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -148,20 +148,18 @@ filename collisions). == Trace2 API -All public Trace2 functions and macros are defined in `trace2.h` and -`trace2.c`. All public symbols are prefixed with `trace2_`. +The Trace2 public API is defined and documented in `trace2.h`; refer to it for +more information. All public functions and macros are prefixed +with `trace2_` and are implemented in `trace2.c`. There are no public Trace2 data structures. The Trace2 code also defines a set of private functions and data types in the `trace2/` directory. These symbols are prefixed with `tr2_` -and should only be used by functions in `trace2.c`. +and should only be used by functions in `trace2.c` (or other private +source files in `trace2/`). -== Conventions for Public Functions and Macros - -The functions defined by the Trace2 API are declared and documented -in `trace2.h`. It defines the API functions and wrapper macros for -Trace2. +=== Conventions for Public Functions and Macros Some functions have a `_fl()` suffix to indicate that they take `file` and `line-number` arguments. @@ -172,52 +170,7 @@ take a `va_list` argument. Some functions have a `_printf_fl()` suffix to indicate that they also take a `printf()` style format with a variable number of arguments. -There are CPP wrapper macros and `#ifdef`s to hide most of these details. -See `trace2.h` for more details. The following discussion will only -describe the simplified forms. - -== Public API - -All Trace2 API functions send a message to all of the active -Trace2 Targets. This section describes the set of available -messages. - -It helps to divide these functions into groups for discussion -purposes. - -=== Basic Command Messages - -These are concerned with the lifetime of the overall git process. -e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`, -`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`. - -=== Command Detail Messages - -These are concerned with describing the specific Git command -after the command line, config, and environment are inspected. -e.g: `void trace2_cmd_name(const char *name)`, -`void trace2_cmd_mode(const char *mode)`. - -=== Child Process Messages - -These are concerned with the various spawned child processes, -including shell scripts, git commands, editors, pagers, and hooks. - -e.g: `void trace2_child_start(struct child_process *cmd)`. - -=== Git Thread Messages - -These messages are concerned with Git thread usage. - -e.g: `void trace2_thread_start(const char *thread_name)`. - -=== Region and Data Messages - -These are concerned with recording performance data -over regions or spans of code. e.g: -`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`. - -Refer to trace2.h for details about all trace2 functions. +CPP wrapper macros are defined to hide most of these details. == Trace2 Target Formats @@ -685,8 +638,8 @@ The "exec_id" field is a command-unique id and is only useful if the `"thread_start"`:: This event is generated when a thread is started. It is - generated from *within* the new thread's thread-proc (for TLS - reasons). + generated from *within* the new thread's thread-proc (because + it needs to access data in the thread's thread-local storage). + ------------ { @@ -698,7 +651,7 @@ The "exec_id" field is a command-unique id and is only useful if the `"thread_exit"`:: This event is generated when a thread exits. It is generated - from *within* the thread's thread-proc (for TLS reasons). + from *within* the thread's thread-proc. + ------------ { @@ -717,6 +670,7 @@ The "exec_id" field is a command-unique id and is only useful if the { "event":"def_param", ... + "scope":"global", "param":"core.abbrev", "value":"7" } @@ -815,6 +769,73 @@ The "value" field may be an integer or a string. } ------------ +`"th_timer"`:: + This event logs the amount of time that a stopwatch timer was + running in the thread. This event is generated when a thread + exits for timers that requested per-thread events. ++ +------------ +{ + "event":"th_timer", + ... + "category":"my_category", + "name":"my_timer", + "intervals":5, # number of time it was started/stopped + "t_total":0.052741, # total time in seconds it was running + "t_min":0.010061, # shortest interval + "t_max":0.011648 # longest interval +} +------------ + +`"timer"`:: + This event logs the amount of time that a stopwatch timer was + running aggregated across all threads. This event is generated + when the process exits. ++ +------------ +{ + "event":"timer", + ... + "category":"my_category", + "name":"my_timer", + "intervals":5, # number of time it was started/stopped + "t_total":0.052741, # total time in seconds it was running + "t_min":0.010061, # shortest interval + "t_max":0.011648 # longest interval +} +------------ + +`"th_counter"`:: + This event logs the value of a counter variable in a thread. + This event is generated when a thread exits for counters that + requested per-thread events. ++ +------------ +{ + "event":"th_counter", + ... + "category":"my_category", + "name":"my_counter", + "count":23 +} +------------ + +`"counter"`:: + This event logs the value of a counter variable across all threads. + This event is generated when the process exits. The total value + reported here is the sum across all threads. ++ +------------ +{ + "event":"counter", + ... + "category":"my_category", + "name":"my_counter", + "count":23 +} +------------ + + == Example Trace2 API Usage Here is a hypothetical usage of the Trace2 API showing the intended @@ -1205,7 +1226,100 @@ worked on 508 items at offset 2032. Thread "th04" worked on 508 items at offset 508. + This example also shows that thread names are assigned in a racy manner -as each thread starts and allocates TLS storage. +as each thread starts. + +Config (def param) Events:: + + Dump "interesting" config values to trace2 log. ++ +We can optionally emit configuration events, see +`trace2.configparams` in linkgit:git-config[1] for how to enable +it. ++ +---------------- +$ git config --system color.ui never +$ git config --global color.ui always +$ git config --local color.ui auto +$ git config --list --show-scope | grep 'color.ui' +system color.ui=never +global color.ui=always +local color.ui=auto +---------------- ++ +Then, mark the config `color.ui` as "interesting" config with +`GIT_TRACE2_CONFIG_PARAMS`: ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ export GIT_TRACE2_CONFIG_PARAMS=color.ui +$ git version +... +$ cat ~/log.perf +d0 | main | version | | | | | ... +d0 | main | start | | 0.001642 | | | /usr/local/bin/git version +d0 | main | cmd_name | | | | | version (version) +d0 | main | def_param | | | | scope:system | color.ui:never +d0 | main | def_param | | | | scope:global | color.ui:always +d0 | main | def_param | | | | scope:local | color.ui:auto +d0 | main | data | r0 | 0.002100 | 0.002100 | fsync | fsync/writeout-only:0 +d0 | main | data | r0 | 0.002126 | 0.002126 | fsync | fsync/hardware-flush:0 +d0 | main | exit | | 0.000470 | | | code:0 +d0 | main | atexit | | 0.000477 | | | code:0 +---------------- + +Stopwatch Timer Events:: + + Measure the time spent in a function call or span of code + that might be called from many places within the code + throughout the life of the process. ++ +---------------- +static void expensive_function(void) +{ + trace2_timer_start(TRACE2_TIMER_ID_TEST1); + ... + sleep_millisec(1000); // Do something expensive + ... + trace2_timer_stop(TRACE2_TIMER_ID_TEST1); +} + +static int ut_100timer(int argc, const char **argv) +{ + ... + + expensive_function(); + + // Do something else 1... + + expensive_function(); + + // Do something else 2... + + expensive_function(); + + return 0; +} +---------------- ++ +In this example, we measure the total time spent in +`expensive_function()` regardless of when it is called +in the overall flow of the program. ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ t/helper/test-tool trace2 100timer 3 1000 +... +$ cat ~/log.perf +d0 | main | version | | | | | ... +d0 | main | start | | 0.001453 | | | t/helper/test-tool trace2 100timer 3 1000 +d0 | main | cmd_name | | | | | trace2 (trace2) +d0 | main | exit | | 3.003667 | | | code:0 +d0 | main | timer | | | | test | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929 +d0 | main | atexit | | 3.003796 | | | code:0 +---------------- + == Future Work diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt index 04b3ec2..f5d2009 100644 --- a/Documentation/technical/bitmap-format.txt +++ b/Documentation/technical/bitmap-format.txt @@ -25,9 +25,9 @@ An object is uniquely described by its bit position within a bitmap: is defined as follows: o1 <= o2 <==> pack(o1) <= pack(o2) /\ offset(o1) <= offset(o2) - - The ordering between packs is done according to the MIDX's .rev file. - Notably, the preferred pack sorts ahead of all other packs. ++ +The ordering between packs is done according to the MIDX's .rev file. +Notably, the preferred pack sorts ahead of all other packs. The on-disk representation (described below) of a bitmap is the same regardless of whether or not that bitmap belongs to a packfile or a MIDX. The only @@ -39,97 +39,119 @@ MIDXs, both the bit-cache and rev-cache extensions are required. == On-disk format - - A header appears at the beginning: - - 4-byte signature: {'B', 'I', 'T', 'M'} - - 2-byte version number (network byte order) - The current implementation only supports version 1 - of the bitmap index (the same one as JGit). - - 2-byte flags (network byte order) - - The following flags are supported: - - - BITMAP_OPT_FULL_DAG (0x1) REQUIRED - This flag must always be present. It implies that the - bitmap index has been generated for a packfile or - multi-pack index (MIDX) with full closure (i.e. where - every single object in the packfile/MIDX can find its - parent links inside the same packfile/MIDX). This is a - requirement for the bitmap index format, also present in - JGit, that greatly reduces the complexity of the - implementation. - - - BITMAP_OPT_HASH_CACHE (0x4) - If present, the end of the bitmap file contains - `N` 32-bit name-hash values, one per object in the - pack/MIDX. The format and meaning of the name-hash is - described below. - - 4-byte entry count (network byte order) - - The total count of entries (bitmapped commits) in this bitmap index. - - 20-byte checksum - - The SHA1 checksum of the pack/MIDX this bitmap index - belongs to. - - - 4 EWAH bitmaps that act as type indexes - - Type indexes are serialized after the hash cache in the shape - of four EWAH bitmaps stored consecutively (see Appendix A for - the serialization format of an EWAH bitmap). - - There is a bitmap for each Git object type, stored in the following - order: - - - Commits - - Trees - - Blobs - - Tags - - In each bitmap, the `n`th bit is set to true if the `n`th object - in the packfile or multi-pack index is of that type. - - The obvious consequence is that the OR of all 4 bitmaps will result - in a full set (all bits set), and the AND of all 4 bitmaps will - result in an empty bitmap (no bits set). - - - N entries with compressed bitmaps, one for each indexed commit - - Where `N` is the total amount of entries in this bitmap index. - Each entry contains the following: - - - 4-byte object position (network byte order) - The position **in the index for the packfile or - multi-pack index** where the bitmap for this commit is - found. - - - 1-byte XOR-offset - The xor offset used to compress this bitmap. For an entry - in position `x`, a XOR offset of `y` means that the actual - bitmap representing this commit is composed by XORing the - bitmap for this entry with the bitmap in entry `x-y` (i.e. - the bitmap `y` entries before this one). - - Note that this compression can be recursive. In order to - XOR this entry with a previous one, the previous entry needs - to be decompressed first, and so on. - - The hard-limit for this offset is 160 (an entry can only be - xor'ed against one of the 160 entries preceding it). This - number is always positive, and hence entries are always xor'ed - with **previous** bitmaps, not bitmaps that will come afterwards - in the index. - - - 1-byte flags for this bitmap - At the moment the only available flag is `0x1`, which hints - that this bitmap can be re-used when rebuilding bitmap indexes - for the repository. - - - The compressed bitmap itself, see Appendix A. + * A header appears at the beginning: + + 4-byte signature: :: {'B', 'I', 'T', 'M'} + + 2-byte version number (network byte order): :: + + The current implementation only supports version 1 + of the bitmap index (the same one as JGit). + + 2-byte flags (network byte order): :: + + The following flags are supported: + + ** {empty} + BITMAP_OPT_FULL_DAG (0x1) REQUIRED: ::: + + This flag must always be present. It implies that the + bitmap index has been generated for a packfile or + multi-pack index (MIDX) with full closure (i.e. where + every single object in the packfile/MIDX can find its + parent links inside the same packfile/MIDX). This is a + requirement for the bitmap index format, also present in + JGit, that greatly reduces the complexity of the + implementation. + + ** {empty} + BITMAP_OPT_HASH_CACHE (0x4): ::: + + If present, the end of the bitmap file contains + `N` 32-bit name-hash values, one per object in the + pack/MIDX. The format and meaning of the name-hash is + described below. + + ** {empty} + BITMAP_OPT_LOOKUP_TABLE (0x10): ::: + If present, the end of the bitmap file contains a table + containing a list of `N` <commit_pos, offset, xor_row> + triplets. The format and meaning of the table is described + below. ++ +NOTE: Unlike the xor_offset used to compress an individual bitmap, +`xor_row` stores an *absolute* index into the lookup table, not a location +relative to the current entry. + + 4-byte entry count (network byte order): :: + The total count of entries (bitmapped commits) in this bitmap index. + + 20-byte checksum: :: + The SHA1 checksum of the pack/MIDX this bitmap index + belongs to. + + * 4 EWAH bitmaps that act as type indexes ++ +Type indexes are serialized after the hash cache in the shape +of four EWAH bitmaps stored consecutively (see Appendix A for +the serialization format of an EWAH bitmap). ++ +There is a bitmap for each Git object type, stored in the following +order: ++ + - Commits + - Trees + - Blobs + - Tags + ++ +In each bitmap, the `n`th bit is set to true if the `n`th object +in the packfile or multi-pack index is of that type. ++ +The obvious consequence is that the OR of all 4 bitmaps will result +in a full set (all bits set), and the AND of all 4 bitmaps will +result in an empty bitmap (no bits set). + + * N entries with compressed bitmaps, one for each indexed commit ++ +Where `N` is the total number of entries in this bitmap index. +Each entry contains the following: + + ** {empty} + 4-byte object position (network byte order): :: + The position **in the index for the packfile or + multi-pack index** where the bitmap for this commit is + found. + + ** {empty} + 1-byte XOR-offset: :: + The xor offset used to compress this bitmap. For an entry + in position `x`, an XOR offset of `y` means that the actual + bitmap representing this commit is composed by XORing the + bitmap for this entry with the bitmap in entry `x-y` (i.e. + the bitmap `y` entries before this one). ++ +NOTE: This compression can be recursive. In order to +XOR this entry with a previous one, the previous entry needs +to be decompressed first, and so on. ++ +The hard-limit for this offset is 160 (an entry can only be +xor'ed against one of the 160 entries preceding it). This +number is always positive, and hence entries are always xor'ed +with **previous** bitmaps, not bitmaps that will come afterwards +in the index. + + ** {empty} + 1-byte flags for this bitmap: :: + At the moment the only available flag is `0x1`, which hints + that this bitmap can be re-used when rebuilding bitmap indexes + for the repository. + + ** The compressed bitmap itself, see Appendix A. + + * {empty} + TRAILER: :: + Trailing checksum of the preceding contents. == Appendix A: Serialization format for an EWAH bitmap @@ -142,8 +164,8 @@ implementation: - 4-byte number of words of the COMPRESSED bitmap, when stored - N x 8-byte words, as specified by the previous field - - This is the actual content of the compressed bitmap. ++ +This is the actual content of the compressed bitmap. - 4-byte position of the current RLW for the compressed bitmap @@ -205,3 +227,31 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag. If implementations want to choose a different hashing scheme, they are free to do so, but MUST allocate a new header flag (because comparing hashes made under two different schemes would be pointless). + +Commit lookup table +------------------- + +If the BITMAP_OPT_LOOKUP_TABLE flag is set, the last `N * (4 + 8 + 4)` +bytes (preceding the name-hash cache and trailing hash) of the `.bitmap` +file contains a lookup table specifying the information needed to get +the desired bitmap from the entries without parsing previous unnecessary +bitmaps. + +For a `.bitmap` containing `nr_entries` reachability bitmaps, the table +contains a list of `nr_entries` <commit_pos, offset, xor_row> triplets +(sorted in the ascending order of `commit_pos`). The content of the i'th +triplet is - + + * {empty} + commit_pos (4 byte integer, network byte order): :: + It stores the object position of a commit (in the midx or pack + index). + + * {empty} + offset (8 byte integer, network byte order): :: + The offset from which that commit's bitmap can be read. + + * {empty} + xor_row (4 byte integer, network byte order): :: + The position of the triplet whose bitmap is used to compress + this one, or `0xffffffff` if no such bitmap exists. diff --git a/Documentation/technical/bundle-uri.txt b/Documentation/technical/bundle-uri.txt new file mode 100644 index 0000000..91d3a13 --- /dev/null +++ b/Documentation/technical/bundle-uri.txt @@ -0,0 +1,572 @@ +Bundle URIs +=========== + +Git bundles are files that store a pack-file along with some extra metadata, +including a set of refs and a (possibly empty) set of necessary commits. See +linkgit:git-bundle[1] and linkgit:gitformat-bundle[5] for more information. + +Bundle URIs are locations where Git can download one or more bundles in +order to bootstrap the object database in advance of fetching the remaining +objects from a remote. + +One goal is to speed up clones and fetches for users with poor network +connectivity to the origin server. Another benefit is to allow heavy users, +such as CI build farms, to use local resources for the majority of Git data +and thereby reducing the load on the origin server. + +To enable the bundle URI feature, users can specify a bundle URI using +command-line options or the origin server can advertise one or more URIs +via a protocol v2 capability. + +Design Goals +------------ + +The bundle URI standard aims to be flexible enough to satisfy multiple +workloads. The bundle provider and the Git client have several choices in +how they create and consume bundle URIs. + +* Bundles can have whatever name the server desires. This name could refer + to immutable data by using a hash of the bundle contents. However, this + means that a new URI will be needed after every update of the content. + This might be acceptable if the server is advertising the URI (and the + server is aware of new bundles being generated) but would not be + ergonomic for users using the command line option. + +* The bundles could be organized specifically for bootstrapping full + clones, but could also be organized with the intention of bootstrapping + incremental fetches. The bundle provider must decide on one of several + organization schemes to minimize client downloads during incremental + fetches, but the Git client can also choose whether to use bundles for + either of these operations. + +* The bundle provider can choose to support full clones, partial clones, + or both. The client can detect which bundles are appropriate for the + repository's partial clone filter, if any. + +* The bundle provider can use a single bundle (for clones only), or a + list of bundles. When using a list of bundles, the provider can specify + whether or not the client needs _all_ of the bundle URIs for a full + clone, or if _any_ one of the bundle URIs is sufficient. This allows the + bundle provider to use different URIs for different geographies. + +* The bundle provider can organize the bundles using heuristics, such as + creation tokens, to help the client prevent downloading bundles it does + not need. When the bundle provider does not provide these heuristics, + the client can use optimizations to minimize how much of the data is + downloaded. + +* The bundle provider does not need to be associated with the Git server. + The client can choose to use the bundle provider without it being + advertised by the Git server. + +* The client can choose to discover bundle providers that are advertised + by the Git server. This could happen during `git clone`, during + `git fetch`, both, or neither. The user can choose which combination + works best for them. + +* The client can choose to configure a bundle provider manually at any + time. The client can also choose to specify a bundle provider manually + as a command-line option to `git clone`. + +Each repository is different and every Git server has different needs. +Hopefully the bundle URI feature is flexible enough to satisfy all needs. +If not, then the feature can be extended through its versioning mechanism. + +Server requirements +------------------- + +To provide a server-side implementation of bundle servers, no other parts +of the Git protocol are required. This allows server maintainers to use +static content solutions such as CDNs in order to serve the bundle files. + +At the current scope of the bundle URI feature, all URIs are expected to +be HTTP(S) URLs where content is downloaded to a local file using a `GET` +request to that URL. The server could include authentication requirements +to those requests with the aim of triggering the configured credential +helper for secure access. (Future extensions could use "file://" URIs or +SSH URIs.) + +Assuming a `200 OK` response from the server, the content at the URL is +inspected. First, Git attempts to parse the file as a bundle file of +version 2 or higher. If the file is not a bundle, then the file is parsed +as a plain-text file using Git's config parser. The key-value pairs in +that config file are expected to describe a list of bundle URIs. If +neither of these parse attempts succeed, then Git will report an error to +the user that the bundle URI provided erroneous data. + +Any other data provided by the server is considered erroneous. + +Bundle Lists +------------ + +The Git server can advertise bundle URIs using a set of `key=value` pairs. +A bundle URI can also serve a plain-text file in the Git config format +containing these same `key=value` pairs. In both cases, we consider this +to be a _bundle list_. The pairs specify information about the bundles +that the client can use to make decisions for which bundles to download +and which to ignore. + +A few keys focus on properties of the list itself. + +bundle.version:: + (Required) This value provides a version number for the bundle + list. If a future Git change enables a feature that needs the Git + client to react to a new key in the bundle list file, then this version + will increment. The only current version number is 1, and if any other + value is specified then Git will fail to use this file. + +bundle.mode:: + (Required) This value has one of two values: `all` and `any`. When `all` + is specified, then the client should expect to need all of the listed + bundle URIs that match their repository's requirements. When `any` is + specified, then the client should expect that any one of the bundle URIs + that match their repository's requirements will suffice. Typically, the + `any` option is used to list a number of different bundle servers + located in different geographies. + +bundle.heuristic:: + If this string-valued key exists, then the bundle list is designed to + work well with incremental `git fetch` commands. The heuristic signals + that there are additional keys available for each bundle that help + determine which subset of bundles the client should download. The only + heuristic currently planned is `creationToken`. + +The remaining keys include an `<id>` segment which is a server-designated +name for each available bundle. The `<id>` must contain only alphanumeric +and `-` characters. + +bundle.<id>.uri:: + (Required) This string value is the URI for downloading bundle `<id>`. + If the URI begins with a protocol (`http://` or `https://`) then the URI + is absolute. Otherwise, the URI is interpreted as relative to the URI + used for the bundle list. If the URI begins with `/`, then that relative + path is relative to the domain name used for the bundle list. (This use + of relative paths is intended to make it easier to distribute a set of + bundles across a large number of servers or CDNs with different domain + names.) + +bundle.<id>.filter:: + This string value represents an object filter that should also appear in + the header of this bundle. The server uses this value to differentiate + different kinds of bundles from which the client can choose those that + match their object filters. + +bundle.<id>.creationToken:: + This value is a nonnegative 64-bit integer used for sorting the bundles + list. This is used to download a subset of bundles during a fetch when + `bundle.heuristic=creationToken`. + +bundle.<id>.location:: + This string value advertises a real-world location from where the bundle + URI is served. This can be used to present the user with an option for + which bundle URI to use or simply as an informative indicator of which + bundle URI was selected by Git. This is only valuable when + `bundle.mode` is `any`. + +Here is an example bundle list using the Git config format: + + [bundle] + version = 1 + mode = all + heuristic = creationToken + + [bundle "2022-02-09-1644442601-daily"] + uri = https://bundles.example.com/git/git/2022-02-09-1644442601-daily.bundle + creationToken = 1644442601 + + [bundle "2022-02-02-1643842562"] + uri = https://bundles.example.com/git/git/2022-02-02-1643842562.bundle + creationToken = 1643842562 + + [bundle "2022-02-09-1644442631-daily-blobless"] + uri = 2022-02-09-1644442631-daily-blobless.bundle + creationToken = 1644442631 + filter = blob:none + + [bundle "2022-02-02-1643842568-blobless"] + uri = /git/git/2022-02-02-1643842568-blobless.bundle + creationToken = 1643842568 + filter = blob:none + +This example uses `bundle.mode=all` as well as the +`bundle.<id>.creationToken` heuristic. It also uses the `bundle.<id>.filter` +options to present two parallel sets of bundles: one for full clones and +another for blobless partial clones. + +Suppose that this bundle list was found at the URI +`https://bundles.example.com/git/git/` and so the two blobless bundles have +the following fully-expanded URIs: + +* `https://bundles.example.com/git/git/2022-02-09-1644442631-daily-blobless.bundle` +* `https://bundles.example.com/git/git/2022-02-02-1643842568-blobless.bundle` + +Advertising Bundle URIs +----------------------- + +If a user knows a bundle URI for the repository they are cloning, then +they can specify that URI manually through a command-line option. However, +a Git host may want to advertise bundle URIs during the clone operation, +helping users unaware of the feature. + +The only thing required for this feature is that the server can advertise +one or more bundle URIs. This advertisement takes the form of a new +protocol v2 capability specifically for discovering bundle URIs. + +The client could choose an arbitrary bundle URI as an option _or_ select +the URI with best performance by some exploratory checks. It is up to the +bundle provider to decide if having multiple URIs is preferable to a +single URI that is geodistributed through server-side infrastructure. + +Cloning with Bundle URIs +------------------------ + +The primary need for bundle URIs is to speed up clones. The Git client +will interact with bundle URIs according to the following flow: + +1. The user specifies a bundle URI with the `--bundle-uri` command-line + option _or_ the client discovers a bundle list advertised by the + Git server. + +2. If the downloaded data from a bundle URI is a bundle, then the client + inspects the bundle headers to check that the prerequisite commit OIDs + are present in the client repository. If some are missing, then the + client delays unbundling until other bundles have been unbundled, + making those OIDs present. When all required OIDs are present, the + client unbundles that data using a refspec. The default refspec is + `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs + are stored so that later `git fetch` negotiations can communicate each + bundled ref as a `have`, reducing the size of the fetch over the Git + protocol. To allow pruning refs from this ref namespace, Git may + introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that + stale bundle refs can be deleted. + +3. If the file is instead a bundle list, then the client inspects the + `bundle.mode` to see if the list is of the `all` or `any` form. + + a. If `bundle.mode=all`, then the client considers all bundle + URIs. The list is reduced based on the `bundle.<id>.filter` options + matching the client repository's partial clone filter. Then, all + bundle URIs are requested. If the `bundle.<id>.creationToken` + heuristic is provided, then the bundles are downloaded in decreasing + order by the creation token, stopping when a bundle has all required + OIDs. The bundles can then be unbundled in increasing creation token + order. The client stores the latest creation token as a heuristic + for avoiding future downloads if the bundle list does not advertise + bundles with larger creation tokens. + + b. If `bundle.mode=any`, then the client can choose any one of the + bundle URIs to inspect. The client can use a variety of ways to + choose among these URIs. The client can also fallback to another URI + if the initial choice fails to return a result. + +Note that during a clone we expect that all bundles will be required, and +heuristics such as `bundle.<uri>.creationToken` can be used to download +bundles in chronological order or in parallel. + +If a given bundle URI is a bundle list with a `bundle.heuristic` +value, then the client can choose to store that URI as its chosen bundle +URI. The client can then navigate directly to that URI during later `git +fetch` calls. + +When downloading bundle URIs, the client can choose to inspect the initial +content before committing to downloading the entire content. This may +provide enough information to determine if the URI is a bundle list or +a bundle. In the case of a bundle, the client may inspect the bundle +header to determine that all advertised tips are already in the client +repository and cancel the remaining download. + +Fetching with Bundle URIs +------------------------- + +When the client fetches new data, it can decide to fetch from bundle +servers before fetching from the origin remote. This could be done via a +command-line option, but it is more likely useful to use a config value +such as the one specified during the clone. + +The fetch operation follows the same procedure to download bundles from a +bundle list (although we do _not_ want to use parallel downloads here). We +expect that the process will end when all prerequisite commit OIDs in a +thin bundle are already in the object database. + +When using the `creationToken` heuristic, the client can avoid downloading +any bundles if their creation tokens are not larger than the stored +creation token. After fetching new bundles, Git updates this local +creation token. + +If the bundle provider does not provide a heuristic, then the client +should attempt to inspect the bundle headers before downloading the full +bundle data in case the bundle tips already exist in the client +repository. + +Error Conditions +---------------- + +If the Git client discovers something unexpected while downloading +information according to a bundle URI or the bundle list found at that +location, then Git can ignore that data and continue as if it was not +given a bundle URI. The remote Git server is the ultimate source of truth, +not the bundle URI. + +Here are a few example error conditions: + +* The client fails to connect with a server at the given URI or a connection + is lost without any chance to recover. + +* The client receives a 400-level response (such as `404 Not Found` or + `401 Not Authorized`). The client should use the credential helper to + find and provide a credential for the URI, but match the semantics of + Git's other HTTP protocols in terms of handling specific 400-level + errors. + +* The server reports any other failure response. + +* The client receives data that is not parsable as a bundle or bundle list. + +* A bundle includes a filter that does not match expectations. + +* The client cannot unbundle the bundles because the prerequisite commit OIDs + are not in the object database and there are no more bundles to download. + +There are also situations that could be seen as wasteful, but are not +error conditions: + +* The downloaded bundles contain more information than is requested by + the clone or fetch request. A primary example is if the user requests + a clone with `--single-branch` but downloads bundles that store every + reachable commit from all `refs/heads/*` references. This might be + initially wasteful, but perhaps these objects will become reachable by + a later ref update that the client cares about. + +* A bundle download during a `git fetch` contains objects already in the + object database. This is probably unavoidable if we are using bundles + for fetches, since the client will almost always be slightly ahead of + the bundle servers after performing its "catch-up" fetch to the remote + server. This extra work is most wasteful when the client is fetching + much more frequently than the server is computing bundles, such as if + the client is using hourly prefetches with background maintenance, but + the server is computing bundles weekly. For this reason, the client + should not use bundle URIs for fetch unless the server has explicitly + recommended it through a `bundle.heuristic` value. + +Example Bundle Provider organization +------------------------------------ + +The bundle URI feature is intentionally designed to be flexible to +different ways a bundle provider wants to organize the object data. +However, it can be helpful to have a complete organization model described +here so providers can start from that base. + +This example organization is a simplified model of what is used by the +GVFS Cache Servers (see section near the end of this document) which have +been beneficial in speeding up clones and fetches for very large +repositories, although using extra software outside of Git. + +The bundle provider deploys servers across multiple geographies. Each +server manages its own bundle set. The server can track a number of Git +repositories, but provides a bundle list for each based on a pattern. For +example, when mirroring a repository at `https://<domain>/<org>/<repo>` +the bundle server could have its bundle list available at +`https://<server-url>/<domain>/<org>/<repo>`. The origin Git server can +list all of these servers under the "any" mode: + + [bundle] + version = 1 + mode = any + + [bundle "eastus"] + uri = https://eastus.example.com/<domain>/<org>/<repo> + + [bundle "europe"] + uri = https://europe.example.com/<domain>/<org>/<repo> + + [bundle "apac"] + uri = https://apac.example.com/<domain>/<org>/<repo> + +This "list of lists" is static and only changes if a bundle server is +added or removed. + +Each bundle server manages its own set of bundles. The initial bundle list +contains only a single bundle, containing all of the objects received from +cloning the repository from the origin server. The list uses the +`creationToken` heuristic and a `creationToken` is made for the bundle +based on the server's timestamp. + +The bundle server runs regularly-scheduled updates for the bundle list, +such as once a day. During this task, the server fetches the latest +contents from the origin server and generates a bundle containing the +objects reachable from the latest origin refs, but not contained in a +previously-computed bundle. This bundle is added to the list, with care +that the `creationToken` is strictly greater than the previous maximum +`creationToken`. + +When the bundle list grows too large, say more than 30 bundles, then the +oldest "_N_ minus 30" bundles are combined into a single bundle. This +bundle's `creationToken` is equal to the maximum `creationToken` among the +merged bundles. + +An example bundle list is provided here, although it only has two daily +bundles and not a full list of 30: + + [bundle] + version = 1 + mode = all + heuristic = creationToken + + [bundle "2022-02-13-1644770820-daily"] + uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-09-1644770820-daily.bundle + creationToken = 1644770820 + + [bundle "2022-02-09-1644442601-daily"] + uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-09-1644442601-daily.bundle + creationToken = 1644442601 + + [bundle "2022-02-02-1643842562"] + uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-02-1643842562.bundle + creationToken = 1643842562 + +To avoid storing and serving object data in perpetuity despite becoming +unreachable in the origin server, this bundle merge can be more careful. +Instead of taking an absolute union of the old bundles, instead the bundle +can be created by looking at the newer bundles and ensuring that their +necessary commits are all available in this merged bundle (or in another +one of the newer bundles). This allows "expiring" object data that is not +being used by new commits in this window of time. That data could be +reintroduced by a later push. + +The intention of this data organization has two main goals. First, initial +clones of the repository become faster by downloading precomputed object +data from a closer source. Second, `git fetch` commands can be faster, +especially if the client has not fetched for a few days. However, if a +client does not fetch for 30 days, then the bundle list organization would +cause redownloading a large amount of object data. + +One way to make this organization more useful to users who fetch frequently +is to have more frequent bundle creation. For example, bundles could be +created every hour, and then once a day those "hourly" bundles could be +merged into a "daily" bundle. The daily bundles are merged into the +oldest bundle after 30 days. + +It is recommended that this bundle strategy is repeated with the `blob:none` +filter if clients of this repository are expecting to use blobless partial +clones. This list of blobless bundles stays in the same list as the full +bundles, but uses the `bundle.<id>.filter` key to separate the two groups. +For very large repositories, the bundle provider may want to _only_ provide +blobless bundles. + +Implementation Plan +------------------- + +This design document is being submitted on its own as an aspirational +document, with the goal of implementing all of the mentioned client +features over the course of several patch series. Here is a potential +outline for submitting these features: + +1. Integrate bundle URIs into `git clone` with a `--bundle-uri` option. + This will include a new `git fetch --bundle-uri` mode for use as the + implementation underneath `git clone`. The initial version here will + expect a single bundle at the given URI. + +2. Implement the ability to parse a bundle list from a bundle URI and + update the `git fetch --bundle-uri` logic to properly distinguish + between `bundle.mode` options. Specifically design the feature so + that the config format parsing feeds a list of key-value pairs into the + bundle list logic. + +3. Create the `bundle-uri` protocol v2 command so Git servers can advertise + bundle URIs using the key-value pairs. Plug into the existing key-value + input to the bundle list logic. Allow `git clone` to discover these + bundle URIs and bootstrap the client repository from the bundle data. + (This choice is an opt-in via a config option and a command-line + option.) + +4. Allow the client to understand the `bundle.heuristic` configuration key + and the `bundle.<id>.creationToken` heuristic. When `git clone` + discovers a bundle URI with `bundle.heuristic`, it configures the client + repository to check that bundle URI during later `git fetch <remote>` + commands. + +5. Allow clients to discover bundle URIs during `git fetch` and configure + a bundle URI for later fetches if `bundle.heuristic` is set. + +6. Implement the "inspect headers" heuristic to reduce data downloads when + the `bundle.<id>.creationToken` heuristic is not available. + +As these features are reviewed, this plan might be updated. We also expect +that new designs will be discovered and implemented as this feature +matures and becomes used in real-world scenarios. + +Related Work: Packfile URIs +--------------------------- + +The Git protocol already has a capability where the Git server can list +a set of URLs along with the packfile response when serving a client +request. The client is then expected to download the packfiles at those +locations in order to have a complete understanding of the response. + +This mechanism is used by the Gerrit server (implemented with JGit) and +has been effective at reducing CPU load and improving user performance for +clones. + +A major downside to this mechanism is that the origin server needs to know +_exactly_ what is in those packfiles, and the packfiles need to be available +to the user for some time after the server has responded. This coupling +between the origin and the packfile data is difficult to manage. + +Further, this implementation is extremely hard to make work with fetches. + +Related Work: GVFS Cache Servers +-------------------------------- + +The GVFS Protocol [2] is a set of HTTP endpoints designed independently of +the Git project before Git's partial clone was created. One feature of this +protocol is the idea of a "cache server" which can be colocated with build +machines or developer offices to transfer Git data without overloading the +central server. + +The endpoint that VFS for Git is famous for is the `GET /gvfs/objects/{oid}` +endpoint, which allows downloading an object on-demand. This is a critical +piece of the filesystem virtualization of that product. + +However, a more subtle need is the `GET /gvfs/prefetch?lastPackTimestamp=<t>` +endpoint. Given an optional timestamp, the cache server responds with a list +of precomputed packfiles containing the commits and trees that were introduced +in those time intervals. + +The cache server computes these "prefetch" packfiles using the following +strategy: + +1. Every hour, an "hourly" pack is generated with a given timestamp. +2. Nightly, the previous 24 hourly packs are rolled up into a "daily" pack. +3. Nightly, all prefetch packs more than 30 days old are rolled up into + one pack. + +When a user runs `gvfs clone` or `scalar clone` against a repo with cache +servers, the client requests all prefetch packfiles, which is at most +`24 + 30 + 1` packfiles downloading only commits and trees. The client +then follows with a request to the origin server for the references, and +attempts to checkout that tip reference. (There is an extra endpoint that +helps get all reachable trees from a given commit, in case that commit +was not already in a prefetch packfile.) + +During a `git fetch`, a hook requests the prefetch endpoint using the +most-recent timestamp from a previously-downloaded prefetch packfile. +Only the list of packfiles with later timestamps are downloaded. Most +users fetch hourly, so they get at most one hourly prefetch pack. Users +whose machines have been off or otherwise have not fetched in over 30 days +might redownload all prefetch packfiles. This is rare. + +It is important to note that the clients always contact the origin server +for the refs advertisement, so the refs are frequently "ahead" of the +prefetched pack data. The missing objects are downloaded on-demand using +the `GET gvfs/objects/{oid}` requests, when needed by a command such as +`git checkout` or `git log`. Some Git optimizations disable checks that +would cause these on-demand downloads to be too aggressive. + +See Also +-------- + +[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/ + An earlier RFC for a bundle URI feature. + +[2] https://github.com/microsoft/VFSForGit/blob/master/Protocol.md + The GVFS Protocol diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index f05e7bd..2c26e95 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -1,4 +1,4 @@ -Git Commit Graph Design Notes +Git Commit-Graph Design Notes ============================= Git walks the commit graph for many reasons, including: @@ -17,7 +17,7 @@ There are two main costs here: The commit-graph file is a supplemental data structure that accelerates commit graph walks. If a user downgrades or disables the 'core.commitGraph' -config setting, then the existing ODB is sufficient. The file is stored +config setting, then the existing object database is sufficient. The file is stored as "commit-graph" either in the .git/objects/info directory or in the info directory of an alternate. @@ -40,7 +40,7 @@ Values 1-4 satisfy the requirements of parse_commit_gently(). There are two definitions of generation number: 1. Corrected committer dates (generation number v2) -2. Topological levels (generation nummber v1) +2. Topological levels (generation number v1) Define "corrected committer date" of a commit recursively as follows: @@ -48,7 +48,7 @@ Define "corrected committer date" of a commit recursively as follows: equal to its committer date. * A commit with at least one parent has corrected committer date equal to - the maximum of its commiter date and one more than the largest corrected + the maximum of its committer date and one more than the largest corrected committer date among its parents. * As a special case, a root commit with timestamp zero has corrected commit @@ -95,7 +95,7 @@ with default order), but is not used when the topological order is required (such as merge base calculations, "git log --graph"). In practice, we expect some commits to be created recently and not stored -in the commit graph. We can treat these commits as having "infinite" +in the commit-graph. We can treat these commits as having "infinite" generation number and walk until reaching commits with known generation number. @@ -136,7 +136,7 @@ Design Details - Commit grafts and replace objects can change the shape of the commit history. The latter can also be enabled/disabled on the fly using - `--no-replace-objects`. This leads to difficultly storing both possible + `--no-replace-objects`. This leads to difficulty storing both possible interpretations of a commit id, especially when computing generation numbers. The commit-graph will not be read or written when replace-objects or grafts are present. @@ -149,7 +149,7 @@ Design Details helpful for these clones, anyway. The commit-graph will not be read or written when shallow commits are present. -Commit Graphs Chains +Commit-Graphs Chains -------------------- Typically, repos grow with near-constant velocity (commits per day). Over time, diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/technical/cruft-packs.txt deleted file mode 100644 index d81f3a8..0000000 --- a/Documentation/technical/cruft-packs.txt +++ /dev/null @@ -1,123 +0,0 @@ -= Cruft packs - -The cruft packs feature offer an alternative to Git's traditional mechanism of -removing unreachable objects. This document provides an overview of Git's -pruning mechanism, and how a cruft pack can be used instead to accomplish the -same. - -== Background - -To remove unreachable objects from your repository, Git offers `git repack -Ad` -(see linkgit:git-repack[1]). Quoting from the documentation: - -[quote] -[...] unreachable objects in a previous pack become loose, unpacked objects, -instead of being left in the old pack. [...] loose unreachable objects will be -pruned according to normal expiry rules with the next 'git gc' invocation. - -Unreachable objects aren't removed immediately, since doing so could race with -an incoming push which may reference an object which is about to be deleted. -Instead, those unreachable objects are stored as loose objects and stay that way -until they are older than the expiration window, at which point they are removed -by linkgit:git-prune[1]. - -Git must store these unreachable objects loose in order to keep track of their -per-object mtimes. If these unreachable objects were written into one big pack, -then either freshening that pack (because an object contained within it was -re-written) or creating a new pack of unreachable objects would cause the pack's -mtime to get updated, and the objects within it would never leave the expiration -window. Instead, objects are stored loose in order to keep track of the -individual object mtimes and avoid a situation where all cruft objects are -freshened at once. - -This can lead to undesirable situations when a repository contains many -unreachable objects which have not yet left the grace period. Having large -directories in the shards of `.git/objects` can lead to decreased performance in -the repository. But given enough unreachable objects, this can lead to inode -starvation and degrade the performance of the whole system. Since we -can never pack those objects, these repositories often take up a large amount of -disk space, since we can only zlib compress them, but not store them in delta -chains. - -== Cruft packs - -A cruft pack eliminates the need for storing unreachable objects in a loose -state by including the per-object mtimes in a separate file alongside a single -pack containing all loose objects. - -A cruft pack is written by `git repack --cruft` when generating a new pack. -linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft` -is a classic all-into-one repack, meaning that everything in the resulting pack is -reachable, and everything else is unreachable. Once written, the `--cruft` -option instructs `git repack` to generate another pack containing only objects -not packed in the previous step (which equates to packing all unreachable -objects together). This progresses as follows: - - 1. Enumerate every object, marking any object which is (a) not contained in a - kept-pack, and (b) whose mtime is within the grace period as a traversal - tip. - - 2. Perform a reachability traversal based on the tips gathered in the previous - step, adding every object along the way to the pack. - - 3. Write the pack out, along with a `.mtimes` file that records the per-object - timestamps. - -This mode is invoked internally by linkgit:git-repack[1] when instructed to -write a cruft pack. Crucially, the set of in-core kept packs is exactly the set -of packs which will not be deleted by the repack; in other words, they contain -all of the repository's reachable objects. - -When a repository already has a cruft pack, `git repack --cruft` typically only -adds objects to it. An exception to this is when `git repack` is given the -`--cruft-expiration` option, which allows the generated cruft pack to omit -expired objects instead of waiting for linkgit:git-gc[1] to expire those objects -later on. - -It is linkgit:git-gc[1] that is typically responsible for removing expired -unreachable objects. - -== Caution for mixed-version environments - -Repositories that have cruft packs in them will continue to work with any older -version of Git. Note, however, that previous versions of Git which do not -understand the `.mtimes` file will use the cruft pack's mtime as the mtime for -all of the objects in it. In other words, do not expect older (pre-cruft pack) -versions of Git to interpret or even read the contents of the `.mtimes` file. - -Note that having mixed versions of Git GC-ing the same repository can lead to -unreachable objects never being completely pruned. This can happen under the -following circumstances: - - - An older version of Git running GC explodes the contents of an existing - cruft pack loose, using the cruft pack's mtime. - - A newer version running GC collects those loose objects into a cruft pack, - where the .mtime file reflects the loose object's actual mtimes, but the - cruft pack mtime is "now". - -Repeating this process will lead to unreachable objects not getting pruned as a -result of repeatedly resetting the objects' mtimes to the present time. - -If you are GC-ing repositories in a mixed version environment, consider omitting -the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and -leaving the `gc.cruftPacks` configuration unset until all writers understand -cruft packs. - -== Alternatives - -Notable alternatives to this design include: - - - The location of the per-object mtime data, and - - Storing unreachable objects in multiple cruft packs. - -On the location of mtime data, a new auxiliary file tied to the pack was chosen -to avoid complicating the `.idx` format. If the `.idx` format were ever to gain -support for optional chunks of data, it may make sense to consolidate the -`.mtimes` format into the `.idx` itself. - -Storing unreachable objects among multiple cruft packs (e.g., creating a new -cruft pack during each repacking operation including only unreachable objects -which aren't already stored in an earlier cruft pack) is significantly more -complicated to construct, and so aren't pursued here. The obvious drawback to -the current implementation is that the entire cruft pack must be re-written from -scratch. diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 260224b..ed57481 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -205,7 +205,7 @@ SHA-1 content. Object storage ~~~~~~~~~~~~~~ Loose objects use zlib compression and packed objects use the packed -format described in Documentation/technical/pack-format.txt, just like +format described in linkgit:gitformat-pack[5], just like today. The content that is compressed and stored uses SHA-256 content instead of SHA-1 content. @@ -562,7 +562,7 @@ hash re-encode during clone and to encourage peers to modernize. The design described here allows fetches by SHA-1 clients of a personal SHA-256 repository because it's not much more difficult than allowing pushes from that repository. This support needs to be guarded -by a configuration option --- servers like git.kernel.org that serve a +by a configuration option -- servers like git.kernel.org that serve a large number of clients would not be expected to bear that cost. Meaning of signatures diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt index aa0aa9a..6f33654 100644 --- a/Documentation/technical/long-running-process-protocol.txt +++ b/Documentation/technical/long-running-process-protocol.txt @@ -3,7 +3,7 @@ Long-running process protocol This protocol is used when Git needs to communicate with an external process throughout the entire life of a single Git command. All -communication is in pkt-line format (see technical/protocol-common.txt) +communication is in pkt-line format (see linkgit:gitprotocol-common[5]) over standard input and standard output. Handshake diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt index 1eb525f..9d453d4 100644 --- a/Documentation/technical/packfile-uri.txt +++ b/Documentation/technical/packfile-uri.txt @@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section directly before the `packfile` section (right after `wanted-refs` if it is sent) containing URIs of any of the given protocols. The URIs point to packfiles that use only features that the client has declared that it supports -(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of +(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of this section. Clients should then download and index all the given URIs (in addition to diff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt index e790258..b4a144e 100644 --- a/Documentation/technical/parallel-checkout.txt +++ b/Documentation/technical/parallel-checkout.txt @@ -56,14 +56,14 @@ Rejected Multi-Threaded Solution The most "straightforward" implementation would be to spread the set of to-be-updated cache entries across multiple threads. But due to the -thread-unsafe functions in the ODB code, we would have to use locks to +thread-unsafe functions in the object database code, we would have to use locks to coordinate the parallel operation. An early prototype of this solution showed that the multi-threaded checkout would bring performance improvements over the sequential code, but there was still too much lock contention. A `perf` profiling indicated that around 20% of the runtime during a local Linux clone (on an SSD) was spent in locking functions. For this reason this approach was rejected in favor of using multiple -child processes, which led to a better performance. +child processes, which led to better performance. Multi-Process Solution ---------------------- @@ -126,7 +126,7 @@ Then, for each assigned item, each worker: * W5: Writes the result to the file descriptor opened at W2. -* W6: Calls `fstat()` or lstat()` on the just-written path, and sends +* W6: Calls `fstat()` or `lstat()` on the just-written path, and sends the result back to the main process, together with the end status of the operation and the item's identification number. @@ -148,7 +148,7 @@ information, the main process handles the results in two steps: - First, it updates the in-memory index with the `lstat()` information sent by the workers. (This must be done first as this information - might me required in the following step.) + might be required in the following step.) - Then it writes the items which collided on disk (i.e. items marked with `PC_ITEM_COLLIDED`). More on this below. @@ -185,7 +185,7 @@ quite straightforward: for each parallel-eligible entry, the main process must remove all files that prevent this entry from being written (before enqueueing it). This includes any non-directory file in the leading path of the entry. Later, when a worker gets assigned the entry, -it looks again for the non-directories files and for an already existing +it looks again for the non-directory files and for an already existing file at the entry's path. If any of these checks finds something, the worker knows that there was a path collision. @@ -232,7 +232,7 @@ conversion and re-encoding, are eligible for parallel checkout. Ineligible entries are checked out by the classic sequential codepath *before* spawning workers. -Note: submodules's files are also eligible for parallel checkout (as +Note: submodules' files are also eligible for parallel checkout (as long as they don't fall into any of the excluding categories mentioned above). But since each submodule is checked out in its own child process, we don't mix the superproject's and the submodules' files in diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 99f0eb3..cd948b0 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -3,7 +3,7 @@ Partial Clone Design Notes The "Partial Clone" feature is a performance optimization for Git that allows Git to function without having a complete copy of the repository. -The goal of this work is to allow Git better handle extremely large +The goal of this work is to allow Git to better handle extremely large repositories. During clone and fetch operations, Git downloads the complete contents @@ -79,7 +79,7 @@ Design Details upload-pack negotiation. + This uses the existing capability discovery mechanism. -See "filter" in Documentation/technical/pack-protocol.txt. +See "filter" in linkgit:gitprotocol-pack[5]. - Clients pass a "filter-spec" to clone and fetch which is passed to the server to request filtering during packfile construction. @@ -256,7 +256,7 @@ remote in a specific order. - Dynamic object fetching currently uses the existing pack protocol V0 which means that each object is requested via fetch-pack. The server will send a full set of info/refs when the connection is established. - If there are large number of refs, this may incur significant overhead. + If there are a large number of refs, this may incur significant overhead. Future Work @@ -265,7 +265,7 @@ Future Work - Improve the way to specify the order in which promisor remotes are tried. + -For example this could allow to specify explicitly something like: +For example this could allow specifying explicitly something like: "When fetching from this remote, I want to use these promisor remotes in this order, though, when pushing or fetching to that remote, I want to use those promisor remotes in that order." @@ -322,7 +322,7 @@ Footnotes [a] expensive-to-modify list of missing objects: Earlier in the design of partial clone we discussed the need for a single list of missing objects. - This would essentially be a sorted linear list of OIDs that the were + This would essentially be a sorted linear list of OIDs that were omitted by the server during a clone or subsequent fetches. This file would need to be loaded into memory on every object lookup. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index ceda4bb..59bea66 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -11,7 +11,7 @@ write out the next tree object to be committed. The state is "virtual" in the sense that it does not necessarily have to, and often does not, match the files in the working tree. -There are cases Git needs to examine the differences between the +There are cases where Git needs to examine the differences between the virtual working tree state in the index and the files in the working tree. The most obvious case is when the user asks `git diff` (or its low level implementation, `git diff-files`) or @@ -165,9 +165,9 @@ Avoiding runtime penalty In order to avoid the above runtime penalty, post 1.4.2 Git used to have a code that made sure the index file -got timestamp newer than the youngest files in the index when -there are many young files with the same timestamp as the -resulting index file would otherwise would have by waiting +got a timestamp newer than the youngest files in the index when +there were many young files with the same timestamp as the +resulting index file otherwise would have by waiting before finishing writing the index file out. I suspected that in practice the situation where many paths in the @@ -190,7 +190,7 @@ In a large project where raciness avoidance cost really matters, however, the initial computation of all object names in the index takes more than one second, and the index file is written out after all that happens. Therefore the timestamp of the -index file will be more than one seconds later than the +index file will be more than one second later than the youngest file in the working tree. This means that in these cases there actually will not be any racily clean entry in the resulting index. diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt index 6a67cc4..dd0b37c 100644 --- a/Documentation/technical/reftable.txt +++ b/Documentation/technical/reftable.txt @@ -46,7 +46,7 @@ search lookup, and range scans. Storage in the file is organized into variable sized blocks. Prefix compression is used within a single block to reduce disk space. Block -size and alignment is tunable by the writer. +size and alignment are tunable by the writer. Performance ^^^^^^^^^^^ @@ -115,7 +115,7 @@ Varint encoding Varint encoding is identical to the ofs-delta encoding method used within pack files. -Decoder works such as: +Decoder works as follows: .... val = buf[ptr] & 0x7f @@ -175,7 +175,7 @@ log_index* footer .... -in a log-only file the first log block immediately follows the file +In a log-only file, the first log block immediately follows the file header, without padding to block alignment. Block size @@ -247,7 +247,7 @@ uint32( hash_id ) .... The header is identical to `version_number=1`, with the 4-byte hash ID -("sha1" for SHA1 and "s256" for SHA-256) append to the header. +("sha1" for SHA1 and "s256" for SHA-256) appended to the header. For maximum backward compatibility, it is recommended to use version 1 when writing SHA1 reftables. @@ -288,7 +288,7 @@ The 2-byte `restart_count` stores the number of entries in the `restart_count` to binary search between restarts before starting a linear scan. -Exactly `restart_count` 3-byte `restart_offset` values precedes the +Exactly `restart_count` 3-byte `restart_offset` values precede the `restart_count`. Offsets are relative to the start of the block and refer to the first byte of any `ref_record` whose name has not been prefix compressed. Entries in the `restart_offset` list must be sorted, diff --git a/Documentation/technical/remembering-renames.txt b/Documentation/technical/remembering-renames.txt index 2fd5cc8..73f4176 100644 --- a/Documentation/technical/remembering-renames.txt +++ b/Documentation/technical/remembering-renames.txt @@ -20,7 +20,7 @@ Outline: 3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also a rename on MERGE_SIDE1 for the next pick - 4. A detailed description of the the counter-examples to #3. + 4. A detailed description of the counter-examples to #3. 5. Why the special cases in #4 are still fully reasonable to use to pair up files for three-way content merging in the merge machinery, and why @@ -407,7 +407,7 @@ considered to be "irrelevant". See for example the following commits: no longer relevant", 2021-03-13) Relevance is always determined by what the _other_ side of history has -done, in terms of modifing a file that our side renamed, or adding a +done, in terms of modifying a file that our side renamed, or adding a file to a directory which our side renamed. This means that a path that is "irrelevant" when picking the first commit of a series in a rebase or cherry-pick, may suddenly become "relevant" when picking the @@ -664,7 +664,7 @@ skip-irrelevant-renames optimization means we sometimes don't detect renames for any files within a directory that was renamed, in which case we will not have been able to detect any rename for the directory itself. In such a case, we do not know whether the directory was -renamed; we want to be careful to avoid cacheing some kind of "this +renamed; we want to be careful to avoid caching some kind of "this directory was not renamed" statement. If we did, then a subsequent commit being rebased could add a file to the old directory, and the user would expect it to end up in the correct directory -- something diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt index 7844ef3..4728142 100644 --- a/Documentation/technical/repository-version.txt +++ b/Documentation/technical/repository-version.txt @@ -82,9 +82,9 @@ When the config key `extensions.preciousObjects` is set to `true`, objects in the repository MUST NOT be deleted (e.g., by `git-prune` or `git repack -d`). -==== `partialclone` +==== `partialClone` -When the config key `extensions.partialclone` is set, it indicates +When the config key `extensions.partialClone` is set, it indicates that the repo was created with a partial clone (or later performed a partial fetch) and that the remote may have omitted sending certain unwanted objects. Such a remote is called a "promisor remote" @@ -96,7 +96,13 @@ The value of this key is the name of the promisor remote. ==== `worktreeConfig` If set, by default "git config" reads from both "config" and -"config.worktree" file from GIT_DIR in that order. In +"config.worktree" files from GIT_DIR in that order. In 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/rerere.txt b/Documentation/technical/rerere.txt index 35d4541..580f233 100644 --- a/Documentation/technical/rerere.txt +++ b/Documentation/technical/rerere.txt @@ -60,7 +60,7 @@ By resolving this conflict, to leave line D, the user declares: what AB and AC wanted to do. As branch AC2 refers to the same commit as AC, the above implies that -this is also compatible what AB and AC2 wanted to do. +this is also compatible with what AB and AC2 wanted to do. By extension, this means that rerere should recognize that the above conflicts are the same. To do this, the labels on the conflict @@ -76,7 +76,7 @@ examples would both result in the following normalized conflict: Sorting hunks ~~~~~~~~~~~~~ -As before, lets imagine that a common ancestor had a file with line A +As before, let's imagine that a common ancestor had a file with line A its early part, and line X in its late part. And then four branches are forked that do these things: @@ -99,7 +99,7 @@ conflict to leave line D means that the user declares: compatible with what AB and AC wanted to do. So the conflict we would see when merging AB into ACAB should be -resolved the same way---it is the resolution that is in line with that +resolved the same way--it is the resolution that is in line with that declaration. Imagine that similarly previously a branch XYXZ was forked from XY, @@ -145,7 +145,7 @@ Nested conflicts Nested conflicts are handled very similarly to "simple" conflicts. Similar to simple conflicts, the conflict is first normalized by stripping the labels from conflict markers, stripping the common ancestor -version, and the sorting the conflict hunks, both for the outer and the +version, and sorting the conflict hunks, both for the outer and the inner conflict. This is done recursively, so any number of nested conflicts can be handled. diff --git a/Documentation/technical/scalar.txt b/Documentation/technical/scalar.txt new file mode 100644 index 0000000..921cb10 --- /dev/null +++ b/Documentation/technical/scalar.txt @@ -0,0 +1,66 @@ +Scalar +====== + +Scalar is a repository management tool that optimizes Git for use in large +repositories. It accomplishes this by helping users to take advantage of +advanced performance features in Git. Unlike most other Git built-in commands, +Scalar is not executed as a subcommand of 'git'; rather, it is built as a +separate executable containing its own series of subcommands. + +Background +---------- + +Scalar was originally designed as an add-on to Git and implemented as a .NET +Core application. It was created based on the learnings from the VFS for Git +project (another application aimed at improving the experience of working with +large repositories). As part of its initial implementation, Scalar relied on +custom features in the Microsoft fork of Git that have since been integrated +into core Git: + +* partial clone, +* commit graphs, +* multi-pack index, +* sparse checkout (cone mode), +* scheduled background maintenance, +* etc + +With the requisite Git functionality in place and a desire to bring the benefits +of Scalar to the larger Git community, the Scalar application itself was ported +from C# to C and integrated upstream. + +Features +-------- + +Scalar is comprised of two major pieces of functionality: automatically +configuring built-in Git performance features and managing repository +enlistments. + +The Git performance features configured by Scalar (see "Background" for +examples) confer substantial performance benefits to large repositories, but are +either too experimental to enable for all of Git yet, or only benefit large +repositories. As new features are introduced, Scalar should be updated +accordingly to incorporate them. This will prevent the tool from becoming stale +while also providing a path for more easily bringing features to the appropriate +users. + +Enlistments are how Scalar knows which repositories on a user's system should +utilize Scalar-configured features. This allows it to update performance +settings when new ones are added to the tool, as well as centrally manage +repository maintenance. The enlistment structure - a root directory with a +`src/` subdirectory containing the cloned repository itself - is designed to +encourage users to route build outputs outside of the repository to avoid the +performance-limiting overhead of ignoring those files in Git. + +Design +------ + +Scalar is implemented in C and interacts with Git via a mix of child process +invocations of Git and direct usage of `libgit.a`. Internally, it is structured +much like other built-ins with subcommands (e.g., `git stash`), containing a +`cmd_<subcommand>()` function for each subcommand, routed through a `cmd_main()` +function. Most options are unique to each subcommand, with `scalar` respecting +some "global" `git` options (e.g., `-c` and `-C`). + +Because `scalar` is not invoked as a Git subcommand (like `git scalar`), it is +built and installed as its own executable in the `bin/` directory, alongside +`git`, `git-gui`, etc. diff --git a/Documentation/technical/sparse-checkout.txt b/Documentation/technical/sparse-checkout.txt new file mode 100644 index 0000000..fa0d01c --- /dev/null +++ b/Documentation/technical/sparse-checkout.txt @@ -0,0 +1,1103 @@ +Table of contents: + + * Terminology + * Purpose of sparse-checkouts + * Usecases of primary concern + * Oversimplified mental models ("Cliff Notes" for this document!) + * Desired behavior + * Behavior classes + * Subcommand-dependent defaults + * Sparse specification vs. sparsity patterns + * Implementation Questions + * Implementation Goals/Plans + * Known bugs + * Reference Emails + + +=== Terminology === + +cone mode: one of two modes for specifying the desired subset of files + in a sparse-checkout. In cone-mode, the user specifies + directories (getting both everything under that directory as + well as everything in leading directories), while in non-cone + mode, the user specifies gitignore-style patterns. Controlled + by the --[no-]cone option to sparse-checkout init|set. + +SKIP_WORKTREE: When tracked files do not match the sparse specification and + are removed from the working tree, the file in the index is marked + with a SKIP_WORKTREE bit. Note that if a tracked file has the + SKIP_WORKTREE bit set but the file is later written by the user to + the working tree anyway, the SKIP_WORKTREE bit will be cleared at + the beginning of any subsequent Git operation. + + Most sparse checkout users are unaware of this implementation + detail, and the term should generally be avoided in user-facing + descriptions and command flags. Unfortunately, prior to the + `sparse-checkout` subcommand this low-level detail was exposed, + and as of time of writing, is still exposed in various places. + +sparse-checkout: a subcommand in git used to reduce the files present in + the working tree to a subset of all tracked files. Also, the + name of the file in the $GIT_DIR/info directory used to track + the sparsity patterns corresponding to the user's desired + subset. + +sparse cone: see cone mode + +sparse directory: An entry in the index corresponding to a directory, which + appears in the index instead of all the files under that directory + that would normally appear. See also sparse-index. Something that + can cause confusion is that the "sparse directory" does NOT match + the sparse specification, i.e. the directory is NOT present in the + working tree. May be renamed in the future (e.g. to "skipped + directory"). + +sparse index: A special mode for sparse-checkout that also makes the + index sparse by recording a directory entry in lieu of all the + files underneath that directory (thus making that a "skipped + directory" which unfortunately has also been called a "sparse + directory"), and does this for potentially multiple + directories. Controlled by the --[no-]sparse-index option to + init|set|reapply. + +sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to + define the set of files of interest. A warning: It is easy to + over-use this term (or the shortened "patterns" term), for two + reasons: (1) users in cone mode specify directories rather than + patterns (their directories are transformed into patterns, but + users may think you are talking about non-cone mode if you use the + word "patterns"), and (b) the sparse specification might + transiently differ in the working tree or index from the sparsity + patterns (see "Sparse specification vs. sparsity patterns"). + +sparse specification: The set of paths in the user's area of focus. This + is typically just the tracked files that match the sparsity + patterns, but the sparse specification can temporarily differ and + include additional files. (See also "Sparse specification + vs. sparsity patterns") + + * When working with history, the sparse specification is exactly + the set of files matching the sparsity patterns. + * When interacting with the working tree, the sparse specification + is the set of tracked files with a clear SKIP_WORKTREE bit or + tracked files present in the working copy. + * When modifying or showing results from the index, the sparse + specification is the set of files with a clear SKIP_WORKTREE bit + or that differ in the index from HEAD. + * If working with the index and the working copy, the sparse + specification is the union of the paths from above. + +vivifying: When a command restores a tracked file to the working tree (and + hopefully also clears the SKIP_WORKTREE bit in the index for that + file), this is referred to as "vivifying" the file. + + +=== Purpose of sparse-checkouts === + +sparse-checkouts exist to allow users to work with a subset of their +files. + +You can think of sparse-checkouts as subdividing "tracked" files into two +categories -- a sparse subset, and all the rest. Implementationally, we +mark "all the rest" in the index with a SKIP_WORKTREE bit and leave them +out of the working tree. The SKIP_WORKTREE files are still tracked, just +not present in the working tree. + +In the past, sparse-checkouts were defined by "SKIP_WORKTREE means the file +is missing from the working tree but pretend the file contents match HEAD". +That was not only bogus (it actually meant the file missing from the +working tree matched the index rather than HEAD), but it was also a +low-level detail which only provided decent behavior for a few commands. +There were a surprising number of ways in which that guiding principle gave +command results that violated user expectations, and as such was a bad +mental model. However, it persisted for many years and may still be found +in some corners of the code base. + +Anyway, the idea of "working with a subset of files" is simple enough, but +there are multiple different high-level usecases which affect how some Git +subcommands should behave. Further, even if we only considered one of +those usecases, sparse-checkouts can modify different subcommands in over a +half dozen different ways. Let's start by considering the high level +usecases: + + A) Users are _only_ interested in the sparse portion of the repo + + A*) Users are _only_ interested in the sparse portion of the repo + that they have downloaded so far + + B) Users want a sparse working tree, but are working in a larger whole + + C) sparse-checkout is a behind-the-scenes implementation detail allowing + Git to work with a specially crafted in-house virtual file system; + users are actually working with a "full" working tree that is + lazily populated, and sparse-checkout helps with the lazy population + piece. + +It may be worth explaining each of these in a bit more detail: + + + (Behavior A) Users are _only_ interested in the sparse portion of the repo + +These folks might know there are other things in the repository, but +don't care. They are uninterested in other parts of the repository, and +only want to know about changes within their area of interest. Showing +them other files from history (e.g. from diff/log/grep/etc.) is a +usability annoyance, potentially a huge one since other changes in +history may dwarf the changes they are interested in. + +Some of these users also arrive at this usecase from wanting to use partial +clones together with sparse checkouts (in a way where they have downloaded +blobs within the sparse specification) and do disconnected development. +Not only do these users generally not care about other parts of the +repository, but consider it a blocker for Git commands to try to operate on +those. If commands attempt to access paths in history outside the sparsity +specification, then the partial clone will attempt to download additional +blobs on demand, fail, and then fail the user's command. (This may be +unavoidable in some cases, e.g. when `git merge` has non-trivial changes to +reconcile outside the sparse specification, but we should limit how often +users are forced to connect to the network.) + +Also, even for users using partial clones that do not mind being +always connected to the network, the need to download blobs as +side-effects of various other commands (such as the printed diffstat +after a merge or pull) can lead to worries about local repository size +growing unnecessarily[10]. + + (Behavior A*) Users are _only_ interested in the sparse portion of the repo + that they have downloaded so far (a variant on the first usecase) + +This variant is driven by folks who using partial clones together with +sparse checkouts and do disconnected development (so far sounding like a +subset of behavior A users) and doing so on very large repositories. The +reason for yet another variant is that downloading even just the blobs +through history within their sparse specification may be too much, so they +only download some. They would still like operations to succeed without +network connectivity, though, so things like `git log -S${SEARCH_TERM} -p` +or `git grep ${SEARCH_TERM} OLDREV ` would need to be prepared to provide +partial results that depend on what happens to have been downloaded. + +This variant could be viewed as Behavior A with the sparse specification +for history querying operations modified from "sparsity patterns" to +"sparsity patterns limited to the blobs we have already downloaded". + + (Behavior B) Users want a sparse working tree, but are working in a + larger whole + +Stolee described this usecase this way[11]: + +"I'm also focused on users that know that they are a part of a larger +whole. They know they are operating on a large repository but focus on +what they need to contribute their part. I expect multiple "roles" to +use very different, almost disjoint parts of the codebase. Some other +"architect" users operate across the entire tree or hop between different +sections of the codebase as necessary. In this situation, I'm wary of +scoping too many features to the sparse-checkout definition, especially +"git log," as it can be too confusing to have their view of the codebase +depend on your "point of view." + +People might also end up wanting behavior B due to complex inter-project +dependencies. The initial attempts to use sparse-checkouts usually involve +the directories you are directly interested in plus what those directories +depend upon within your repository. But there's a monkey wrench here: if +you have integration tests, they invert the hierarchy: to run integration +tests, you need not only what you are interested in and its in-tree +dependencies, you also need everything that depends upon what you are +interested in or that depends upon one of your dependencies...AND you need +all the in-tree dependencies of that expanded group. That can easily +change your sparse-checkout into a nearly dense one. + +Naturally, that tends to kill the benefits of sparse-checkouts. There are +a couple solutions to this conundrum: either avoid grabbing in-repo +dependencies (maybe have built versions of your in-repo dependencies pulled +from a CI cache somewhere), or say that users shouldn't run integration +tests directly and instead do it on the CI server when they submit a code +review. Or do both. Regardless of whether you stub out your in-repo +dependencies or stub out the things that depend upon you, there is +certainly a reason to want to query and be aware of those other stubbed-out +parts of the repository, particularly when the dependencies are complex or +change relatively frequently. Thus, for such uses, sparse-checkouts can be +used to limit what you directly build and modify, but these users do not +necessarily want their sparse checkout paths to limit their queries of +versions in history. + +Some people may also be interested in behavior B over behavior A simply as +a performance workaround: if they are using non-cone mode, then they have +to deal with its inherent quadratic performance problems. In that mode, +every operation that checks whether paths match the sparsity specification +can be expensive. As such, these users may only be willing to pay for +those expensive checks when interacting with the working copy, and may +prefer getting "unrelated" results from their history queries over having +slow commands. + + (Behavior C) sparse-checkout is an implementational detail supporting a + special VFS. + +This usecase goes slightly against the traditional definition of +sparse-checkout in that it actually tries to present a full or dense +checkout to the user. However, this usecase utilizes the same underlying +technical underpinnings in a new way which does provide some performance +advantages to users. The basic idea is that a company can have an in-house +Git-aware Virtual File System which pretends all files are present in the +working tree, by intercepting all file system accesses and using those to +fetch and write accessed files on demand via partial clones. The VFS uses +sparse-checkout to prevent Git from writing or paying attention to many +files, and manually updates the sparse checkout patterns itself based on +user access and modification of files in the working tree. See commit +ecc7c8841d ("repo_read_index: add config to expect files outside sparse +patterns", 2022-02-25) and the link at [17] for a more detailed description +of such a VFS. + +The biggest difference here is that users are completely unaware that the +sparse-checkout machinery is even in use. The sparse patterns are not +specified by the user but rather are under the complete control of the VFS +(and the patterns are updated frequently and dynamically by it). The user +will perceive the checkout as dense, and commands should thus behave as if +all files are present. + + +=== Usecases of primary concern === + +Most of the rest of this document will focus on Behavior A and Behavior +B. Some notes about the other two cases and why we are not focusing on +them: + + (Behavior A*) + +Supporting this usecase is estimated to be difficult and a lot of work. +There are no plans to implement it currently, but it may be a potential +future alternative. Knowing about the existence of additional alternatives +may affect our choice of command line flags (e.g. if we need tri-state or +quad-state flags rather than just binary flags), so it was still important +to at least note. + +Further, I believe the descriptions below for Behavior A are probably still +valid for this usecase, with the only exception being that it redefines the +sparse specification to restrict it to already-downloaded blobs. The hard +part is in making commands capable of respecting that modified definition. + + (Behavior C) + +This usecase violates some of the early sparse-checkout documented +assumptions (since files marked as SKIP_WORKTREE will be displayed to users +as present in the working tree). That violation may mean various +sparse-checkout related behaviors are not well suited to this usecase and +we may need tweaks -- to both documentation and code -- to handle it. +However, this usecase is also perhaps the simplest model to support in that +everything behaves like a dense checkout with a few exceptions (e.g. branch +checkouts and switches write fewer things, knowing the VFS will lazily +write the rest on an as-needed basis). + +Since there is no publically available VFS-related code for folks to try, +the number of folks who can test such a usecase is limited. + +The primary reason to note the Behavior C usecase is that as we fix things +to better support Behaviors A and B, there may be additional places where +we need to make tweaks allowing folks in this usecase to get the original +non-sparse treatment. For an example, see ecc7c8841d ("repo_read_index: +add config to expect files outside sparse patterns", 2022-02-25). The +secondary reason to note Behavior C, is so that folks taking advantage of +Behavior C do not assume they are part of the Behavior B camp and propose +patches that break things for the real Behavior B folks. + + +=== Oversimplified mental models === + +An oversimplification of the differences in the above behaviors is: + + Behavior A: Restrict worktree and history operations to sparse specification + Behavior B: Restrict worktree operations to sparse specification; have any + history operations work across all files + Behavior C: Do not restrict either worktree or history operations to the + sparse specification...with the exception of branch checkouts or + switches which avoid writing files that will match the index so + they can later lazily be populated instead. + + +=== Desired behavior === + +As noted previously, despite the simple idea of just working with a subset +of files, there are a range of different behavioral changes that need to be +made to different subcommands to work well with such a feature. See +[1,2,3,4,5,6,7,8,9,10] for various examples. In particular, at [2], we saw +that mere composition of other commands that individually worked correctly +in a sparse-checkout context did not imply that the higher level command +would work correctly; it sometimes requires further tweaks. So, +understanding these differences can be beneficial. + +* Commands behaving the same regardless of high-level use-case + + * commands that only look at files within the sparsity specification + + * diff (without --cached or REVISION arguments) + * grep (without --cached or REVISION arguments) + * diff-files + + * commands that restore files to the working tree that match sparsity + patterns, and remove unmodified files that don't match those + patterns: + + * switch + * checkout (the switch-like half) + * read-tree + * reset --hard + + * commands that write conflicted files to the working tree, but otherwise + will omit writing files to the working tree that do not match the + sparsity patterns: + + * merge + * rebase + * cherry-pick + * revert + + * `am` and `apply --cached` should probably be in this section but + are buggy (see the "Known bugs" section below) + + The behavior for these commands somewhat depends upon the merge + strategy being used: + * `ort` behaves as described above + * `recursive` tries to not vivify files unnecessarily, but does sometimes + vivify files without conflicts. + * `octopus` and `resolve` will always vivify any file changed in the merge + relative to the first parent, which is rather suboptimal. + + It is also important to note that these commands WILL update the index + outside the sparse specification relative to when the operation began, + BUT these commands often make a commit just before or after such that + by the end of the operation there is no change to the index outside the + sparse specification. Of course, if the operation hits conflicts or + does not make a commit, then these operations clearly can modify the + index outside the sparse specification. + + Finally, it is important to note that at least the first four of these + commands also try to remove differences between the sparse + specification and the sparsity patterns (much like the commands in the + previous section). + + * commands that always ignore sparsity since commits must be full-tree + + * archive + * bundle + * commit + * format-patch + * fast-export + * fast-import + * commit-tree + + * commands that write any modified file to the working tree (conflicted + or not, and whether those paths match sparsity patterns or not): + + * stash + * apply (without `--index` or `--cached`) + +* Commands that may slightly differ for behavior A vs. behavior B: + + Commands in this category behave mostly the same between the two + behaviors, but may differ in verbosity and types of warning and error + messages. + + * commands that make modifications to which files are tracked: + * add + * rm + * mv + * update-index + + The fact that files can move between the 'tracked' and 'untracked' + categories means some commands will have to treat untracked files + differently. But if we have to treat untracked files differently, + then additional commands may also need changes: + + * status + * clean + + In particular, `status` may need to report any untracked files outside + the sparsity specification as an erroneous condition (especially to + avoid the user trying to `git add` them, forcing `git add` to display + an error). + + It's not clear to me exactly how (or even if) `clean` would change, + but it's the other command that also affects untracked files. + + `update-index` may be slightly special. Its --[no-]skip-worktree flag + may need to ignore the sparse specification by its nature. Also, its + current --[no-]ignore-skip-worktree-entries default is totally bogus. + + * commands for manually tweaking paths in both the index and the working tree + * `restore` + * the restore-like half of `checkout` + + These commands should be similar to add/rm/mv in that they should + only operate on the sparse specification by default, and require a + special flag to operate on all files. + + Also, note that these commands currently have a number of issues (see + the "Known bugs" section below) + +* Commands that significantly differ for behavior A vs. behavior B: + + * commands that query history + * diff (with --cached or REVISION arguments) + * grep (with --cached or REVISION arguments) + * show (when given commit arguments) + * blame (only matters when one or more -C flags are passed) + * and annotate + * log + * whatchanged + * ls-files + * diff-index + * diff-tree + * ls-tree + + Note: for log and whatchanged, revision walking logic is unaffected + but displaying of patches is affected by scoping the command to the + sparse-checkout. (The fact that revision walking is unaffected is + why rev-list, shortlog, show-branch, and bisect are not in this + list.) + + ls-files may be slightly special in that e.g. `git ls-files -t` is + often used to see what is sparse and what is not. Perhaps -t should + always work on the full tree? + +* Commands I don't know how to classify + + * range-diff + + Is this like `log` or `format-patch`? + + * cherry + + See range-diff + +* Commands unaffected by sparse-checkouts + + * shortlog + * show-branch + * rev-list + * bisect + + * branch + * describe + * fetch + * gc + * init + * maintenance + * notes + * pull (merge & rebase have the necessary changes) + * push + * submodule + * tag + + * config + * filter-branch (works in separate checkout without sparse-checkout setup) + * pack-refs + * prune + * remote + * repack + * replace + + * bugreport + * count-objects + * fsck + * gitweb + * help + * instaweb + * merge-tree (doesn't touch worktree or index, and merges always compute full-tree) + * rerere + * verify-commit + * verify-tag + + * commit-graph + * hash-object + * index-pack + * mktag + * mktree + * multi-pack-index + * pack-objects + * prune-packed + * symbolic-ref + * unpack-objects + * update-ref + * write-tree (operates on index, possibly optimized to use sparse dir entries) + + * for-each-ref + * get-tar-commit-id + * ls-remote + * merge-base (merges are computed full tree, so merge base should be too) + * name-rev + * pack-redundant + * rev-parse + * show-index + * show-ref + * unpack-file + * var + * verify-pack + + * <Everything under 'Interacting with Others' in 'git help --all'> + * <Everything under 'Low-level...Syncing' in 'git help --all'> + * <Everything under 'Low-level...Internal Helpers' in 'git help --all'> + * <Everything under 'External commands' in 'git help --all'> + +* Commands that might be affected, but who cares? + + * merge-file + * merge-index + * gitk? + + +=== Behavior classes === + +From the above there are a few classes of behavior: + + * "restrict" + + Commands in this class only read or write files in the working tree + within the sparse specification. + + When moving to a new commit (e.g. switch, reset --hard), these commands + may update index files outside the sparse specification as of the start + of the operation, but by the end of the operation those index files + will match HEAD again and thus those files will again be outside the + sparse specification. + + When paths are explicitly specified, these paths are intersected with + the sparse specification and will only operate on such paths. + (e.g. `git restore [--staged] -- '*.png'`, `git reset -p -- '*.md'`) + + Some of these commands may also attempt, at the end of their operation, + to cull transient differences between the sparse specification and the + sparsity patterns (see "Sparse specification vs. sparsity patterns" for + details, but this basically means either removing unmodified files not + matching the sparsity patterns and marking those files as + SKIP_WORKTREE, or vivifying files that match the sparsity patterns and + marking those files as !SKIP_WORKTREE). + + * "restrict modulo conflicts" + + Commands in this class generally behave like the "restrict" class, + except that: + (1) they will ignore the sparse specification and write files with + conflicts to the working tree (thus temporarily expanding the + sparse specification to include such files.) + (2) they are grouped with commands which move to a new commit, since + they often create a commit and then move to it, even though we + know there are many exceptions to moving to the new commit. (For + example, the user may rebase a commit that becomes empty, or have + a cherry-pick which conflicts, or a user could run `merge + --no-commit`, and we also view `apply --index` kind of like `am + --no-commit`.) As such, these commands can make changes to index + files outside the sparse specification, though they'll mark such + files with SKIP_WORKTREE. + + * "restrict also specially applied to untracked files" + + Commands in this class generally behave like the "restrict" class, + except that they have to handle untracked files differently too, often + because these commands are dealing with files changing state between + 'tracked' and 'untracked'. Often, this may mean printing an error + message if the command had nothing to do, but the arguments may have + referred to files whose tracked-ness state could have changed were it + not for the sparsity patterns excluding them. + + * "no restrict" + + Commands in this class ignore the sparse specification entirely. + + * "restrict or no restrict dependent upon behavior A vs. behavior B" + + Commands in this class behave like "no restrict" for folks in the + behavior B camp, and like "restrict" for folks in the behavior A camp. + However, when behaving like "restrict" a warning of some sort might be + provided that history queries have been limited by the sparse-checkout + specification. + + +=== Subcommand-dependent defaults === + +Note that we have different defaults depending on the command for the +desired behavior : + + * Commands defaulting to "restrict": + * diff-files + * diff (without --cached or REVISION arguments) + * grep (without --cached or REVISION arguments) + * switch + * checkout (the switch-like half) + * reset (<commit>) + + * restore + * checkout (the restore-like half) + * checkout-index + * reset (with pathspec) + + This behavior makes sense; these interact with the working tree. + + * Commands defaulting to "restrict modulo conflicts": + * merge + * rebase + * cherry-pick + * revert + + * am + * apply --index (which is kind of like an `am --no-commit`) + + * read-tree (especially with -m or -u; is kind of like a --no-commit merge) + * reset (<tree-ish>, due to similarity to read-tree) + + These also interact with the working tree, but require slightly + different behavior either so that (a) conflicts can be resolved or (b) + because they are kind of like a merge-without-commit operation. + + (See also the "Known bugs" section below regarding `am` and `apply`) + + * Commands defaulting to "no restrict": + * archive + * bundle + * commit + * format-patch + * fast-export + * fast-import + * commit-tree + + * stash + * apply (without `--index`) + + These have completely different defaults and perhaps deserve the most + detailed explanation: + + In the case of commands in the first group (format-patch, + fast-export, bundle, archive, etc.), these are commands for + communicating history, which will be broken if they restrict to a + subset of the repository. As such, they operate on full paths and + have no `--restrict` option for overriding. Some of these commands may + take paths for manually restricting what is exported, but it needs to + be very explicit. + + In the case of stash, it needs to vivify files to avoid losing the + user's changes. + + In the case of apply without `--index`, that command needs to update + the working tree without the index (or the index without the working + tree if `--cached` is passed), and if we restrict those updates to the + sparse specification then we'll lose changes from the user. + + * Commands defaulting to "restrict also specially applied to untracked files": + * add + * rm + * mv + * update-index + * status + * clean (?) + + Our original implementation for the first three of these commands was + "no restrict", but it had some severe usability issues: + * `git add <somefile>` if honored and outside the sparse + specification, can result in the file randomly disappearing later + when some subsequent command is run (since various commands + automatically clean up unmodified files outside the sparse + specification). + * `git rm '*.jpg'` could very negatively surprise users if it deletes + files outside the range of the user's interest. + * `git mv` has similar surprises when moving into or out of the cone, + so best to restrict by default + + So, we switched `add` and `rm` to default to "restrict", which made + usability problems much less severe and less frequent, but we still got + complaints because commands like: + git add <file-outside-sparse-specification> + git rm <file-outside-sparse-specification> + would silently do nothing. We should instead print an error in those + cases to get usability right. + + update-index needs to be updated to match, and status and maybe clean + also need to be updated to specially handle untracked paths. + + There may be a difference in here between behavior A and behavior B in + terms of verboseness of errors or additional warnings. + + * Commands falling under "restrict or no restrict dependent upon behavior + A vs. behavior B" + + * diff (with --cached or REVISION arguments) + * grep (with --cached or REVISION arguments) + * show (when given commit arguments) + * blame (only matters when one or more -C flags passed) + * and annotate + * log + * and variants: shortlog, gitk, show-branch, whatchanged, rev-list + * ls-files + * diff-index + * diff-tree + * ls-tree + + For now, we default to behavior B for these, which want a default of + "no restrict". + + Note that two of these commands -- diff and grep -- also appeared in a + different list with a default of "restrict", but only when limited to + searching the working tree. The working tree vs. history distinction + is fundamental in how behavior B operates, so this is expected. Note, + though, that for diff and grep with --cached, when doing "restrict" + behavior, the difference between sparse specification and sparsity + patterns is important to handle. + + "restrict" may make more sense as the long term default for these[12]. + Also, supporting "restrict" for these commands might be a fair amount + of work to implement, meaning it might be implemented over multiple + releases. If that behavior were the default in the commands that + supported it, that would force behavior B users to need to learn to + slowly add additional flags to their commands, depending on git + version, to get the behavior they want. That gradual switchover would + be painful, so we should avoid it at least until it's fully + implemented. + + +=== Sparse specification vs. sparsity patterns === + +In a well-behaved situation, the sparse specification is given directly +by the $GIT_DIR/info/sparse-checkout file. However, it can transiently +diverge for a few reasons: + + * needing to resolve conflicts (merging will vivify conflicted files) + * running Git commands that implicitly vivify files (e.g. "git stash apply") + * running Git commands that explicitly vivify files (e.g. "git checkout + --ignore-skip-worktree-bits FILENAME") + * other commands that write to these files (perhaps a user copies it + from elsewhere) + +For the last item, note that we do automatically clear the SKIP_WORKTREE +bit for files that are present in the working tree. This has been true +since 82386b4496 ("Merge branch 'en/present-despite-skipped'", +2022-03-09) + +However, such a situation is transient because: + + * Such transient differences can and will be automatically removed as + a side-effect of commands which call unpack_trees() (checkout, + merge, reset, etc.). + * Users can also request such transient differences be corrected via + running `git sparse-checkout reapply`. Various places recommend + running that command. + * Additional commands are also welcome to implicitly fix these + differences; we may add more in the future. + +While we avoid dropping unstaged changes or files which have conflicts, +we otherwise aggressively try to fix these transient differences. If +users want these differences to persist, they should run the `set` or +`add` subcommands of `git sparse-checkout` to reflect their intended +sparse specification. + +However, when we need to do a query on history restricted to the +"relevant subset of files" such a transiently expanded sparse +specification is ignored. There are a couple reasons for this: + + * The behavior wanted when doing something like + git grep expression REVISION + is roughly what the users would expect from + git checkout REVISION && git grep expression + (modulo a "REVISION:" prefix), which has a couple ramifications: + + * REVISION may have paths not in the current index, so there is no + path we can consult for a SKIP_WORKTREE setting for those paths. + + * Since `checkout` is one of those commands that tries to remove + transient differences in the sparse specification, it makes sense + to use the corrected sparse specification + (i.e. $GIT_DIR/info/sparse-checkout) rather than attempting to + consult SKIP_WORKTREE anyway. + +So, a transiently expanded (or restricted) sparse specification applies to +the working tree, but not to history queries where we always use the +sparsity patterns. (See [16] for an early discussion of this.) + +Similar to a transiently expanded sparse specification of the working tree +based on additional files being present in the working tree, we also need +to consider additional files being modified in the index. In particular, +if the user has staged changes to files (relative to HEAD) that do not +match the sparsity patterns, and the file is not present in the working +tree, we still want to consider the file part of the sparse specification +if we are specifically performing a query related to the index (e.g. git +diff --cached [REVISION], git diff-index [REVISION], git restore --staged +--source=REVISION -- PATHS, etc.) Note that a transiently expanded sparse +specification for the index usually only matters under behavior A, since +under behavior B index operations are lumped with history and tend to +operate full-tree. + + +=== Implementation Questions === + + * Do the options --scope={sparse,all} sound good to others? Are there better + options? + * Names in use, or appearing in patches, or previously suggested: + * --sparse/--dense + * --ignore-skip-worktree-bits + * --ignore-skip-worktree-entries + * --ignore-sparsity + * --[no-]restrict-to-sparse-paths + * --full-tree/--sparse-tree + * --[no-]restrict + * --scope={sparse,all} + * --focus/--unfocus + * --limit/--unlimited + * Rationale making me lean slightly towards --scope={sparse,all}: + * We want a name that works for many commands, so we need a name that + does not conflict + * We know that we have more than two possible usecases, so it is best + to avoid a flag that appears to be binary. + * --scope={sparse,all} isn't overly long and seems relatively + explanatory + * `--sparse`, as used in add/rm/mv, is totally backwards for + grep/log/etc. Changing the meaning of `--sparse` for these + commands would fix the backwardness, but possibly break existing + scripts. Using a new name pairing would allow us to treat + `--sparse` in these commands as a deprecated alias. + * There is a different `--sparse`/`--dense` pair for commands using + revision machinery, so using that naming might cause confusion + * There is also a `--sparse` in both pack-objects and show-branch, which + don't conflict but do suggest that `--sparse` is overloaded + * The name --ignore-skip-worktree-bits is a double negative, is + quite a mouthful, refers to an implementation detail that many + users may not be familiar with, and we'd need a negation for it + which would probably be even more ridiculously long. (But we + can make --ignore-skip-worktree-bits a deprecated alias for + --no-restrict.) + + * If a config option is added (sparse.scope?) what should the values and + description be? "sparse" (behavior A), "worktree-sparse-history-dense" + (behavior B), "dense" (behavior C)? There's a risk of confusion, + because even for Behaviors A and B we want some commands to be + full-tree and others to operate sparsely, so the wording may need to be + more tied to the usecases and somehow explain that. Also, right now, + the primary difference we are focusing is just the history-querying + commands (log/diff/grep). Previous config suggestion here: [13] + + * Is `--no-expand` a good alias for ls-files's `--sparse` option? + (`--sparse` does not map to either `--scope=sparse` or `--scope=all`, + because in non-cone mode it does nothing and in cone-mode it shows the + sparse directory entries which are technically outside the sparse + specification) + + * Under Behavior A: + * Does ls-files' `--no-expand` override the default `--scope=all`, or + does it need an extra flag? + * Does ls-files' `-t` option imply `--scope=all`? + * Does update-index's `--[no-]skip-worktree` option imply `--scope=all`? + + * sparse-checkout: once behavior A is fully implemented, should we take + an interim measure to ease people into switching the default? Namely, + if folks are not already in a sparse checkout, then require + `sparse-checkout init/set` to take a + `--set-scope=(sparse|worktree-sparse-history-dense|dense)` flag (which + would set sparse.scope according to the setting given), and throw an + error if the flag is not provided? That error would be a great place + to warn folks that the default may change in the future, and get them + used to specifying what they want so that the eventual default switch + is seamless for them. + + +=== Implementation Goals/Plans === + + * Get buy-in on this document in general. + + * Figure out answers to the 'Implementation Questions' sections (above) + + * Fix bugs in the 'Known bugs' section (below) + + * Provide some kind of method for backfilling the blobs within the sparse + specification in a partial clone + + [Below here is kind of spitballing since the first two haven't been resolved] + + * update-index: flip the default to --no-ignore-skip-worktree-entries, + nuke this stupid "Oh, there's a bug? Let me add a flag to let users + request that they not trigger this bug." flag + + * Flags & Config + * Make `--sparse` in add/rm/mv a deprecated alias for `--scope=all` + * Make `--ignore-skip-worktree-bits` in checkout-index/checkout/restore + a deprecated aliases for `--scope=all` + * Create config option (sparse.scope?), tie it to the "Cliff notes" + overview + + * Add --scope=sparse (and --scope=all) flag to each of the history querying + commands. IMPORTANT: make sure diff machinery changes don't mess with + format-patch, fast-export, etc. + +=== Known bugs === + +This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've +been working on it. + +0. Behavior A is not well supported in Git. (Behavior B didn't used to + be either, but was the easier of the two to implement.) + +1. am and apply: + + apply, without `--index` or `--cached`, relies on files being present + in the working copy, and also writes to them unconditionally. As + such, it should first check for the files' presence, and if found to + be SKIP_WORKTREE, then clear the bit and vivify the paths, then do + its work. Currently, it just throws an error. + + apply, with either `--cached` or `--index`, will not preserve the + SKIP_WORKTREE bit. This is fine if the file has conflicts, but + otherwise SKIP_WORKTREE bits should be preserved for --cached and + probably also for --index. + + am, if there are no conflicts, will vivify files and fail to preserve + the SKIP_WORKTREE bit. If there are conflicts and `-3` is not + specified, it will vivify files and then complain the patch doesn't + apply. If there are conflicts and `-3` is specified, it will vivify + files and then complain that those vivified files would be + overwritten by merge. + +2. reset --hard: + + reset --hard provides confusing error message (works correctly, but + misleads the user into believing it didn't): + + $ touch addme + $ git add addme + $ git ls-files -t + H addme + H tracked + S tracked-but-maybe-skipped + $ git reset --hard # usually works great + error: Path 'addme' not uptodate; will not remove from working tree. + HEAD is now at bdbbb6f third + $ git ls-files -t + H tracked + S tracked-but-maybe-skipped + $ ls -1 + tracked + + `git reset --hard` DID remove addme from the index and the working tree, contrary + to the error message, but in line with how reset --hard should behave. + +3. read-tree + + `read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the + entries it reads into the index, resulting in all your files suddenly + appearing to be "deleted". + +4. Checkout, restore: + + These command do not handle path & revision arguments appropriately: + + $ ls + tracked + $ git ls-files -t + H tracked + S tracked-but-maybe-skipped + $ git status --porcelain + $ git checkout -- '*skipped' + error: pathspec '*skipped' did not match any file(s) known to git + $ git ls-files -- '*skipped' + tracked-but-maybe-skipped + $ git checkout HEAD -- '*skipped' + error: pathspec '*skipped' did not match any file(s) known to git + $ git ls-tree HEAD | grep skipped + 100644 blob 276f5a64354b791b13840f02047738c77ad0584f tracked-but-maybe-skipped + $ git status --porcelain + $ git checkout HEAD~1 -- '*skipped' + $ git ls-files -t + H tracked + H tracked-but-maybe-skipped + $ git status --porcelain + M tracked-but-maybe-skipped + $ git checkout HEAD -- '*skipped' + $ git status --porcelain + $ + + Note that checkout without a revision (or restore --staged) fails to + find a file to restore from the index, even though ls-files shows + such a file certainly exists. + + Similar issues occur with HEAD (--source=HEAD in restore's case), + but suddenly works when HEAD~1 is specified. And then after that it + will work with HEAD specified, even though it didn't before. + + Directories are also an issue: + + $ git sparse-checkout set nomatches + $ git status + On branch main + You are in a sparse checkout with 0% of tracked files present. + + nothing to commit, working tree clean + $ git checkout . + error: pathspec '.' did not match any file(s) known to git + $ git checkout HEAD~1 . + Updated 1 path from 58916d9 + $ git ls-files -t + S tracked + H tracked-but-maybe-skipped + +5. checkout and restore --staged, continued: + + These commands do not correctly scope operations to the sparse + specification, and make it worse by not setting important SKIP_WORKTREE + bits: + + $ git restore --source OLDREV --staged outside-sparse-cone/ + $ git status --porcelain + MD outside-sparse-cone/file1 + MD outside-sparse-cone/file2 + MD outside-sparse-cone/file3 + + We can add a --scope=all mode to `git restore` to let it operate outside + the sparse specification, but then it will be important to set the + SKIP_WORKTREE bits appropriately. + +6. Performance issues; see: + https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/ + + +=== Reference Emails === + +Emails that detail various bugs we've had in sparse-checkout: + +[1] (Original descriptions of behavior A & behavior B) + https://lore.kernel.org/git/CABPp-BGJ_Nvi5TmgriD9Bh6eNXE2EDq2f8e8QKXAeYG3BxZafA@mail.gmail.com/ +[2] (Fix stash applications in sparse checkouts; bugs from behavioral differences) + https://lore.kernel.org/git/ccfedc7140dbf63ba26a15f93bd3885180b26517.1606861519.git.gitgitgadget@gmail.com/ +[3] (Present-despite-skipped entries) + https://lore.kernel.org/git/11d46a399d26c913787b704d2b7169cafc28d639.1642175983.git.gitgitgadget@gmail.com/ +[4] (Clone --no-checkout interaction) + https://lore.kernel.org/git/pull.801.v2.git.git.1591324899170.gitgitgadget@gmail.com/ (clone --no-checkout) +[5] (The need for update_sparsity() and avoiding `read-tree -mu HEAD`) + https://lore.kernel.org/git/3a1f084641eb47515b5a41ed4409a36128913309.1585270142.git.gitgitgadget@gmail.com/ +[6] (SKIP_WORKTREE is advisory, not mandatory) + https://lore.kernel.org/git/844306c3e86ef67591cc086decb2b760e7d710a3.1585270142.git.gitgitgadget@gmail.com/ +[7] (`worktree add` should copy sparsity settings from current worktree) + https://lore.kernel.org/git/c51cb3714e7b1d2f8c9370fe87eca9984ff4859f.1644269584.git.gitgitgadget@gmail.com/ +[8] (Avoid negative surprises in add, rm, and mv) + https://lore.kernel.org/git/cover.1617914011.git.matheus.bernardino@usp.br/ + https://lore.kernel.org/git/pull.1018.v4.git.1632497954.gitgitgadget@gmail.com/ +[9] (Move from out-of-cone to in-cone) + https://lore.kernel.org/git/20220630023737.473690-6-shaoxuan.yuan02@gmail.com/ + https://lore.kernel.org/git/20220630023737.473690-4-shaoxuan.yuan02@gmail.com/ +[10] (Unnecessarily downloading objects outside sparse specification) + https://lore.kernel.org/git/CAOLTT8QfwOi9yx_qZZgyGa8iL8kHWutEED7ok_jxwTcYT_hf9Q@mail.gmail.com/ + +[11] (Stolee's comments on high-level usecases) + https://lore.kernel.org/git/1a1e33f6-3514-9afc-0a28-5a6b85bd8014@gmail.com/ + +[12] Others commenting on eventually switching default to behavior A: + * https://lore.kernel.org/git/xmqqh719pcoo.fsf@gitster.g/ + * https://lore.kernel.org/git/xmqqzgeqw0sy.fsf@gitster.g/ + * https://lore.kernel.org/git/a86af661-cf58-a4e5-0214-a67d3a794d7e@github.com/ + +[13] Previous config name suggestion and description + * https://lore.kernel.org/git/CABPp-BE6zW0nJSStcVU=_DoDBnPgLqOR8pkTXK3dW11=T01OhA@mail.gmail.com/ + +[14] Tangential issue: switch to cone mode as default sparse specification mechanism: + https://lore.kernel.org/git/a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com/ + +[15] Lengthy email on grep behavior, covering what should be searched: + * https://lore.kernel.org/git/CABPp-BGVO3QdbfE84uF_3QDF0-y2iHHh6G5FAFzNRfeRitkuHw@mail.gmail.com/ + +[16] Email explaining sparsity patterns vs. SKIP_WORKTREE and history operations, + search for the parenthetical comment starting "We do not check". + https://lore.kernel.org/git/CABPp-BFsCPPNOZ92JQRJeGyNd0e-TCW-LcLyr0i_+VSQJP+GCg@mail.gmail.com/ + +[17] https://lore.kernel.org/git/20220207190320.2960362-1-jonathantanmy@google.com/ 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-remotes.txt b/Documentation/urls-remotes.txt index 86d0008..bf17012 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -33,7 +33,9 @@ config file would appear like this: ------------ The `<pushurl>` is used for pushes only. It is optional and defaults -to `<URL>`. +to `<URL>`. Pushing to a remote affects all defined pushurls or all +defined urls if no pushurls are defined. Fetch, however, will only +fetch from the first defined url if multiple urls are defined. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -46,7 +48,7 @@ provide a refspec on the command line. This file should have the following format: ------------ - URL: one of the above URL format + URL: one of the above URL formats Push: <refspec> Pull: <refspec> diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 1c229d7..7cec85a 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -6,23 +6,23 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. -Git supports ssh, git, http, and https protocols (in addition, ftp, +Git supports ssh, git, http, and https protocols (in addition, ftp and ftps can be used for fetching, but this is inefficient and -deprecated; do not use it). +deprecated; do not use them). The native transport (i.e. git:// URL) does no authentication and 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 865074b..90a4189 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1122,7 +1122,7 @@ choosing "Stage Hunk For Commit"). === Creating good commit messages Though not required, it's a good idea to begin the commit message -with a single short (less than 50 character) line summarizing the +with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3 $ 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 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 +used with linkgit:git-diff[1] to show the changes you've made so far to resolve +conflicts. Using the same example as above, after resolving the conflict we +get: + +------------------------------------------------- +$ git diff AUTO_MERGE +diff --git a/file.txt b/file.txt +index cd10406..8bf5ae7 100644 +--- a/file.txt ++++ b/file.txt +@@ -1,5 +1 @@ +-<<<<<<< HEAD:file.txt +-Hello world +-======= +-Goodbye +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt ++Goodbye world +------------------------------------------------- + +Notice that the diff shows we deleted the conflict markers and both versions of +the content line, and wrote "Goodbye world" instead. + The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help for merges: @@ -3133,7 +3160,7 @@ those "loose" objects. You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in link:technical/pack-format.html[pack format]. +found in linkgit:gitformat-pack[5]. To put the loose objects into a pack, just run git repack: @@ -4066,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 @@ -4096,19 +4154,18 @@ $ 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 now call a <<def_commit_object,commit>>. -Also, we do not call it "cache" any more, but rather "index"; however, the -file is still called `cache.h`. Remark: Not much reason to change it now, -especially since there is no good single name for it anyway, because it is -basically _the_ header file which is included by _all_ of Git's C sources. +Also, we do not call it "cache" any more, but rather "index"; however, +the file is still called `read-cache.h`. If you grasp the ideas in that initial commit, you should check out a -more recent version and skim `cache.h`, `object.h` and `commit.h`. +more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`. In the early days, Git (in the tradition of UNIX) was a bunch of programs which were extremely simple, and which you used in scripts, piping the @@ -4119,11 +4176,11 @@ many of these parts have become builtins, and some of the core has been and to avoid code duplication. By now, you know what the index is (and find the corresponding data -structures in `cache.h`), and that there are just a couple of object types -(blobs, trees, commits and tags) which inherit their common structure from -`struct object`, which is their first member (and thus, you can cast e.g. -`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e. -get at the object name and flags). +structures in `read-cache-ll.h`), and that there are just a couple of +object types (blobs, trees, commits and tags) which inherit their +common structure from `struct object`, which is their first member +(and thus, you can cast e.g. `(struct object *)commit` to achieve the +_same_ as `&commit->object`, i.e. get at the object name and flags). Now is a good point to take a break to let this information sink in. |