diff options
Diffstat (limited to 'Documentation')
412 files changed, 18873 insertions, 4236 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 9022d48..a48448d 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -10,8 +10,8 @@ howto-index.txt doc.dep cmds-*.txt mergetools-*.txt -manpage-base-url.xsl SubmittingPatches.txt tmp-doc-diff/ GIT-ASCIIDOCFLAGS +/.build/ /GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index e3af089..1d92b2d 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,14 @@ 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 + explain how the code works and what is assumed from the surrounding + context. The log messages explain what the changes wanted to + achieve and why the changes were necessary (more on this in the + accompanying SubmittingPatches document). Make your code readable and sensible, and don't try to be clever. @@ -33,10 +40,13 @@ 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 they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive): @@ -152,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 @@ -180,6 +188,26 @@ For shell scripts specifically (not exhaustive): hopefully nobody starts using "local" before they are reimplemented in C ;-) + - Some versions of shell do not understand "export variable=value", + so we write "variable=value" and then "export variable" on two + separate lines. + + - Some versions of dash have broken variable assignment when prefixed + with "local", "export", and "readonly", in that the value to be + assigned goes through field splitting at $IFS unless quoted. + + (incorrect) + local variable=$value + local variable=$(command args) + + (correct) + local variable="$value" + local variable="$(command args)" + + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. + "\xc2\xa2") in printf format strings, since hexadecimal escape + sequences are not portable. + For C programs: @@ -194,10 +222,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 @@ -210,15 +247,27 @@ For C programs: . since mid 2017 with 512f41cf, we have been using designated initializers for array (e.g. "int array[10] = { [5] = 2 }"). - These used to be forbidden, but we have not heard any breakage - report, and they are assumed to be safe. + . since early 2021 with 765dc168882, we have been using variadic + macros, mostly for printf-like trace and debug macros. + + . 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. - - NULL pointers shall be written as NULL, not as 0. - When declaring pointers, the star sides with the variable @@ -413,8 +462,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 @@ -453,7 +535,7 @@ For Perl programs: - Most of the C guidelines above apply. - - We try to support Perl 5.8 and later ("use Perl 5.008"). + - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). - use strict and use warnings are strongly preferred. @@ -479,26 +561,42 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, 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 - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - 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. - Where required libraries do not restrict us to Python 2, we try to also be compatible with Python 3.1 and later. + +Program Output + + We make a distinction between a Git command's primary output and + output which is merely chatty feedback (for instance, status + messages, running transcript, or progress display), as well as error + messages. Roughly speaking, a Git command's primary output is that + which one might want to capture to a file or send down a pipe; its + chatty output should not interfere with these use-cases. + + As such, primary output should be sent to the standard output stream + (stdout), and chatty output should be sent to the standard error + stream (stderr). Examples of commands which produce primary output + include `git log`, `git show`, and `git branch --list` which generate + output on the stdout stream. + + Not all Git commands have primary output; this is often true of + commands whose main function is to perform an action. Some action + commands are silent, whereas others are chatty. An example of a + chatty action commands is `git clone` with its "Cloning into + '<path>'..." and "Checking connectivity..." status messages which it + sends to the stderr stream. + + Error messages from Git commands should always be sent to the stderr + stream. + + Error Messages - Do not end error messages with a full stop. @@ -525,7 +623,7 @@ Externally Visible Names . The variable name describes the effect of tweaking this knob. The section and variable names that consist of multiple words are - formed by concatenating the words without punctuations (e.g. `-`), + formed by concatenating the words without punctuation marks (e.g. `-`), and are broken using bumpyCaps in documentation as a hint to the reader. @@ -551,57 +649,167 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file). + In order to ensure the documentation is inclusive, avoid assuming + that an unspecified example person is male or female, and think + twice before using "he", "him", "she", or "her". Here are some + tips to avoid use of gendered pronouns: + + - Prefer succinctness and matter-of-factly describing functionality + in the abstract. E.g. + + `--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... + + 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 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 + 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 + versions. + + - If you still need to refer to an example person that is + third-person singular, you may resort to "singular they" to avoid + "he/she/him/her", e.g. + + A contributor asks their upstream to pull from them. + + Note that this sounds ungrammatical and unnatural to those who + learned that "they" is only used for third-person plural, e.g. + those who learn English as a second language in some parts of the + world. + Every user-visible change should be reflected in the 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 @@ -612,37 +820,6 @@ Writing Documentation: the user would type into a shell and use 'Git' (uppercase first letter) when talking about the version control system and its properties. - A few commented examples follow to provide reference when writing or - modifying paragraphs or option/command explanations that contain options - or commands: - - Literal examples (e.g. use of command-line options, command names, - branch names, URLs, pathnames (files and directories), configuration and - environment variables) must be typeset in monospace (i.e. wrapped with - backticks): - `--pretty=oneline` - `git rev-list` - `remote.pushDefault` - `http://git.example.com` - `.git/config` - `GIT_DIR` - `HEAD` - - An environment variable must be prefixed with "$" only when referring to its - value and not when referring to the variable itself, in this case there is - nothing to add except the backticks: - `GIT_DIR` is specified - `$GIT_DIR/hooks/pre-receive` - - Word phrases enclosed in `backtick characters` are rendered literally - and will not be further expanded. The use of `backticks` to achieve the - previous rule means that literal examples should not use AsciiDoc - escapes. - Correct: - `--pretty=oneline` - Incorrect: - `\--pretty=oneline` - If some place in the documentation needs to typeset a command usage example with inline substitutions, it is fine to use +monospaced and inline substituted text+ instead of `monospaced literal text`, and with diff --git a/Documentation/Makefile b/Documentation/Makefile index f5605b7..3f2383a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,3 +1,6 @@ +# Import tree-wide shared Makefile behavior and libraries +include ../shared.mak + # Guard against environment variables MAN1_TXT = MAN5_TXT = @@ -18,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 @@ -48,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)) @@ -87,28 +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/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 @@ -131,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) @@ -176,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 @@ -214,33 +222,6 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' endif -QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir -QUIET_SUBDIR1 = - -ifneq ($(findstring $(MAKEFLAGS),w),w) -PRINT_DIR = --no-print-directory -else # "make -w" -NO_SUBDIR = : -endif - -ifneq ($(findstring $(MAKEFLAGS),s),s) -ifndef V - QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; - QUIET_XMLTO = @echo ' ' XMLTO $@; - QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; - QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; - QUIET_DBLATEX = @echo ' ' DBLATEX $@; - QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; - QUIET_GEN = @echo ' ' GEN $@; - QUIET_LINT = @echo ' ' LINT $@; - QUIET_STDERR = 2> /dev/null - QUIET_SUBDIR0 = +@subdir= - QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ - $(MAKE) $(PRINT_DIR) -C $$subdir - export V -endif -endif - all: html man html: $(DOC_HTML) @@ -284,7 +265,7 @@ install-html: html ../GIT-VERSION-FILE: FORCE $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE -ifneq ($(MAKECMDGOALS),clean) +ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),) -include ../GIT-VERSION-FILE endif @@ -310,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 @@ -325,12 +308,12 @@ $(mergetools_txt): mergetools-list.made mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) $(QUIET_GEN) \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ + $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=diff && \ . ../git-mergetool--lib.sh && \ - show_tool_names can_diff "* " || :' >mergetools-diff.txt && \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ + show_tool_names can_diff' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-diff.txt && \ + $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=merge && \ . ../git-mergetool--lib.sh && \ - show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ + show_tool_names can_merge' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-merge.txt && \ date >$@ TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) @@ -343,6 +326,7 @@ GIT-ASCIIDOCFLAGS: FORCE fi clean: + $(RM) -rf .build/ $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info $(RM) *.pdf @@ -350,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) @@ -359,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 $@ $< @@ -412,7 +399,7 @@ gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl $(RM) $@+ gitman.info: gitman.texi - $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $< $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@ @@ -456,21 +443,57 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done -lint-docs:: - $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \ +## Lint: gitlink +LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT)) +$(LINT_DOCS_GITLINK): lint-gitlink.perl +$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt + $(call mkdir_p_parent_template) + $(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \ + $< \ $(HOWTO_TXT) $(DOC_DEP_TXT) \ --section=1 $(MAN1_TXT) \ --section=5 $(MAN5_TXT) \ - --section=7 $(MAN7_TXT); \ - $(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT); \ - $(PERL_PATH) lint-man-section-order.perl $(MAN_TXT); + --section=7 $(MAN7_TXT) >$@ +.PHONY: lint-docs-gitlink +lint-docs-gitlink: $(LINT_DOCS_GITLINK) + +## Lint: man-end-blurb +LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT)) +$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl +$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt + $(call mkdir_p_parent_template) + $(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@ +.PHONY: lint-docs-man-end-blurb + +## Lint: man-section-order +LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT)) +$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl +$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt + $(call mkdir_p_parent_template) + $(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@ +.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 ifeq ($(wildcard po/Makefile),po/Makefile) doc-l10n install-l10n:: $(MAKE) -C po $@ endif -# Delete the target file on error -.DELETE_ON_ERROR: - .PHONY: FORCE diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 015cf24..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 @@ -710,13 +712,104 @@ dependencies. `prove` also makes the output nicer. Go ahead and commit this change, as well. [[ready-to-share]] -== Getting Ready to Share +== Getting Ready to Share: Anatomy of a Patch Series You may have noticed already that the Git project performs its code reviews via emailed patches, which are then applied by the maintainer when they are ready -and approved by the community. The Git project does not accept patches from +and approved by the community. The Git project does not accept contributions from pull requests, and the patches emailed for review need to be formatted a -specific way. At this point the tutorial diverges, in order to demonstrate two +specific way. + +:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/ +:lore: https://lore.kernel.org/git/ + +Before taking a look at how to convert your commits into emailed patches, +let's analyze what the end result, a "patch series", looks like. Here is an +{patch-series}[example] of the summary view for a patch series on the web interface of +the {lore}[Git mailing list archive]: + +---- +2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget +2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget +2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message] +2022-02-18 19:39 ` Taylor Blau +2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:35 ` Taylor Blau +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 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 +2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason +2022-02-19 0:21 ` Taylor Blau +2022-02-22 2:36 ` John Cai +2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason +2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget +2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget +2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason +2022-02-23 21:27 ` Junio C Hamano +// continued +---- + +We can note a few things: + +- Each commit is sent as a separate email, with the commit message title as + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an + _n_-commit series. +- Each patch is sent as a reply to an introductory email called the _cover + letter_ of the series, prefixed "[PATCH 0/_n_]". +- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH + v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of + three patches in the second iteration. Each iteration is sent with a new cover + letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the + previous iteration (more on that below). + +NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without +_i_/_n_ numbering (in the above thread overview, no single-patch topic appears, +though). + +[[cover-letter]] +=== The cover letter + +In addition to an email per patch, the Git community also expects your patches +to come with a cover letter. This is an important component of change +submission as it explains to the community from a high level what you're trying +to do, and why, in a way that's more apparent than just looking at your +patches. + +The title of your cover letter should be something which succinctly covers the +purpose of your entire topic branch. It's often in the imperative mood, just +like our commit message titles. Here is how we'll title our series: + +--- +Add the 'psuh' command +--- + +The body of the cover letter is used to give additional context to reviewers. +Be sure to explain anything your patches don't make clear on their own, but +remember that since the cover letter is not recorded in the commit history, +anything that might be useful to future readers of the repository's history +should also be in your commit messages. + +Here's an example body for `psuh`: + +---- +Our internal metrics indicate widespread interest in the command +git-psuh - that is, many users are trying to use it, but finding it is +unavailable, using some unknown workaround instead. + +The following handful of patches add the psuh command and implement some +handy features on top of it. + +This patchset is part of the MyFirstContribution tutorial and should not +be merged. +---- + +At this point the tutorial diverges, in order to demonstrate two different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those @@ -741,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 @@ -808,8 +901,22 @@ https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch. -Review the PR's title and description, as it's used by GitGitGadget as the cover -letter for your change. When you're happy, submit your pull request. +Review the PR's title and description, as they're used by GitGitGadget +respectively as the subject and body of the cover letter for your change. Refer +to <<cover-letter,"The cover letter">> above for advice on how to title your +submission and what content to include in the description. + +NOTE: For single-patch contributions, your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, so you usually do not need any additional context. In that case, +remove the PR description that GitHub automatically generates from your commit +message (your PR description should be empty). If you do need to supply even +more context, you can do so in that space and it will be appended to the email +that GitGitGadget will send, between the three-dash line and the diffstat +(see <<single-patch,Bonus Chapter: One-Patch Changes>> for how this looks once +submitted). + +When you're happy, submit your pull request. [[run-ci-ggg]] === Running CI and Getting Ready to Send @@ -905,19 +1012,34 @@ Sending emails with Git is a two-part process; before you can prepare the emails themselves, you'll need to prepare the patches. Luckily, this is pretty simple: ---- -$ git format-patch --cover-letter -o psuh/ master..psuh +$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh ---- -The `--cover-letter` parameter tells `format-patch` to create a cover letter -template for you. You will need to fill in the template before you're ready -to send - but for now, the template will be next to your other patches. + . The `--cover-letter` option tells `format-patch` to create a + cover letter template for you. You will need to fill in the + template before you're ready to send - but for now, the template + will be next to your other patches. -The `-o psuh/` parameter tells `format-patch` to place the patch files into a -directory. This is useful because `git send-email` can take a directory and -send out all the patches from there. + . The `-o psuh/` option tells `format-patch` to place the patch + files into a directory. This is useful because `git send-email` + can take a directory and send out all the patches from there. -`master..psuh` tells `format-patch` to generate patches for the difference -between `master` and `psuh`. It will make one patch file per commit. After you + . The `--base=auto` option tells the command to record the "base + commit", on which the recipient is expected to apply the patch + series. The `auto` value will cause `format-patch` to compute + the base commit automatically, which is the merge base of tip + commit of the remote-tracking branch and the specified revision + range. + + . The `psuh@{u}..psuh` option tells `format-patch` to generate + patches for the commits you created on the `psuh` branch since it + forked from its upstream (which is `origin/master` if you + followed the example in the "Set up your workspace" section). If + you are already on the `psuh` branch, you can just say `@{u}`, + which means "commits on the current branch since it forked from + its upstream", which is the same thing. + +The command will make one patch file per commit. After you run, you can go have a look at each of the patches with your favorite text editor and make sure everything looks alright; however, it's not recommended to make code fixups via the patch file. It's a better idea to make the change the @@ -937,49 +1059,29 @@ but want reviewers to look at what they have so far. You can add this flag with Check and make sure that your patches and cover letter template exist in the directory you specified - you're nearly ready to send out your review! -[[cover-letter]] +[[preparing-cover-letter]] === Preparing Email -In addition to an email per patch, the Git community also expects your patches -to come with a cover letter, typically with a subject line [PATCH 0/x] (where -x is the number of patches you're sending). Since you invoked `format-patch` -with `--cover-letter`, you've already got a template ready. Open it up in your -favorite editor. +Since you invoked `format-patch` with `--cover-letter`, you've already got a +cover letter template ready. Open it up in your favorite editor. You should see a number of headers present already. Check that your `From:` -header is correct. Then modify your `Subject:` to something which succinctly -covers the purpose of your entire topic branch, for example: +header is correct. Then modify your `Subject:` (see <<cover-letter,above>> for +how to choose good title for your patch series): ---- -Subject: [PATCH 0/7] adding the 'psuh' command +Subject: [PATCH 0/7] Add the 'psuh' command ---- Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git -community that this email is the beginning of a review, and many reviewers -filter their email for this type of flag. +community that this email is the beginning of a patch series, and many +reviewers filter their email for this type of flag. You'll need to add some extra parameters when you invoke `git send-email` to add the cover letter. -Next you'll have to fill out the body of your cover letter. This is an important -component of change submission as it explains to the community from a high level -what you're trying to do, and why, in a way that's more apparent than just -looking at your diff. Be sure to explain anything your diff doesn't make clear -on its own. - -Here's an example body for `psuh`: - ----- -Our internal metrics indicate widespread interest in the command -git-psuh - that is, many users are trying to use it, but finding it is -unavailable, using some unknown workaround instead. - -The following handful of patches add the psuh command and implement some -handy features on top of it. - -This patchset is part of the MyFirstContribution tutorial and should not -be merged. ----- +Next you'll have to fill out the body of your cover letter. Again, see +<<cover-letter,above>> for what content to include. The template created by `git format-patch --cover-letter` includes a diffstat. This gives reviewers a summary of what they're in for when reviewing your topic. @@ -1029,43 +1131,63 @@ kidding - be patient!) [[v2-git-send-email]] === Sending v2 -Skip ahead to <<reviewing,Responding to Reviews>> for information on how to -handle comments from reviewers. Continue this section when your topic branch is -shaped the way you want it to look for your patchset v2. +This section will focus on how to send a v2 of your patchset. To learn what +should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for +information on how to handle comments from reviewers. -When you're ready with the next iteration of your patch, the process is fairly -similar. +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll +mark the tip of our v1 branch for easy reference: -First, generate your v2 patches again: +---- +$ git checkout psuh +$ git branch psuh-v1 +---- + +Refine your patch series by using `git rebase -i` to adjust commits based upon +reviewer comments. Once the patch series is ready for submission, generate your +patches again, but with some new flags: ---- -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master.. ---- -This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`, -to the `psuh/` directory. You may notice that they are sitting alongside the v1 -patches; that's fine, but be careful when you are ready to send them. +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a +range-diff between `psuh-v1` and `psuh` in the cover letter (see +linkgit:git-range-diff[1]). This helps tell reviewers about the differences +between your v1 and v2 patches. + +The `-v2` parameter tells `format-patch` to output your patches +as version "2". For instance, you may notice that your v2 patches are +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". + +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). 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 @@ -1082,7 +1204,7 @@ to the command: ---- $ git send-email --to=target@example.com --in-reply-to="<foo.12345.author@example.com>" - psuh/v2* + psuh/v2-*.patch ---- [[single-patch]] @@ -1136,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 2d10eea..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,23 +50,29 @@ 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). +We'll need to include the `parse-options.h` header. ---- +#include "parse-options.h" + +... + int cmd_walken(int argc, const char **argv, const char *prefix) { const char * const walken_usage[] = { N_("git walken"), NULL, - } + }; struct option options[] = { OPT_END() }; @@ -119,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: @@ -195,16 +202,22 @@ Similarly to the default values, we don't have anything to do here yet ourselves; however, we should call `git_default_config()` if we aren't calling any other existing config callbacks. -Add a new function to `builtin/walken.c`: +Add a new function to `builtin/walken.c`. +We'll also need to include the `config.h` header: ---- -static int git_walken_config(const char *var, const char *value, void *cb) +#include "config.h" + +... + +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); } ---- @@ -229,8 +242,14 @@ typically done by calling `repo_init_revisions()` with the repository you intend to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info` struct. -Add the `struct rev_info` and the `repo_init_revisions()` call: +Add the `struct rev_info` and the `repo_init_revisions()` call. +We'll also need to include the `revision.h` header: + ---- +#include "revision.h" + +... + int cmd_walken(int argc, const char **argv, const char *prefix) { /* This can go wherever you like in your declarations.*/ @@ -325,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; @@ -367,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); } ---- @@ -501,29 +525,30 @@ 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 the name, these functions traverse all kinds of objects. Let's have a look at -the arguments to `traverse_commit_list_filtered()`, which are a superset of the -arguments to the unfiltered version. +the arguments to `traverse_commit_list()`. -- `struct list_objects_filter_options *filter_options`: This is a struct which - stores a filter-spec as outlined in `Documentation/rev-list-options.txt`. -- `struct rev_info *revs`: This is the `rev_info` used for the walk. +- `struct rev_info *revs`: This is the `rev_info` used for the walk. If + its `filter` member is not `NULL`, then `filter` contains information for + how to filter the object list. - `show_commit_fn show_commit`: A callback which will be used to handle each individual commit object. - `show_object_fn show_object`: A callback which will be used to handle each non-commit object (so each blob, tree, or tag). - `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 parameter: + - `struct oidset *omitted`: A linked-list of object IDs which the provided filter caused to be omitted. -It looks like this `traverse_commit_list_filtered()` uses callbacks we provide -instead of needing us to call it repeatedly ourselves. Cool! Let's add the -callbacks first. +It looks like these methods use callbacks we provide instead of needing us +to call it repeatedly ourselves. Cool! Let's add the callbacks first. For the sake of this tutorial, we'll simply keep track of how many of each kind of object we find. At file scope in `builtin/walken.c` add the following @@ -624,9 +649,14 @@ static void walken_object_walk(struct rev_info *rev) ---- Let's start by calling just the unfiltered walk and reporting our counts. -Complete your implementation of `walken_object_walk()`: +Complete your implementation of `walken_object_walk()`. +We'll also need to include the `list-objects.h` header. ---- +#include "list-objects.h" + +... + traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL); printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count, @@ -691,20 +721,9 @@ help understand. In our case, that means we omit trees and blobs not directly referenced by `HEAD` or `HEAD`'s history, because we begin the walk with only `HEAD` in the `pending` list.) -First, we'll need to `#include "list-objects-filter-options.h`" and set up the -`struct list_objects_filter_options` at the top of the function. - ----- -static void walken_object_walk(struct rev_info *rev) -{ - struct list_objects_filter_options filter_options = {}; - - ... ----- - For now, we are not going to track the omitted objects, so we'll replace those parameters with `NULL`. For the sake of simplicity, we'll add a simple -build-time branch to use our filter or not. Replace the line calling +build-time branch to use our filter or not. Preface the line calling `traverse_commit_list()` with the following, which will remind us which kind of walk we've just performed: @@ -712,19 +731,17 @@ walk we've just performed: if (0) { /* Unfiltered: */ trace_printf(_("Unfiltered object walk.\n")); - traverse_commit_list(rev, walken_show_commit, - walken_show_object, NULL); } else { trace_printf( _("Filtered object walk with filterspec 'tree:1'.\n")); - parse_list_objects_filter(&filter_options, "tree:1"); - traverse_commit_list_filtered(&filter_options, rev, - walken_show_commit, walken_show_object, NULL, NULL); + parse_list_objects_filter(&rev->filter, "tree:1"); } + traverse_commit_list(rev, walken_show_commit, + walken_show_object, NULL); ---- -`struct list_objects_filter_options` is usually built directly from a command +The `rev->filter` member is usually built directly from a command line argument, so the module provides an easy way to build one from a string. Even though we aren't taking user input right now, we can still build one with a hardcoded string using `parse_list_objects_filter()`. @@ -737,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( ... @@ -757,13 +780,14 @@ 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: ---- ... - traverse_commit_list_filtered(&filter_options, rev, + traverse_commit_list_filtered(rev, walken_show_commit, walken_show_object, NULL, &omitted); ... @@ -779,7 +803,7 @@ Count all the objects within and modify the print statement: while ((oid = oidset_iter_next(&oit))) omitted_count++; - printf("commits %d\nblobs %d\ntags %d\ntrees%d\nomitted %d\n", + printf("commits %d\nblobs %d\ntags %d\ntrees %d\nomitted %d\n", commit_count, blob_count, tag_count, tree_count, omitted_count); ---- @@ -796,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)); @@ -820,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 @@ -848,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.3.txt b/Documentation/RelNotes/2.30.3.txt new file mode 100644 index 0000000..31b2a4d --- /dev/null +++ b/Documentation/RelNotes/2.30.3.txt @@ -0,0 +1,24 @@ +Git v2.30.2 Release Notes +========================= + +This release addresses the security issue CVE-2022-24765. + +Fixes since v2.30.2 +------------------- + + * Build fix on Windows. + + * Fix `GIT_CEILING_DIRECTORIES` with Windows-style root directories. + + * CVE-2022-24765: + On multi-user machines, Git users might find themselves + unexpectedly in a Git worktree, e.g. when another user created a + repository in `C:\.git`, in a mounted network drive or in a + scratch space. Merely having a Git-aware prompt that runs `git + status` (or `git diff`) and navigating to a directory which is + supposedly not a Git worktree, or opening such a directory in an + editor or IDE such as VS Code or Atom, will potentially run + commands defined by that other user. + +Credit for finding this vulnerability goes to 俞晨东; The fix was +authored by Johannes Schindelin. diff --git a/Documentation/RelNotes/2.30.4.txt b/Documentation/RelNotes/2.30.4.txt new file mode 100644 index 0000000..4eedb74 --- /dev/null +++ b/Documentation/RelNotes/2.30.4.txt @@ -0,0 +1,21 @@ +Git v2.30.4 Release Notes +========================= + +This release contains minor fix-ups for the changes that went into +Git 2.30.3, which was made to address CVE-2022-24765. + + * The code that was meant to parse the new `safe.directory` + configuration variable was not checking what configuration + variable was being fed to it, which has been corrected. + + * '*' can be used as the value for the `safe.directory` variable to + signal that the user considers that any directory is safe. + + + +Derrick Stolee (2): + t0033: add tests for safe.directory + setup: opt-out of check with safe.directory=* + +Matheus Valadares (1): + setup: fix safe.directory key not being checked 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.2.txt b/Documentation/RelNotes/2.31.2.txt new file mode 100644 index 0000000..aa13a5b --- /dev/null +++ b/Documentation/RelNotes/2.31.2.txt @@ -0,0 +1,6 @@ +Git v2.31.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.3 to address +the security issue CVE-2022-24765; see the release notes for that +version for details. diff --git a/Documentation/RelNotes/2.31.3.txt b/Documentation/RelNotes/2.31.3.txt new file mode 100644 index 0000000..ca143ab --- /dev/null +++ b/Documentation/RelNotes/2.31.3.txt @@ -0,0 +1,4 @@ +Git Documentation/RelNotes/2.31.3.txt Release Notes +========================= + +This release merges up the fixes that appear in v2.31.3. 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.1.txt b/Documentation/RelNotes/2.32.1.txt new file mode 100644 index 0000000..7dcca13 --- /dev/null +++ b/Documentation/RelNotes/2.32.1.txt @@ -0,0 +1,6 @@ +Git v2.32.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.3 and +v2.31.2 to address the security issue CVE-2022-24765; see the +release notes for these versions for details. diff --git a/Documentation/RelNotes/2.32.2.txt b/Documentation/RelNotes/2.32.2.txt new file mode 100644 index 0000000..cf49695 --- /dev/null +++ b/Documentation/RelNotes/2.32.2.txt @@ -0,0 +1,4 @@ +Git Documentation/RelNotes/2.32.2.txt Release Notes +========================= + +This release merges up the fixes that appear in v2.32.2. 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.0.txt b/Documentation/RelNotes/2.33.0.txt index d4c56de..893c18b 100644 --- a/Documentation/RelNotes/2.33.0.txt +++ b/Documentation/RelNotes/2.33.0.txt @@ -1,18 +1,6 @@ Git 2.33 Release Notes ====================== -Backward compatibility notes ----------------------------- - - * The "-m" option in "git log -m" that does not specify which format, - if any, of diff is desired did not have any visible effect; it now - implies some form of diff (by default "--patch") is produced. - - You can disable the diff output with "git log -m --no-patch", but - then there probably isn't much point in passing "-m" in the first - place ;-). - - Updates since Git 2.32 ---------------------- @@ -24,12 +12,14 @@ UI, Workflows & Features "smtp-server" that is meant to name the server to instead name the command to talk to the server. - * The "-m" option in "git log -m" that does not specify which format, - if any, of diff is desired did not have any visible effect; it now - implies some form of diff (by default "--patch") is produced. - * The userdiff pattern for C# learned the token "record". + * "git rev-list" learns to omit the "commit <object-name>" header + lines from the output with the `--no-commit-header` option. + + * "git worktree add --lock" learned to record why the worktree is + locked with a custom message. + Performance, Internal Implementation, Development Support etc. @@ -42,7 +32,7 @@ Performance, Internal Implementation, Development Support etc. reduce code duplication. * Repeated rename detections in a sequence of mergy operations have - been optimize out. + been optimized out for the 'ort' merge strategy. * Preliminary clean-up of tests before the main reftable changes hits the codebase. @@ -54,6 +44,49 @@ Performance, Internal Implementation, Development Support etc. * Code cleanup around struct_type_init() functions. + * "git send-email" optimization. + + * GitHub Actions / CI update. + (merge 0dc787a9f2 js/ci-windows-update later to maint). + + * Object accesses in repositories with many alternate object store + have been optimized. + + * "git log" has been optimized not to waste cycles to load ref + decoration data that may not be needed. + + * Many "printf"-like helper functions we have have been annotated + with __attribute__() to catch placeholder/parameter mismatches. + + * Tests that cover protocol bits have been updated and helpers + used there have been consolidated. + + * The CI gained a new job to run "make sparse" check. + + * "git status" codepath learned to work with sparsely populated index + without hydrating it fully. + + * A guideline for gender neutral documentation has been added. + + * Documentation on "git diff -l<n>" and diff.renameLimit have been + updated, and the defaults for these limits have been raised. + + * The completion support used to offer alternate spelling of options + that exist only for compatibility, which has been corrected. + + * "TEST_OUTPUT_DIRECTORY=there make test" failed to work, which has + been corrected. + + * "git bundle" gained more test coverage. + + * "git read-tree" had a codepath where blobs are fetched one-by-one + from the promisor remote, which has been corrected to fetch in bulk. + + * Rewrite of "git submodule" in C continues. + + * "git checkout" and "git commit" learn to work without unnecessarily + expanding sparse indexes. + Fixes since v2.32 ----------------- @@ -175,6 +208,32 @@ Fixes since v2.32 and adds to guidelines to do so. (merge 46a237f42f ds/gender-neutral-doc later to maint). + * "git commit --allow-empty-message" won't abort the operation upon + an empty message, but the hint shown in the editor said otherwise. + (merge 6f70f00b4f hj/commit-allow-empty-message later to maint). + + * The code that gives an error message in "git multi-pack-index" when + no subcommand is given tried to print a NULL pointer as a strong, + which has been corrected. + (merge 88617d11f9 tb/reverse-midx later to maint). + + * CI update. + (merge a066a90db6 js/ci-check-whitespace-updates later to maint). + + * Documentation fix for "git pull --rebase=no". + (merge d3236becec fc/pull-no-rebase-merges-theirs-into-ours later to maint). + + * A race between repacking and using pack bitmaps has been corrected. + (merge dc1daacdcc jk/check-pack-valid-before-opening-bitmap later to maint). + + * The local changes stashed by "git merge --autostash" were lost when + the merge failed in certain ways, which has been corrected. + + * Windows rmdir() equivalent behaves differently from POSIX ones in + that when used on a symbolic link that points at a directory, the + target directory gets removed, which has been corrected. + (merge 3e7d4888e5 tb/mingw-rmdir-symlink-to-directory later to maint). + * Other code cleanup, docfix, build fix, etc. (merge bfe35a6165 ah/doc-describe later to maint). (merge f302c1e4aa jc/clarify-revision-range later to maint). @@ -208,3 +267,13 @@ Fixes since v2.32 (merge 617480d75b hn/refs-iterator-peel-returns-boolean later to maint). (merge 6a24cc71ed ar/submodule-helper-include-cleanup later to maint). (merge 5632e838f8 rs/khash-alloc-cleanup later to maint). + (merge b1d87fbaf1 jk/typofix later to maint). + (merge e04170697a ab/gitignore-discovery-doc later to maint). + (merge 8232a0ff48 dl/packet-read-response-end-fix later to maint). + (merge eb448631fb dl/diff-merge-base later to maint). + (merge c510928a25 hn/refs-debug-empty-prefix later to maint). + (merge ddcb189d9d tb/bitmap-type-filter-comment-fix later to maint). + (merge 878b399734 pb/submodule-recurse-doc later to maint). + (merge 734283855f jk/config-env-doc later to maint). + (merge 482e1488a9 ab/getcwd-test later to maint). + (merge f0b922473e ar/doc-markup-fix later to maint). diff --git a/Documentation/RelNotes/2.33.1.txt b/Documentation/RelNotes/2.33.1.txt new file mode 100644 index 0000000..b71738e --- /dev/null +++ b/Documentation/RelNotes/2.33.1.txt @@ -0,0 +1,138 @@ +Git 2.33.1 Release Notes +======================== + +This primarily is to backport various fixes accumulated during the +development towards Git 2.34, the next feature release. + + +Fixes since v2.33 +----------------- + + * The unicode character width table (used for output alignment) has + been updated. + + * Input validation of "git pack-objects --stdin-packs" has been + corrected. + + * Bugfix for common ancestor negotiation recently introduced in "git + push" codepath. + + * "git pull" had various corner cases that were not well thought out + around its --rebase backend, e.g. "git pull --ff-only" did not stop + but went ahead and rebased when the history on other side is not a + descendant of our history. The series tries to fix them up. + + * "git apply" miscounted the bytes and failed to read to the end of + binary hunks. + + * "git range-diff" code clean-up. + + * "git commit --fixup" now works with "--edit" again, after it was + broken in v2.32. + + * Use upload-artifacts v1 (instead of v2) for 32-bit linux, as the + new version has a blocker bug for that architecture. + + * Checking out all the paths from HEAD during the last conflicted + step in "git rebase" and continuing would cause the step to be + skipped (which is expected), but leaves MERGE_MSG file behind in + $GIT_DIR and confuses the next "git commit", which has been + corrected. + + * Various bugs in "git rebase -r" have been fixed. + + * mmap() imitation used to call xmalloc() that dies upon malloc() + failure, which has been corrected to just return an error to the + caller to be handled. + + * "git diff --relative" segfaulted and/or produced incorrect result + when there are unmerged paths. + + * The delayed checkout code path in "git checkout" etc. were chatty + even when --quiet and/or --no-progress options were given. + + * "git branch -D <branch>" used to refuse to remove a broken branch + ref that points at a missing commit, which has been corrected. + + * Build update for Apple clang. + + * The parser for the "--nl" option of "git column" has been + corrected. + + * "git upload-pack" which runs on the other side of "git fetch" + forgot to take the ref namespaces into account when handling + want-ref requests. + + * The sparse-index support can corrupt the index structure by storing + a stale and/or uninitialized data, which has been corrected. + + * Buggy tests could damage repositories outside the throw-away test + area we created. We now by default export GIT_CEILING_DIRECTORIES + to limit the damage from such a stray test. + + * Even when running "git send-email" without its own threaded + discussion support, a threading related header in one message is + carried over to the subsequent message to result in an unwanted + threading, which has been corrected. + + * The output from "git fast-export", when its anonymization feature + is in use, showed an annotated tag incorrectly. + + * Recent "diff -m" changes broke "gitk", which has been corrected. + + * "git maintenance" scheduler fix for macOS. + + * A pathname in an advice message has been made cut-and-paste ready. + + * The "git apply -3" code path learned not to bother the lower level + merge machinery when the three-way merge can be trivially resolved + without the content level merge. + + * The code that optionally creates the *.rev reverse index file has + been optimized to avoid needless computation when it is not writing + the file out. + + * "git range-diff -I... <range> <range>" segfaulted, which has been + corrected. + + * The order in which various files that make up a single (conceptual) + packfile has been reevaluated and straightened up. This matters in + correctness, as an incomplete set of files must not be shown to a + running Git. + + * The "mode" word is useless in a call to open(2) that does not + create a new file. Such a call in the files backend of the ref + subsystem has been cleaned up. + + * "git update-ref --stdin" failed to flush its output as needed, + which potentially led the conversation to a deadlock. + + * When "git am --abort" fails to abort correctly, it still exited + with exit status of 0, which has been corrected. + + * Correct nr and alloc members of strvec struct to be of type size_t. + + * "git stash", where the tentative change involves changing a + directory to a file (or vice versa), was confused, which has been + corrected. + + * "git clone" from a repository whose HEAD is unborn into a bare + repository didn't follow the branch name the other side used, which + is corrected. + + * "git cvsserver" had a long-standing bug in its authentication code, + which has finally been corrected (it is unclear and is a separate + question if anybody is seriously using it, though). + + * "git difftool --dir-diff" mishandled symbolic links. + + * Sensitive data in the HTTP trace were supposed to be redacted, but + we failed to do so in HTTP/2 requests. + + * "make clean" has been updated to remove leftover .depend/ + directories, even when it is not told to use them to compute header + dependencies. + + * Protocol v0 clients can get stuck parsing a malformed feature line. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.33.2.txt b/Documentation/RelNotes/2.33.2.txt new file mode 100644 index 0000000..e504489 --- /dev/null +++ b/Documentation/RelNotes/2.33.2.txt @@ -0,0 +1,15 @@ +Git v2.33.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.3, v2.31.2 +and v2.32.1 to address the security issue CVE-2022-24765; see +the release notes for these versions for details. + +In addition, it contains the following fixes: + + * Squelch over-eager warning message added during this cycle. + + * A bug in "git rebase -r" has been fixed. + + * One CI task based on Fedora image noticed a not-quite-kosher + construct recently, which has been corrected. diff --git a/Documentation/RelNotes/2.33.3.txt b/Documentation/RelNotes/2.33.3.txt new file mode 100644 index 0000000..e2bada1 --- /dev/null +++ b/Documentation/RelNotes/2.33.3.txt @@ -0,0 +1,4 @@ +Git Documentation/RelNotes/2.33.3.txt Release Notes +========================= + +This release merges up the fixes that appear in v2.33.3. 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.0.txt b/Documentation/RelNotes/2.34.0.txt new file mode 100644 index 0000000..75d4fdf --- /dev/null +++ b/Documentation/RelNotes/2.34.0.txt @@ -0,0 +1,438 @@ +Git 2.34 Release Notes +====================== + +Updates since Git 2.33 +---------------------- + +Backward compatibility notes + + * The "--preserve-merges" option of "git rebase" has been removed. + + +UI, Workflows & Features + + * Pathname expansion (like "~username/") learned a way to specify a + location relative to Git installation (e.g. its $sharedir which is + $(prefix)/share), with "%(prefix)". + + * The `ort` strategy is used instead of `recursive` as the default + merge strategy. + + * The userdiff pattern for "java" language has been updated. + + * "git rebase" by default skips changes that are equivalent to + commits that are already in the history the branch is rebased onto; + give messages when this happens to let the users be aware of + skipped commits, and also teach them how to tell "rebase" to keep + duplicated changes. + + * The advice message that "git cherry-pick" gives when it asks + conflicted replay of a commit to be resolved by the end user has + been updated. + + * After "git clone --recurse-submodules", all submodules are cloned + but they are not by default recursed into by other commands. With + submodule.stickyRecursiveClone configuration set, submodule.recurse + configuration is set to true in a repository created by "clone" + with "--recurse-submodules" option. + + * The logic for auto-correction of misspelt subcommands learned to go + interactive when the help.autocorrect configuration variable is set + to 'prompt'. + + * "git maintenance" scheduler learned to use systemd timers as a + possible backend. + + * "git diff --submodule=diff" showed failure from run_command() when + trying to run diff inside a submodule, when the user manually + removes the submodule directory. + + * "git bundle unbundle" learned to show progress display. + + * In cone mode, the sparse-index code path learned to remove ignored + files (like build artifacts) outside the sparse cone, allowing the + entire directory outside the sparse cone to be removed, which is + especially useful when the sparse patterns change. + + * Taking advantage of the CGI interface, http-backend has been + updated to enable protocol v2 automatically when the other side + asks for it. + + * The credential-cache helper has been adjusted to Windows. + + * The error in "git help no-such-git-command" is handled better. + + * The unicode character width table (used for output alignment) has + been updated. + + * The ref iteration code used to optionally allow dangling refs to be + shown, which has been tightened up. + + * "git add", "git mv", and "git rm" have been adjusted to avoid + updating paths outside of the sparse-checkout definition unless + the user specifies a "--sparse" option. + + * "git repack" has been taught to generate multi-pack reachability + bitmaps. + + * "git fsck" has been taught to report mismatch between expected and + actual types of an object better. + + * In addition to GnuPG, ssh public crypto can be used for object and + push-cert signing. Note that this feature cannot be used with + ssh-keygen from OpenSSH 8.7, whose support for it is broken. Avoid + using it unless you update to OpenSSH 8.8. + + * "git log --grep=string --author=name" learns to highlight hits just + like "git grep string" does. + + + +Performance, Internal Implementation, Development Support etc. + + * "git bisect" spawned "git show-branch" only to pretty-print the + title of the commit after checking out the next version to be + tested; this has been rewritten in C. + + * "git add" can work better with the sparse index. + + * Support for ancient versions of cURL library (pre 7.19.4) has been + dropped. + + * A handful of tests that assumed implementation details of files + backend for refs have been cleaned up. + + * trace2 logs learned to show parent process name to see in what + context Git was invoked. + + * Loading of ref tips to prepare for common ancestry negotiation in + "git fetch-pack" has been optimized by taking advantage of the + commit graph when available. + + * Remind developers that the userdiff patterns should be kept simple + and permissive, assuming that the contents they apply are always + syntactically correct. + + * The current implementation of GIT_TEST_FAIL_PREREQS is broken in + that checking for the lack of a prerequisite would not work. Avoid + the use of "if ! test_have_prereq X" in a test script. + + * The revision traversal API has been optimized by taking advantage + of the commit-graph, when available, to determine if a commit is + reachable from any of the existing refs. + + * "git fetch --quiet" optimization to avoid useless computation of + info that will never be displayed. + + * Callers from older advice_config[] based API has been updated to + use the newer advice_if_enabled() and advice_enabled() API. + + * Teach "test_pause" and "debug" helpers to allow using the HOME and + TERM environment variables the user usually uses. + + * "make INSTALL_STRIP=-s install" allows the installation step to use + "install -s" to strip the binaries as they get installed. + + * Code that handles large number of refs in the "git fetch" code + path has been optimized. + + * The reachability bitmap file used to be generated only for a single + pack, but now we've learned to generate bitmaps for history that + span across multiple packfiles. + + * The code to make "git grep" recurse into submodules has been + updated to migrate away from the "add submodule's object store as + an alternate object store" mechanism (which is suboptimal). + + * The tracing of process ancestry information has been enhanced. + + * Reduce number of write(2) system calls while sending the + ref advertisement. + + * Update the build procedure to use the "-pedantic" build when + DEVELOPER makefile macro is in effect. + + * Large part of "git submodule add" gets rewritten in C. + + * The run-command API has been updated so that the callers can easily + ask the file descriptors open for packfiles to be closed immediately + before spawning commands that may trigger auto-gc. + + * An oddball OPTION_ARGUMENT feature has been removed from the + parse-options API. + + * The mergesort implementation used to sort linked list has been + optimized. + + * Remove external declaration of functions that no longer exist. + + * "git multi-pack-index write --bitmap" learns to propagate the + hashcache from original bitmap to resulting bitmap. + + * CI learns to run the leak sanitizer builds. + + * "git grep --recurse-submodules" takes trees and blobs from the + submodule repository, but the textconv settings when processing a + blob from the submodule is not taken from the submodule repository. + A test is added to demonstrate the issue, without fixing it. + + * Teach "git help -c" into helping the command line completion of + configuration variables. + + * When "git cmd -h" shows more than one line of usage text (e.g. + the cmd subcommand may take sub-sub-command), parse-options API + learned to align these lines, even across i18n/l10n. + + * Prevent "make sparse" from running for the source files that + haven't been modified. + + * The code path to write a new version of .midx multi-pack index files + has learned to release the mmaped memory holding the current + version of .midx before removing them from the disk, as some + platforms do not allow removal of a file that still has mapping. + + * A new feature has been added to abort early in the test framework. + + +Fixes since v2.33 +----------------- + + * Input validation of "git pack-objects --stdin-packs" has been + corrected. + + * Bugfix for common ancestor negotiation recently introduced in "git + push" code path. + + * "git pull" had various corner cases that were not well thought out + around its --rebase backend, e.g. "git pull --ff-only" did not stop + but went ahead and rebased when the history on other side is not a + descendant of our history. The series tries to fix them up. + + * "git apply" miscounted the bytes and failed to read to the end of + binary hunks. + + * "git range-diff" code clean-up. + + * "git commit --fixup" now works with "--edit" again, after it was + broken in v2.32. + + * Use upload-artifacts v1 (instead of v2) for 32-bit linux, as the + new version has a blocker bug for that architecture. + + * Checking out all the paths from HEAD during the last conflicted + step in "git rebase" and continuing would cause the step to be + skipped (which is expected), but leaves MERGE_MSG file behind in + $GIT_DIR and confuses the next "git commit", which has been + corrected. + + * Various bugs in "git rebase -r" have been fixed. + + * mmap() imitation used to call xmalloc() that dies upon malloc() + failure, which has been corrected to just return an error to the + caller to be handled. + + * "git diff --relative" segfaulted and/or produced incorrect result + when there are unmerged paths. + + * The delayed checkout code path in "git checkout" etc. were chatty + even when --quiet and/or --no-progress options were given. + + * "git branch -D <branch>" used to refuse to remove a broken branch + ref that points at a missing commit, which has been corrected. + + * Build update for Apple clang. + + * The parser for the "--nl" option of "git column" has been + corrected. + + * "git upload-pack" which runs on the other side of "git fetch" + forgot to take the ref namespaces into account when handling + want-ref requests. + + * The sparse-index support can corrupt the index structure by storing + a stale and/or uninitialized data, which has been corrected. + + * Buggy tests could damage repositories outside the throw-away test + area we created. We now by default export GIT_CEILING_DIRECTORIES + to limit the damage from such a stray test. + + * Even when running "git send-email" without its own threaded + discussion support, a threading related header in one message is + carried over to the subsequent message to result in an unwanted + threading, which has been corrected. + + * The output from "git fast-export", when its anonymization feature + is in use, showed an annotated tag incorrectly. + + * Recent "diff -m" changes broke "gitk", which has been corrected. + + * The "git apply -3" code path learned not to bother the lower level + merge machinery when the three-way merge can be trivially resolved + without the content level merge. This fixes a regression caused by + recent "-3way first and fall back to direct application" change. + + * The code that optionally creates the *.rev reverse index file has + been optimized to avoid needless computation when it is not writing + the file out. + + * "git range-diff -I... <range> <range>" segfaulted, which has been + corrected. + + * The order in which various files that make up a single (conceptual) + packfile has been reevaluated and straightened up. This matters in + correctness, as an incomplete set of files must not be shown to a + running Git. + + * The "mode" word is useless in a call to open(2) that does not + create a new file. Such a call in the files backend of the ref + subsystem has been cleaned up. + + * "git update-ref --stdin" failed to flush its output as needed, + which potentially led the conversation to a deadlock. + + * When "git am --abort" fails to abort correctly, it still exited + with exit status of 0, which has been corrected. + + * Correct nr and alloc members of strvec struct to be of type size_t. + + * "git stash", where the tentative change involves changing a + directory to a file (or vice versa), was confused, which has been + corrected. + + * "git clone" from a repository whose HEAD is unborn into a bare + repository didn't follow the branch name the other side used, which + is corrected. + + * "git cvsserver" had a long-standing bug in its authentication code, + which has finally been corrected (it is unclear and is a separate + question if anybody is seriously using it, though). + + * "git difftool --dir-diff" mishandled symbolic links. + + * Sensitive data in the HTTP trace were supposed to be redacted, but + we failed to do so in HTTP/2 requests. + + * "make clean" has been updated to remove leftover .depend/ + directories, even when it is not told to use them to compute header + dependencies. + + * Protocol v0 clients can get stuck parsing a malformed feature line. + + * A few kinds of changes "git status" can show were not documented. + (merge d2a534c515 ja/doc-status-types-and-copies later to maint). + + * The mergesort implementation used to sort linked list has been + optimized. + (merge c90cfc225b rs/mergesort later to maint). + + * An editor session launched during a Git operation (e.g. during 'git + commit') can leave the terminal in a funny state. The code path + has updated to save the terminal state before, and restore it + after, it spawns an editor. + (merge 3d411afabc cm/save-restore-terminal later to maint). + + * "git cat-file --batch" with the "--batch-all-objects" option is + supposed to iterate over all the objects found in a repository, but + it used to translate these object names using the replace mechanism, + which defeats the point of enumerating all objects in the repository. + This has been corrected. + (merge bf972896d7 jk/cat-file-batch-all-wo-replace later to maint). + + * Recent sparse-index work broke safety against attempts to add paths + with trailing slashes to the index, which has been corrected. + (merge c8ad9d04c6 rs/make-verify-path-really-verify-again later to maint). + + * The "--color-lines" and "--color-by-age" options of "git blame" + have been missing, which are now documented. + (merge 8c32856133 bs/doc-blame-color-lines later to maint). + + * The PATH used in CI job may be too wide and let incompatible dlls + to be grabbed, which can cause the build&test to fail. Tighten it. + (merge 7491ef6198 js/windows-ci-path-fix later to maint). + + * Avoid performance measurements from getting ruined by gc and other + housekeeping pauses interfering in the middle. + (merge be79131a53 rs/disable-gc-during-perf-tests later to maint). + + * Stop "git add --dry-run" from creating new blob and tree objects. + (merge e578d0311d rs/add-dry-run-without-objects later to maint). + + * "git commit" gave duplicated error message when the object store + was unwritable, which has been corrected. + (merge 4ef91a2d79 ab/fix-commit-error-message-upon-unwritable-object-store later to maint). + + * Recent sparse-index addition, namely any use of index_name_pos(), + can expand sparse index entries and breaks any code that walks + cache-tree or existing index entries. One such instance of such a + breakage has been corrected. + + * The xxdiff difftool backend can exit with status 128, which the + difftool-helper that launches the backend takes as a significant + failure, when it is not significant at all. Work it around. + (merge 571f4348dd da/mergetools-special-case-xxdiff-exit-128 later to maint). + + * Improve test framework around unwritable directories. + (merge 5d22e18965 ab/test-cleanly-recreate-trash-directory later to maint). + + * "git push" client talking to an HTTP server did not diagnose the + lack of the final status report from the other side correctly, + which has been corrected. + (merge c5c3486f38 jk/http-push-status-fix later to maint). + + * Update "git archive" documentation and give explicit mention on the + compression level for both zip and tar.gz format. + (merge c4b208c309 bs/archive-doc-compression-level later to maint). + + * Drop "git sparse-checkout" from the list of common commands. + (merge 6a9a50a8af sg/sparse-index-not-that-common-a-command later to maint). + + * "git branch -c/-m new old" was not described to copy config, which + has been corrected. + (merge 8252ec300e jc/branch-copy-doc later to maint). + + * Squelch over-eager warning message added during this cycle. + + * Fix long-standing shell syntax error in the completion script. + (merge 46b0585286 re/completion-fix-test-equality later to maint). + + * Teach "git commit-graph" command not to allow using replace objects + at all, as we do not use the commit-graph at runtime when we see + object replacement. + (merge 095d112f8c ab/ignore-replace-while-working-on-commit-graph later to maint). + + * "git pull --no-verify" did not affect the underlying "git merge". + (merge 47bfdfb3fd ar/fix-git-pull-no-verify later to maint). + + * One CI task based on Fedora image noticed a not-quite-kosher + construct recently, which has been corrected. + + * "git pull --ff-only" and "git pull --rebase --ff-only" should make + it a no-op to attempt pulling from a remote that is behind us, but + instead the command errored out by saying it was impossible to + fast-forward, which may technically be true, but not a useful thing + to diagnose as an error. This has been corrected. + (merge 361cb52383 jc/fix-pull-ff-only-when-already-up-to-date later to maint). + + * The way Cygwin emulates a unix-domain socket, on top of which the + simple-ipc mechanism is implemented, can race with the program on + the other side that wants to use the socket, and briefly make it + appear as a regular file before lstat(2) starts reporting it as a + socket. We now have a workaround on the side that connects to a + unix domain socket. + + * Other code cleanup, docfix, build fix, etc. + (merge f188160be9 ab/bundle-remove-verbose-option later to maint). + (merge 8c6b4332b4 rs/close-pack-leakfix later to maint). + (merge 51b04c05b7 bs/difftool-msg-tweak later to maint). + (merge dd20e4a6db ab/make-compdb-fix later to maint). + (merge 6ffb990dc4 os/status-docfix later to maint). + (merge 100c2da2d3 rs/p3400-lose-tac later to maint). + (merge 76f3b69896 tb/aggregate-ignore-leading-whitespaces later to maint). + (merge 6e4fd8bfcd tz/doc-link-to-bundle-format-fix later to maint). + (merge f6c013dfa1 jc/doc-commit-header-continuation-line later to maint). + (merge ec9a37d69b ab/pkt-line-cleanup later to maint). + (merge 8650c6298c ab/fix-make-lint-docs later to maint). + (merge 1c720357ce ab/test-lib-diff-cleanup later to maint). + (merge 6b615dbece ks/submodule-add-message-fix later to maint). + (merge 203eb8381a jc/doc-format-patch-clarify-auto-base later to maint). + (merge 559664c792 ab/test-lib later to maint). diff --git a/Documentation/RelNotes/2.34.1.txt b/Documentation/RelNotes/2.34.1.txt new file mode 100644 index 0000000..ad404e9 --- /dev/null +++ b/Documentation/RelNotes/2.34.1.txt @@ -0,0 +1,23 @@ +Git v2.34.1 Release Notes +========================= + +This release is primarily to fix a handful of regressions in Git 2.34. + +Fixes since v2.34 +----------------- + + * "git grep" looking in a blob that has non-UTF8 payload was + completely broken when linked with certain versions of PCREv2 + library in the latest release. + + * "git pull" with any strategy when the other side is behind us + should succeed as it is a no-op, but doesn't. + + * An earlier change in 2.34.0 caused JGit application (that abused + GIT_EDITOR mechanism when invoking "git config") to get stuck with + a SIGTTOU signal; it has been reverted. + + * An earlier change that broke .gitignore matching has been reverted. + + * SubmittingPatches document gained a syntactically incorrect mark-up, + which has been corrected. diff --git a/Documentation/RelNotes/2.34.2.txt b/Documentation/RelNotes/2.34.2.txt new file mode 100644 index 0000000..0c32cd8 --- /dev/null +++ b/Documentation/RelNotes/2.34.2.txt @@ -0,0 +1,6 @@ +Git v2.34.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.3, v2.31.2, +v2.32.1 and v2.33.2 to address the security issue CVE-2022-24765; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.34.3.txt b/Documentation/RelNotes/2.34.3.txt new file mode 100644 index 0000000..10f6171 --- /dev/null +++ b/Documentation/RelNotes/2.34.3.txt @@ -0,0 +1,4 @@ +Git Documentation/RelNotes/2.34.3.txt Release Notes +========================= + +This release merges up the fixes that appear in v2.34.3. 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.0.txt b/Documentation/RelNotes/2.35.0.txt new file mode 100644 index 0000000..d69b50d --- /dev/null +++ b/Documentation/RelNotes/2.35.0.txt @@ -0,0 +1,412 @@ +Git 2.35 Release Notes +====================== + +Updates since Git 2.34 +---------------------- + +Backward compatibility warts + + * "_" is now treated as any other URL-valid characters in an URL when + matching the per-URL configuration variable names. + + * The color palette used by "git grep" has been updated to match that + of GNU grep. + + +Note to those who build from the source + + * You may need to define NO_UNCOMPRESS2 Makefile macro if you build + with zlib older than 1.2.9. + + * If your compiler cannot grok C99, the build will fail. See the + instruction at the beginning of git-compat-util.h if this happens + to you. + + +UI, Workflows & Features + + * "git status --porcelain=v2" now show the number of stash entries + with --show-stash like the normal output does. + + * "git stash" learned the "--staged" option to stash away what has + been added to the index (and nothing else). + + * "git var GIT_DEFAULT_BRANCH" is a way to see what name is used for + the newly created branch if "git init" is run. + + * Various operating modes of "git reset" have been made to work + better with the sparse index. + + * "git submodule deinit" for a submodule whose .git metadata + directory is embedded in its working tree refused to work, until + the submodule gets converted to use the "absorbed" form where the + metadata directory is stored in superproject, and a gitfile at the + top-level of the working tree of the submodule points at it. The + command is taught to convert such submodules to the absorbed form + as needed. + + * The completion script (in contrib/) learns that the "--date" + option of commands from the "git log" family takes "human" and + "auto" as valid values. + + * "Zealous diff3" style of merge conflict presentation has been added. + + * The "git log --format=%(describe)" placeholder has been extended to + allow passing selected command-line options to the underlying "git + describe" command. + + * "default" and "reset" have been added to our color palette. + + * The cryptographic signing using ssh keys can specify literal keys + for keytypes whose name do not begin with the "ssh-" prefix by + using the "key::" prefix mechanism (e.g. "key::ecdsa-sha2-nistp256"). + + * "git fetch" without the "--update-head-ok" option ought to protect + a checked out branch from getting updated, to prevent the working + tree that checks it out to go out of sync. The code was written + before the use of "git worktree" got widespread, and only checked + the branch that was checked out in the current worktree, which has + been updated. + + * "git name-rev" has been tweaked to give output that is shorter and + easier to understand. + + * "git apply" has been taught to ignore a message without a patch + with the "--allow-empty" option. It also learned to honor the + "--quiet" option given from the command line. + + * The "init" and "set" subcommands in "git sparse-checkout" have been + unified for a better user experience and performance. + + * Many git commands that deal with working tree files try to remove a + directory that becomes empty (i.e. "git switch" from a branch that + has the directory to another branch that does not would attempt + remove all files in the directory and the directory itself). This + drops users into an unfamiliar situation if the command was run in + a subdirectory that becomes subject to removal due to the command. + The commands have been taught to keep an empty directory if it is + the directory they were started in to avoid surprising users. + + * "git am" learns "--empty=(stop|drop|keep)" option to tweak what is + done to a piece of e-mail without a patch in it. + + * The default merge message prepared by "git merge" records the name + of the current branch; the name can be overridden with a new option + to allow users to pretend a merge is made on a different branch. + + * The way "git p4" shows file sizes in its output has been updated to + use human-readable units. + + * "git -c branch.autosetupmerge=inherit branch new old" makes "new" + to have the same upstream as the "old" branch, instead of marking + "old" itself as its upstream. + + +Performance, Internal Implementation, Development Support etc. + + * The use of errno as a means to carry the nature of error in the ref + API implementation has been reworked and reduced. + + * Teach and encourage first-time contributors to this project to + state the base commit when they submit their topic. + + * The command line completion for "git send-email" options have been + tweaked to make it easier to keep it in sync with the command itself. + + * Ensure that the sparseness of the in-core index matches the + index.sparse configuration specified by the repository immediately + after the on-disk index file is read. + + * Code clean-up to eventually allow information on remotes defined + for an arbitrary repository to be read. + + * Build optimization. + + * Tighten code for testing pack-bitmap. + + * Weather balloon to break people with compilers that do not support + C99. + + * The "reftable" backend for the refs API, without integrating into + the refs subsystem, has been added. + + * More tests are marked as leak-free. + + * The test framework learns to list unsatisfied test prerequisites, + and optionally error out when prerequisites that are expected to be + satisfied are not. + + * The default setting for trace2 event nesting was too low to cause + test failures, which is worked around by bumping it up in the test + framework. + + * Drop support for TravisCI and update test workflows at GitHub. + + * Many tests that used to need GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME + mechanism to force "git" to use 'master' as the default name for + the initial branch no longer need it; the use of the mechanism from + them have been removed. + + * Allow running our tests while disabling fsync. + + * Document the parameters given to the reflog entry iterator callback + functions. + (merge e6e94f34b2 jc/reflog-iterator-callback-doc later to maint). + + * The test helper for refs subsystem learned to write bogus and/or + nonexistent object name to refs to simulate error situations we + want to test Git in. + + * "diff --histogram" optimization. + + * Weather balloon to find compilers that do not grok variable + declaration in the for() loop. + + * diff and blame commands have been taught to work better with sparse + index. + + * The chainlint test script linter in the test suite has been updated. + + * The DEVELOPER=yes build uses -std=gnu99 now. + + * "git format-patch" uses a single rev_info instance and then exits. + Mark the structure with UNLEAK() macro to squelch leak sanitizer. + + * New interface into the tmp-objdir API to help in-core use of the + quarantine feature. + + * Broken &&-chains in the test scripts have been corrected. + + * The RCS keyword substitution in "git p4" used to be done assuming + that the contents are UTF-8 text, which can trigger decoding + errors. We now treat the contents as a bytestring for robustness + and correctness. + + * The conditions to choose different definitions of the FLEX_ARRAY + macro for vendor compilers has been simplified to make it easier to + maintain. + + * Correctness and performance update to "diff --color-moved" feature. + + * "git upload-pack" (the other side of "git fetch") used a 8kB buffer + but most of its payload came on 64kB "packets". The buffer size + has been enlarged so that such a packet fits. + + * "git fetch" and "git pull" are now declared sparse-index clean. + Also "git ls-files" learns the "--sparse" option to help debugging. + + * Similar message templates have been consolidated so that + translators need to work on fewer number of messages. + + +Fixes since v2.34 +----------------- + + * "git grep" looking in a blob that has non-UTF8 payload was + completely broken when linked with certain versions of PCREv2 + library in the latest release. + + * Other code cleanup, docfix, build fix, etc. + + * "git pull" with any strategy when the other side is behind us + should succeed as it is a no-op, but doesn't. + + * An earlier change in 2.34.0 caused JGit application (that abused + GIT_EDITOR mechanism when invoking "git config") to get stuck with + a SIGTTOU signal; it has been reverted. + + * An earlier change that broke .gitignore matching has been reverted. + + * Things like "git -c branch.sort=bogus branch new HEAD", i.e. the + operation modes of the "git branch" command that do not need the + sort key information, no longer errors out by seeing a bogus sort + key. + (merge 98e7ab6d42 jc/fix-ref-sorting-parse later to maint). + + * The compatibility implementation for unsetenv(3) were written to + mimic ancient, non-POSIX, variant seen in an old glibc; it has been + changed to return an integer to match the more modern era. + (merge a38989bd5b jc/unsetenv-returns-an-int later to maint). + + * The clean/smudge conversion code path has been prepared to better + work on platforms where ulong is narrower than size_t. + (merge 596b5e77c9 mc/clean-smudge-with-llp64 later to maint). + + * Redact the path part of packfile URI that appears in the trace output. + (merge 0ba558ffb1 if/redact-packfile-uri later to maint). + + * CI has been taught to catch some Unicode directional formatting + sequence that can be used in certain mischief. + (merge 0e7696c64d js/ci-no-directional-formatting later to maint). + + * The "--date=format:<strftime>" gained a workaround for the lack of + system support for a non-local timezone to handle "%s" placeholder. + (merge 9b591b9403 jk/strbuf-addftime-seconds-since-epoch later to maint). + + * The "merge" subcommand of "git jump" (in contrib/) silently ignored + pathspec and other parameters. + (merge 67ba13e5a4 jk/jump-merge-with-pathspec later to maint). + + * The code to decode the length of packed object size has been + corrected. + (merge 34de5b8eac jt/pack-header-lshift-overflow later to maint). + + * The advice message given by "git pull" when the user hasn't made a + choice between merge and rebase still said that the merge is the + default, which no longer is the case. This has been corrected. + (merge 71076d0edd ah/advice-pull-has-no-preference-between-rebase-and-merge later to maint). + + * "git fetch", when received a bad packfile, can fail with SIGPIPE. + This wasn't wrong per-se, but we now detect the situation and fail + in a more predictable way. + (merge 2a4aed42ec jk/fetch-pack-avoid-sigpipe-to-index-pack later to maint). + + * The function to cull a child process and determine the exit status + had two separate code paths for normal callers and callers in a + signal handler, and the latter did not yield correct value when the + child has caught a signal. The handling of the exit status has + been unified for these two code paths. An existing test with + flakiness has also been corrected. + (merge 5263e22cba jk/t7006-sigpipe-tests-fix later to maint). + + * When a non-existent program is given as the pager, we tried to + reuse an uninitialized child_process structure and crashed, which + has been fixed. + (merge f917f57f40 em/missing-pager later to maint). + + * The single-key-input mode in "git add -p" had some code to handle + keys that generate a sequence of input via ReadKey(), which did not + handle end-of-file correctly, which has been fixed. + (merge fc8a8126df cb/add-p-single-key-fix later to maint). + + * "git rebase -x" added an unnecessary 'exec' instructions before + 'noop', which has been corrected. + (merge cc9dcdee61 en/rebase-x-fix later to maint). + + * When the "git push" command is killed while the receiving end is + trying to report what happened to the ref update proposals, the + latter used to die, due to SIGPIPE. The code now ignores SIGPIPE + to increase our chances to run the post-receive hook after it + happens. + (merge d34182b9e3 rj/receive-pack-avoid-sigpipe-during-status-reporting later to maint). + + * "git worktree add" showed "Preparing worktree" message to the + standard output stream, but when it failed, the message from die() + went to the standard error stream. Depending on the order the + stdio streams are flushed at the program end, this resulted in + confusing output. It has been corrected by sending all the chatty + messages to the standard error stream. + (merge b50252484f es/worktree-chatty-to-stderr later to maint). + + * Coding guideline document has been updated to clarify what goes to + standard error in our system. + (merge e258eb4800 es/doc-stdout-vs-stderr later to maint). + + * The sparse-index/sparse-checkout feature had a bug in its use of + the matching code to determine which path is in or outside the + sparse checkout patterns. + (merge 8c5de0d265 ds/sparse-deep-pattern-checkout-fix later to maint). + + * "git rebase -x" by mistake started exporting the GIT_DIR and + GIT_WORK_TREE environment variables when the command was rewritten + in C, which has been corrected. + (merge 434e0636db en/rebase-x-wo-git-dir-env later to maint). + + * When "git log" implicitly enabled the "decoration" processing + without being explicitly asked with "--decorate" option, it failed + to read and honor the settings given by the "--decorate-refs" + option. + + * "git fetch --set-upstream" did not check if there is a current + branch, leading to a segfault when it is run on a detached HEAD, + which has been corrected. + (merge 17baeaf82d ab/fetch-set-upstream-while-detached later to maint). + + * Among some code paths that ask an yes/no question, only one place + gave a prompt that looked different from the others, which has been + updated to match what the others create. + (merge 0fc8ed154c km/help-prompt-fix later to maint). + + * "git log --invert-grep --author=<name>" used to exclude commits + written by the given author, but now "--invert-grep" only affects + the matches made by the "--grep=<pattern>" option. + (merge 794c000267 rs/log-invert-grep-with-headers later to maint). + + * "git grep --perl-regexp" failed to match UTF-8 characters with + wildcard when the pattern consists only of ASCII letters, which has + been corrected. + (merge 32e3e8bc55 rs/pcre2-utf later to maint). + + * Certain sparse-checkout patterns that are valid in non-cone mode + led to segfault in cone mode, which has been corrected. + + * Use of certain "git rev-list" options with "git fast-export" + created nonsense results (the worst two of which being "--reverse" + and "--invert-grep --grep=<foo>"). The use of "--first-parent" is + made to behave a bit more sensible than before. + (merge 726a228dfb ws/fast-export-with-revision-options later to maint). + + * Perf tests were run with end-user's shell, but it has been + corrected to use the shell specified by $TEST_SHELL_PATH. + (merge 9ccab75608 ja/perf-use-specified-shell later to maint). + + * Fix dependency rules to generate hook-list.h header file. + (merge d3fd1a6667 ab/makefile-hook-list-dependency-fix later to maint). + + * "git stash" by default triggers its "push" action, but its + implementation also made "git stash -h" to show short help only for + "git stash push", which has been corrected. + (merge ca7990cea5 ab/do-not-limit-stash-help-to-push later to maint). + + * "git apply --3way" bypasses the attempt to do a three-way + application in more cases to address the regression caused by the + recent change to use direct application as a fallback. + (merge 34d607032c jz/apply-3-corner-cases later to maint). + + * Fix performance-releated bug in "git subtree" (in contrib/). + (merge 3ce8888fb4 jl/subtree-check-parents-argument-passing-fix later to maint). + + * Extend the guidance to choose the base commit to build your work + on, and hint/nudge contributors to read others' changes. + (merge fdfae830f8 jc/doc-submitting-patches-choice-of-base later to maint). + + * A corner case bug in the ort merge strategy has been corrected. + (merge d30126c20d en/merge-ort-renorm-with-rename-delete-conflict-fix later to maint). + + * "git stash apply" forgot to attempt restoring untracked files when + it failed to restore changes to tracked ones. + (merge 71cade5a0b en/stash-df-fix later to maint). + + * Calling dynamically loaded functions on Windows has been corrected. + (merge 4a9b204920 ma/windows-dynload-fix later to maint). + + * Some lockfile code called free() in signal-death code path, which + has been corrected. + (merge 58d4d7f1c5 ps/lockfile-cleanup-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 74db416c9c cw/protocol-v2-doc-fix later to maint). + (merge f9b2b6684d ja/doc-cleanup later to maint). + (merge 7d1b866778 jc/fix-first-object-walk later to maint). + (merge 538ac74604 js/trace2-avoid-recursive-errors later to maint). + (merge 152923b132 jk/t5319-midx-corruption-test-deflake later to maint). + (merge 9081a421a6 ab/checkout-branch-info-leakfix later to maint). + (merge 42c456ff81 rs/mergesort later to maint). + (merge ad506e6780 tl/midx-docfix later to maint). + (merge bf5b83fd8a hk/ci-checkwhitespace-commentfix later to maint). + (merge 49f1eb3b34 jk/refs-g11-workaround later to maint). + (merge 7d3fc7df70 jt/midx-doc-fix later to maint). + (merge 7b089120d9 hn/create-reflog-simplify later to maint). + (merge 9e12400da8 cb/mingw-gmtime-r later to maint). + (merge 0bf0de6cc7 tb/pack-revindex-on-disk-cleanup later to maint). + (merge 2c68f577fc ew/cbtree-remove-unused-and-broken-cb-unlink later to maint). + (merge eafd6e7e55 ab/die-with-bug later to maint). + (merge 91028f7659 jc/grep-patterntype-default-doc later to maint). + (merge 47ca93d071 ds/repack-fixlets later to maint). + (merge e6a9bc0c60 rs/t4202-invert-grep-test-fix later to maint). + (merge deb5407a42 gh/gpg-doc-markup-fix later to maint). + (merge 999bba3e0b rs/daemon-plug-leak later to maint). + (merge 786eb1ba39 js/l10n-mention-ngettext-early-in-readme later to maint). + (merge 2f12b31b74 ab/makefile-msgfmt-wo-stats later to maint). + (merge 0517f591ca fs/gpg-unknown-key-test-fix later to maint). + (merge 97d6fb5a1f ma/header-dup-cleanup later to maint). diff --git a/Documentation/RelNotes/2.35.1.txt b/Documentation/RelNotes/2.35.1.txt new file mode 100644 index 0000000..726ba25 --- /dev/null +++ b/Documentation/RelNotes/2.35.1.txt @@ -0,0 +1,6 @@ +Git v2.35.1 Release Notes +========================= + +Git 2.35 shipped with a regression that broke use of "rebase" and +"stash" in a secondary worktree. This maintenance release ought to +fix it. diff --git a/Documentation/RelNotes/2.35.2.txt b/Documentation/RelNotes/2.35.2.txt new file mode 100644 index 0000000..290bfa9 --- /dev/null +++ b/Documentation/RelNotes/2.35.2.txt @@ -0,0 +1,7 @@ +Git v2.35.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.30.3, +v2.31.2, v2.32.1, v2.33.2 and v2.34.2 to address the security +issue CVE-2022-24765; see the release notes for these versions +for details. diff --git a/Documentation/RelNotes/2.35.3.txt b/Documentation/RelNotes/2.35.3.txt new file mode 100644 index 0000000..5458ba3 --- /dev/null +++ b/Documentation/RelNotes/2.35.3.txt @@ -0,0 +1,4 @@ +Git Documentation/RelNotes/2.35.3.txt Release Notes +========================= + +This release merges up the fixes that appear in v2.35.3. 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.0.txt b/Documentation/RelNotes/2.36.0.txt new file mode 100644 index 0000000..e477fba --- /dev/null +++ b/Documentation/RelNotes/2.36.0.txt @@ -0,0 +1,429 @@ +Git 2.36 Release Notes +====================== + +Updates since Git 2.35 +---------------------- + +Backward compatibility warts + + * "git name-rev --stdin" has been deprecated and issues a warning + when used; use "git name-rev --annotate-stdin" instead. + + * "git clone --filter=... --recurse-submodules" only makes the + top-level a partial clone, while submodules are fully cloned. This + behaviour is changed to pass the same filter down to the submodules. + + * With the fixes for CVE-2022-24765 that are common with versions of + Git 2.30.4, 2.31.3, 2.32.2, 2.33.3, 2.34.3, and 2.35.3, Git has + been taught not to recognise repositories owned by other users, in + order to avoid getting affected by their config files and hooks. + You can list the path to the safe/trusted repositories that may be + owned by others on a multi-valued configuration variable + `safe.directory` to override this behaviour, or use '*' to declare + that you trust anything. + + +Note to those who build from the source + + * Since Git 2.31, our source assumed that the compiler you use to + build Git supports variadic macros, with an easy-to-use escape + hatch to allow compilation without variadic macros with an request + to report that you had to use the escape hatch to the list. + Because we haven't heard from anybody who actually needed to use + the escape hatch, it has been removed, making support of variadic + macros a hard requirement. + + +UI, Workflows & Features + + * Assorted updates to "git cat-file", especially "-h". + + * The command line completion (in contrib/) learns to complete + arguments to give to "git sparse-checkout" command. + + * "git log --remerge-diff" shows the difference from mechanical merge + result and the result that is actually recorded in a merge commit. + + * "git log" and friends learned an option --exclude-first-parent-only + to propagate UNINTERESTING bit down only along the first-parent + chain, just like --first-parent option shows commits that lack the + UNINTERESTING bit only along the first-parent chain. + + * The command line completion script (in contrib/) learned to + complete all Git subcommands, including the ones that are normally + hidden, when GIT_COMPLETION_SHOW_ALL_COMMANDS is used. + + * "git branch" learned the "--recurse-submodules" option. + + * A user can forget to make a script file executable before giving + it to "git bisect run". In such a case, all tests will exit with + 126 or 127 error codes, even on revisions that are marked as good. + Try to recognize this situation and stop iteration early. + + * When "index-pack" dies due to incoming data exceeding the maximum + allowed input size, include the value of the limit in the error + message. + + * The error message given by "git switch HEAD~4" has been clarified + to suggest the "--detach" option that is required. + + * In sparse-checkouts, files mis-marked as missing from the working tree + could lead to later problems. Such files were hard to discover, and + harder to correct. Automatically detecting and correcting the marking + of such files has been added to avoid these problems. + + * "git cat-file" learns "--batch-command" mode, which is a more + flexible interface than the existing "--batch" or "--batch-check" + modes, to allow different kinds of inquiries made. + + * The level of verbose output from the ort backend during inner merge + has been aligned to that of the recursive backend. + + * "git remote rename A B", depending on the number of remote-tracking + refs involved, takes long time renaming them. The command has been + taught to show progress bar while making the user wait. + + * Bundle file format gets extended to allow a partial bundle, + filtered by similar criteria you would give when making a + partial/lazy clone. + + * A new built-in userdiff driver for kotlin has been added. + + * "git repack" learned a new configuration to disable triggering of + age-old "update-server-info" command, which is rarely useful these + days. + + * "git stash" does not allow subcommands it internally runs as its + implementation detail, except for "git reset", to emit messages; + now "git reset" part has also been squelched. + + * "git ls-tree" learns "--oid-only" option, similar to "--name-only", + and more generalized "--format" option. + + * "git fetch --refetch" learned to fetch everything without telling + the other side what we already have, which is useful when you + cannot trust what you have in the local object store. + + * "git branch" gives hint when branch tracking cannot be established + because fetch refspecs from multiple remote repositories overlap. + + * "git worktree list --porcelain" did not c-quote pathnames and lock + reasons with unsafe bytes correctly, which is worked around by + introducing NUL terminated output format with "-z". + + +Performance, Internal Implementation, Development Support etc. + + * "git apply" (ab)used the util pointer of the string-list to keep + track of how each symbolic link needs to be handled, which has been + simplified by using strset. + + * Fix a hand-rolled alloca() imitation that may have violated + alignment requirement of data being sorted in compatibility + implementation of qsort_s() and stable qsort(). + + * Use the parse-options API in "git reflog" command. + + * The conditional inclusion mechanism of configuration files using + "[includeIf <condition>]" learns to base its decision on the + URL of the remote repository the repository interacts with. + (merge 399b198489 jt/conditional-config-on-remote-url later to maint). + + * "git name-rev --stdin" does not behave like usual "--stdin" at + all. Start the process of renaming it to "--annotate-stdin". + (merge a2585719b3 jc/name-rev-stdin later to maint). + + * "git update-index", "git checkout-index", and "git clean" are + taught to work better with the sparse checkout feature. + + * Use an internal call to reset_head() helper function instead of + spawning "git checkout" in "rebase", and update code paths that are + involved in the change. + + * Messages "ort" merge backend prepares while dealing with conflicted + paths were unnecessarily confusing since it did not differentiate + inner merges and outer merges. + + * Small modernization of the rerere-train script (in contrib/). + + * Use designated initializers we started using in mid 2017 in more + parts of the codebase that are relatively quiescent. + + * Improve failure case behaviour of xdiff library when memory + allocation fails. + + * General clean-up in reftable implementation, including + clarification of the API documentation, tightening the code to + honor documented length limit, etc. + + * Remove the escape hatch we added when we introduced the weather + balloon to use variadic macros unconditionally, to make it official + that we now have a hard dependency on the feature. + + * Makefile refactoring with a bit of suffixes rule stripping to + optimize the runtime overhead. + + * "git stash drop" is reimplemented as an internal call to + reflog_delete() function, instead of invoking "git reflog delete" + via run_command() API. + + * Count string_list items in size_t, not "unsigned int". + + * The single-key interactive operation used by "git add -p" has been + made more robust. + + * Remove unneeded <meta http-equiv=content-type...> from gitweb + output. + + * "git name-rev" learned to use the generation numbers when setting + the lower bound of searching commits used to explain the revision, + when available, instead of committer time. + + * Replace core.fsyncObjectFiles with two new configuration variables, + core.fsync and core.fsyncMethod. + + * Updates to refs traditionally weren't fsync'ed, but we can + configure using core.fsync variable to do so. + + * "git reflog" command now uses parse-options API to parse its + command line options. + + +Fixes since v2.35 +----------------- + + * "rebase" and "stash" in secondary worktrees are broken in + Git 2.35.0, which has been corrected. + + * "git pull --rebase" ignored the rebase.autostash configuration + variable when the remote history is a descendant of our history, + which has been corrected. + (merge 3013d98d7a pb/pull-rebase-autostash-fix later to maint). + + * "git update-index --refresh" has been taught to deal better with + racy timestamps (just like "git status" already does). + (merge 2ede073fd2 ms/update-index-racy later to maint). + + * Avoid tests that are run under GIT_TRACE2 set from failing + unnecessarily. + (merge 944d808e42 js/test-unset-trace2-parents later to maint). + + * The merge-ort misbehaved when merge.renameLimit configuration is + set too low and failed to find all renames. + (merge 9ae39fef7f en/merge-ort-restart-optim-fix later to maint). + + * We explain that revs come first before the pathspec among command + line arguments, but did not spell out that dashed options come + before other args, which has been corrected. + (merge c11f95010c tl/doc-cli-options-first later to maint). + + * "git add -p" rewritten in C regressed hunk splitting in some cases, + which has been corrected. + (merge 7008ddc645 pw/add-p-hunk-split-fix later to maint). + + * "git fetch --negotiate-only" is an internal command used by "git + push" to figure out which part of our history is missing from the + other side. It should never recurse into submodules even when + fetch.recursesubmodules configuration variable is set, nor it + should trigger "gc". The code has been tightened up to ensure it + only does common ancestry discovery and nothing else. + (merge de4eaae63a gc/fetch-negotiate-only-early-return later to maint). + + * The code path that verifies signatures made with ssh were made to + work better on a system with CRLF line endings. + (merge caeef01ea7 fs/ssh-signing-crlf later to maint). + + * "git sparse-checkout init" failed to write into $GIT_DIR/info + directory when the repository was created without one, which has + been corrected to auto-create it. + (merge 7f44842ac1 jt/sparse-checkout-leading-dir-fix later to maint). + + * Cloning from a repository that does not yet have any branches or + tags but has other refs resulted in a "remote transport reported + error", which has been corrected. + (merge dccea605b6 jt/clone-not-quite-empty later to maint). + + * Mark in various places in the code that the sparse index and the + split index features are mutually incompatible. + (merge 451b66c533 js/sparse-vs-split-index later to maint). + + * Update the logic to compute alignment requirement for our mem-pool. + (merge e38bcc66d8 jc/mem-pool-alignment later to maint). + + * Pick a better random number generator and use it when we prepare + temporary filenames. + (merge 47efda967c bc/csprng-mktemps later to maint). + + * Update the contributor-facing documents on proposed log messages. + (merge cdba0295b0 jc/doc-log-messages later to maint). + + * When "git fetch --prune" failed to prune the refs it wanted to + prune, the command issued error messages but exited with exit + status 0, which has been corrected. + (merge c9e04d905e tg/fetch-prune-exit-code-fix later to maint). + + * Problems identified by Coverity in the reftable code have been + corrected. + (merge 01033de49f hn/reftable-coverity-fixes later to maint). + + * A bug that made multi-pack bitmap and the object order out-of-sync, + making the .midx data corrupt, has been fixed. + (merge f8b60cf99b tb/midx-bitmap-corruption-fix later to maint). + + * The build procedure has been taught to notice older version of zlib + and enable our replacement uncompress2() automatically. + (merge 07564773c2 ab/auto-detect-zlib-compress2 later to maint). + + * Interaction between fetch.negotiationAlgorithm and + feature.experimental configuration variables has been corrected. + (merge 714edc620c en/fetch-negotiation-default-fix later to maint). + + * "git diff --diff-filter=aR" is now parsed correctly. + (merge 75408ca949 js/diff-filter-negation-fix later to maint). + + * When "git subtree" wants to create a merge, it used "git merge" and + let it be affected by end-user's "merge.ff" configuration, which + has been corrected. + (merge 9158a3564a tk/subtree-merge-not-ff-only later to maint). + + * Unlike "git apply", "git patch-id" did not handle patches with + hunks that has only 1 line in either preimage or postimage, which + has been corrected. + (merge 757e75c81e jz/patch-id-hunk-header-parsing-fix later to maint). + + * "receive-pack" checks if it will do any ref updates (various + conditions could reject a push) before received objects are taken + out of the temporary directory used for quarantine purposes, so + that a push that is known-to-fail will not leave crufts that a + future "gc" needs to clean up. + (merge 5407764069 cb/clear-quarantine-early-on-all-ref-update-errors later to maint). + + * When there is no object to write .bitmap file for, "git + multi-pack-index" triggered an error, instead of just skipping, + which has been corrected. + (merge eb57277ba3 tb/midx-no-bitmap-for-no-objects later to maint). + + * "git cmd -h" outside a repository should error out cleanly for many + commands, but instead it hit a BUG(), which has been corrected. + (merge 87ad07d735 js/short-help-outside-repo-fix later to maint). + + * "working tree" and "per-worktree ref" were in glossary, but + "worktree" itself wasn't, which has been corrected. + (merge 2df5387ed0 jc/glossary-worktree later to maint). + + * L10n support for a few error messages. + (merge 3d3c23b3a7 bs/forbid-i18n-of-protocol-token-in-fetch-pack later to maint). + + * Test modernization. + (merge d4fe066e4b sy/t0001-use-path-is-helper later to maint). + + * "git log --graph --graph" used to leak a graph structure, and there + was no way to countermand "--graph" that appear earlier on the + command line. A "--no-graph" option has been added and resource + leakage has been plugged. + + * Error output given in response to an ambiguous object name has been + improved. + (merge 3a73c1dfaf ab/ambiguous-object-name later to maint). + + * "git sparse-checkout" wants to work with per-worktree configuration, + but did not work well in a worktree attached to a bare repository. + (merge 3ce1138272 ds/sparse-checkout-requires-per-worktree-config later to maint). + + * Setting core.untrackedCache to true failed to add the untracked + cache extension to the index. + + * Workaround we have for versions of PCRE2 before their version 10.36 + were in effect only for their versions newer than 10.36 by mistake, + which has been corrected. + (merge 97169fc361 rs/pcre-invalid-utf8-fix-fix later to maint). + + * Document Taylor as a new member of Git PLC at SFC. Welcome. + (merge e8d56ca863 tb/coc-plc-update later to maint). + + * "git checkout -b branch/with/multi/level/name && git stash" only + recorded the last level component of the branch name, which has + been corrected. + + * Check the return value from parse_tree_indirect() to turn segfaults + into calls to die(). + (merge 8d2eaf649a gc/parse-tree-indirect-errors later to maint). + + * Newer version of GPGSM changed its output in a backward + incompatible way to break our code that parses its output. It also + added more processes our tests need to kill when cleaning up. + Adjustments have been made to accommodate these changes. + (merge b0b70d54c4 fs/gpgsm-update later to maint). + + * The untracked cache newly computed weren't written back to the + on-disk index file when there is no other change to the index, + which has been corrected. + + * "git config -h" did not describe the "--type" option correctly. + (merge 5445124fad mf/fix-type-in-config-h later to maint). + + * The way generation number v2 in the commit-graph files are + (not) handled has been corrected. + (merge 6dbf4b8172 ds/commit-graph-gen-v2-fixes later to maint). + + * The method to trigger malloc check used in our tests no longer work + with newer versions of glibc. + (merge baedc59543 ep/test-malloc-check-with-glibc-2.34 later to maint). + + * When "git fetch --recurse-submodules" grabbed submodule commits + that would be needed to recursively check out newly fetched commits + in the superproject, it only paid attention to submodules that are + in the current checkout of the superproject. We now do so for all + submodules that have been run "git submodule init" on. + + * "git rebase $base $non_branch_commit", when $base is an ancestor or + the $non_branch_commit, modified the current branch, which has been + corrected. + + * When "shallow" information is updated, we forgot to update the + in-core equivalent, which has been corrected. + + * When creating a loose object file, we didn't report the exact + filename of the file we failed to fsync, even though the + information was readily available, which has been corrected. + + * "git am" can read from the standard input when no mailbox is given + on the command line, but the end-user gets no indication when it + happens, making Git appear stuck. + (merge 7b20af6a06 jc/mailsplit-warn-on-tty later to maint). + + * "git mv" failed to refresh the cached stat information for the + entry it moved. + (merge b7f9130a06 vd/mv-refresh-stat later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge cfc5cf428b jc/find-header later to maint). + (merge 40e7cfdd46 jh/p4-fix-use-of-process-error-exception later to maint). + (merge 727e6ea350 jh/p4-spawning-external-commands-cleanup later to maint). + (merge 0a6adc26e2 rs/grep-expr-cleanup later to maint). + (merge 4ed7dfa713 po/readme-mention-contributor-hints later to maint). + (merge 6046f7a91c en/plug-leaks-in-merge later to maint). + (merge 8c591dbfce bc/clarify-eol-attr later to maint). + (merge 518e15db74 rs/parse-options-lithelp-help later to maint). + (merge cbac0076ef gh/doc-typos later to maint). + (merge ce14de03db ab/no-errno-from-resolve-ref-unsafe later to maint). + (merge 2826ffad8c rc/negotiate-only-typofix later to maint). + (merge 0f03f04c5c en/sparse-checkout-leakfix later to maint). + (merge 74f3390dde sy/diff-usage-typofix later to maint). + (merge 45d0212a71 ll/doc-mktree-typofix later to maint). + (merge e9b272e4c1 js/no-more-legacy-stash later to maint). + (merge 6798b08e84 ab/do-not-hide-failures-in-git-dot-pm later to maint). + (merge 9325285df4 po/doc-check-ignore-markup-fix later to maint). + (merge cd26cd6c7c sy/modernize-t-lib-read-tree-m-3way later to maint). + (merge d17294a05e ab/hash-object-leakfix later to maint). + (merge b8403129d3 jd/t0015-modernize later to maint). + (merge 332acc248d ds/mailmap later to maint). + (merge 04bf052eef ab/grep-patterntype later to maint). + (merge 6ee36364eb ab/diff-free-more later to maint). + (merge 63a36017fe nj/read-tree-doc-reffix later to maint). + (merge eed36fce38 sm/no-git-in-upstream-of-pipe-in-tests later to maint). + (merge c614beb933 ep/t6423-modernize later to maint). + (merge 57be9c6dee ab/reflog-prep-fix later to maint). + (merge 5327d8982a js/in-place-reverse-in-sequencer later to maint). + (merge 2e2c0be51e dp/worktree-repair-in-usage later to maint). + (merge 6563706568 jc/coding-guidelines-decl-in-for-loop later to maint). diff --git a/Documentation/RelNotes/2.36.1.txt b/Documentation/RelNotes/2.36.1.txt new file mode 100644 index 0000000..a961709 --- /dev/null +++ b/Documentation/RelNotes/2.36.1.txt @@ -0,0 +1,33 @@ +Git v2.36.1 Release Notes +========================= + +Fixes since v2.36 +----------------- + + * "git submodule update" without pathspec should silently skip an + uninitialized submodule, but it started to become noisy by mistake. + + * "diff-tree --stdin" has been broken for about a year, but 2.36 + release broke it even worse by breaking running the command with + <pathspec>, which in turn broke "gitk" and got noticed. This has + been corrected by aligning its behaviour to that of "log". + + * Regression fix for 2.36 where "git name-rev" started to sometimes + reference strings after they are freed. + + * "git show <commit1> <commit2>... -- <pathspec>" lost the pathspec + when showing the second and subsequent commits, which has been + corrected. + + * "git fast-export -- <pathspec>" lost the pathspec when showing the + second and subsequent commits, which has been corrected. + + * "git format-patch <args> -- <pathspec>" lost the pathspec when + showing the second and subsequent commits, which has been + corrected. + + * Get rid of a bogus and over-eager coccinelle rule. + + * Correct choices of C compilers used in various CI jobs. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.36.2.txt b/Documentation/RelNotes/2.36.2.txt new file mode 100644 index 0000000..958f5b4 --- /dev/null +++ b/Documentation/RelNotes/2.36.2.txt @@ -0,0 +1,56 @@ +Git v2.36.2 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 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 +------------------- + + * Fixes real problems noticed by gcc 12 and works around false + positives. + + * Update URL to the gitk repository. + + * The "--current" option of "git show-branch" should have been made + incompatible with the "--reflog" mode, but this was not enforced, + which has been corrected. + + * "git archive --add-file=<path>" picked up the raw permission bits + from the path and propagated to zip output in some cases, without + normalization, which has been corrected (tar output did not have + this issue). + + * A bit of test framework fixes with a few fixes to issues found by + valgrind. + + * macOS CI jobs have been occasionally flaky due to tentative version + skew between perforce and the homebrew packager. Instead of + failing the whole CI job, just let it skip the p4 tests when this + happens. + + * The commit summary shown after making a commit is matched to what + is given in "git status" not to use the break-rewrite heuristics. + + * Avoid problems from interaction between malloc_check and address + sanitizer. + + * "git rebase --keep-base <upstream> <branch-to-rebase>" computed the + commit to rebase onto incorrectly, which has been corrected. + + * The path taken by "git multi-pack-index" command from the end user + was compared with path internally prepared by the tool withut first + normalizing, which lead to duplicated paths not being noticed, + which has been corrected. + + * "git clone --origin X" leaked piece of memory that held value read + from the clone.defaultRemoteName configuration variable, which has + been plugged. 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.0.txt b/Documentation/RelNotes/2.37.0.txt new file mode 100644 index 0000000..99dc7e3 --- /dev/null +++ b/Documentation/RelNotes/2.37.0.txt @@ -0,0 +1,337 @@ +Git v2.37 Release Notes +======================= + +UI, Workflows & Features + + * "vimdiff[123]" mergetool drivers have been reimplemented with a + more generic layout mechanism. + + * "git -v" and "git -h" are now understood as "git --version" and + "git --help". + + * The temporary files fed to external diff command are now generated + inside a new temporary directory under the same basename. + + * "git log --since=X" will stop traversal upon seeing a commit that + is older than X, but there may be commits behind it that is younger + than X when the commit was created with a faulty clock. A new + option is added to keep digging without stopping, and instead + filter out commits with timestamp older than X. + + * "git -c branch.autosetupmerge=simple branch $A $B" will set the $B + as $A's upstream only when $A and $B shares the same name, and "git + -c push.default=simple" on branch $A would push to update the + branch $A at the remote $B came from. Also more places use the + sole remote, if exists, before defaulting to 'origin'. + + * A new doc has been added that lists tips for tools to work with + Git's codebase. + + * "git remote -v" now shows the list-objects-filter used during + fetching from the remote, if available. + + * With the new http.curloptResolve configuration, the CURLOPT_RESOLVE + mechanism that allows cURL based applications to use pre-resolved + IP addresses for the requests is exposed to the scripts. + + * "git add -i" was rewritten in C some time ago and has been in + testing; the reimplementation is now exposed to general public by + default. + + * Deprecate non-cone mode of the sparse-checkout feature. + + * Introduce a filesystem-dependent mechanism to optimize the way the + bits for many loose object files are ensured to hit the disk + platter. + + * The "do not remove the directory the user started Git in" logic, + when Git cannot tell where that directory is, is disabled. Earlier + we refused to run in such a case. + + * A mechanism to pack unreachable objects into a "cruft pack", + instead of ejecting them into loose form to be reclaimed later, has + been introduced. + + * Update the doctype written in gitweb output to xhtml5. + + * The "transfer.credentialsInURL" configuration variable controls what + happens when a URL with embedded login credential is used on either + "fetch" or "push". Credentials are currently only detected in + `remote.<name>.url` config, not `remote.<name>.pushurl`. + + * "git revert" learns "--reference" option to use more human-readable + reference to the commit it reverts in the message template it + prepares for the user. + + * Various error messages that talk about the removal of + "--preserve-merges" in "rebase" have been strengthened, and "rebase + --abort" learned to get out of a state that was left by an earlier + use of the option. + + +Performance, Internal Implementation, Development Support etc. + + * The performance of the "untracked cache" feature has been improved + when "--untracked-files=<mode>" and "status.showUntrackedFiles" + are combined. + + * "git stash" works better with sparse index entries. + + * "git show :<path>" learned to work better with the sparse-index + feature. + + * Introduce and apply coccinelle rule to discourage an explicit + comparison between a pointer and NULL, and applies the clean-up to + the maintenance track. + + * Preliminary code refactoring around transport and bundle code. + + * "sparse-checkout" learns to work better with the sparse-index + feature. + + * A workflow change for translators are being proposed. git.pot is + no longer version controlled and it is local responsibility of + translators to generate it. + + * Plug the memory leaks from the trickiest API of all, the revision + walker. + + * Rename .env_array member to .env in the child_process structure. + + * The fsmonitor--daemon handles even more corner cases when + watching filesystem events. + + * A new bug() and BUG_if_bug() API is introduced to make it easier to + uniformly log "detect multiple bugs and abort in the end" pattern. + + +Fixes since v2.36 +----------------- + + * "git submodule update" without pathspec should silently skip an + uninitialized submodule, but it started to become noisy by mistake. + (merge 4f1ccef87c gc/submodule-update-part2 later to maint). + + * "diff-tree --stdin" has been broken for about a year, but 2.36 + release broke it even worse by breaking running the command with + <pathspec>, which in turn broke "gitk" and got noticed. This has + been corrected by aligning its behaviour to that of "log". + (merge f8781bfda3 jc/diff-tree-stdin-fix later to maint). + + * Regression fix for 2.36 where "git name-rev" started to sometimes + reference strings after they are freed. + (merge 45a14f578e rs/name-rev-fix-free-after-use later to maint). + + * "git show <commit1> <commit2>... -- <pathspec>" lost the pathspec + when showing the second and subsequent commits, which has been + corrected. + (merge 5cdb38458e jc/show-pathspec-fix later to maint). + + * "git fast-export -- <pathspec>" lost the pathspec when showing the + second and subsequent commits, which has been corrected. + (merge d1c25272f5 rs/fast-export-pathspec-fix later to maint). + + * "git format-patch <args> -- <pathspec>" lost the pathspec when + showing the second and subsequent commits, which has been + corrected. + (merge 91f8f7e46f rs/format-patch-pathspec-fix later to maint). + + * "git clone --origin X" leaked piece of memory that held value read + from the clone.defaultRemoteName configuration variable, which has + been plugged. + (merge 6dfadc8981 jc/clone-remote-name-leak-fix later to maint). + + * Get rid of a bogus and over-eager coccinelle rule. + (merge 08bdd3a185 jc/cocci-xstrdup-or-null-fix later to maint). + + * The path taken by "git multi-pack-index" command from the end user + was compared with path internally prepared by the tool without first + normalizing, which lead to duplicated paths not being noticed, + which has been corrected. + (merge 11f9e8de3d ds/midx-normalize-pathname-before-comparison later to maint). + + * Correct choices of C compilers used in various CI jobs. + (merge 3506cae04f ab/cc-package-fixes later to maint). + + * Various cleanups to "git p4". + (merge 4ff0108d9e jh/p4-various-fixups later to maint). + + * The progress meter of "git blame" was showing incorrect numbers + when processing only parts of the file. + (merge e5f5d7d42e ea/progress-partial-blame later to maint). + + * "git rebase --keep-base <upstream> <branch-to-rebase>" computed the + commit to rebase onto incorrectly, which has been corrected. + (merge 9e5ebe9668 ah/rebase-keep-base-fix later to maint). + + * Fix a leak of FILE * in an error codepath. + (merge c0befa0c03 kt/commit-graph-plug-fp-leak-on-error later to maint). + + * Avoid problems from interaction between malloc_check and address + sanitizer. + (merge 067109a5e7 pw/test-malloc-with-sanitize-address later to maint). + + * The commit summary shown after making a commit is matched to what + is given in "git status" not to use the break-rewrite heuristics. + (merge 84792322ed rs/commit-summary-wo-break-rewrite later to maint). + + * Update a few end-user facing messages around EOL conversion. + (merge c970d30c2c ah/convert-warning-message later to maint). + + * Trace2 documentation updates. + (merge a6c80c313c js/trace2-doc-fixes later to maint). + + * Build procedure fixup. + (merge 1fbfd96f50 mg/detect-compiler-in-c-locale later to maint). + + * "git pull" without "--recurse-submodules=<arg>" made + submodule.recurse take precedence over fetch.recurseSubmodules by + mistake, which has been corrected. + (merge 5819417365 gc/pull-recurse-submodules later to maint). + + * "git bisect" was too silent before it is ready to start computing + the actual bisection, which has been corrected. + (merge f11046e6de cd/bisect-messages-from-pre-flight-states later to maint). + + * macOS CI jobs have been occasionally flaky due to tentative version + skew between perforce and the homebrew packager. Instead of + failing the whole CI job, just let it skip the p4 tests when this + happens. + (merge f15e00b463 cb/ci-make-p4-optional later to maint). + + * A bit of test framework fixes with a few fixes to issues found by + valgrind. + (merge 7c898554d7 ab/valgrind-fixes later to maint). + + * "git archive --add-file=<path>" picked up the raw permission bits + from the path and propagated to zip output in some cases, without + normalization, which has been corrected (tar output did not have + this issue). + (merge 6a61661967 jc/archive-add-file-normalize-mode later to maint). + + * "make coverage-report" without first running "make coverage" did + not produce any meaningful result, which has been corrected. + (merge 96ddfecc5b ep/coverage-report-wants-test-to-have-run later to maint). + + * The "--current" option of "git show-branch" should have been made + incompatible with the "--reflog" mode, but this was not enforced, + which has been corrected. + (merge 41c64ae0e7 jc/show-branch-g-current later to maint). + + * "git fetch" unnecessarily failed when an unexpected optional + section appeared in the output, which has been corrected. + (merge 7709acf7be jt/fetch-peek-optional-section later to maint). + + * The way "git fetch" without "--update-head-ok" ensures that HEAD in + no worktree points at any ref being updated was too wasteful, which + has been optimized a bit. + (merge f7400da800 os/fetch-check-not-current-branch later to maint). + + * "git fetch --recurse-submodules" from multiple remotes (either from + a remote group, or "--all") used to make one extra "git fetch" in + the submodules, which has been corrected. + (merge 0353c68818 jc/avoid-redundant-submodule-fetch later to maint). + + * With a recent update to refuse access to repositories of other + people by default, "sudo make install" and "sudo git describe" + stopped working, which has been corrected. + (merge 6b11e3d52e cb/path-owner-check-with-sudo-plus later to maint). + + * The tests that ensured merges stop when interfering local changes + are present did not make sure that local changes are preserved; now + they do. + (merge 4b317450ce jc/t6424-failing-merge-preserve-local-changes later to maint). + + * Some real problems noticed by gcc 12 have been fixed, while false + positives have been worked around. + + * Update the version of FreeBSD image used in Cirrus CI. + (merge c58bebd4c6 pb/use-freebsd-12.3-in-cirrus-ci later to maint). + + * The multi-pack-index code did not protect the packfile it is going + to depend on from getting removed while in use, which has been + corrected. + (merge 4090511e40 tb/midx-race-in-pack-objects later to maint). + + * Teach "git repack --geometric" work better with "--keep-pack" and + avoid corrupting the repository when packsize limit is used. + (merge 66731ff921 tb/geom-repack-with-keep-and-max later to maint). + + * The documentation on the interaction between "--add-file" and + "--prefix" options of "git archive" has been improved. + (merge a75910602a rs/document-archive-prefix later to maint). + + * A git subcommand like "git add -p" spawns a separate git process + while relaying its command line arguments. A pathspec with only + negative elements was mistakenly passed with an empty string, which + has been corrected. + (merge b02fdbc80a jc/all-negative-pathspec later to maint). + + * With a more targeted workaround in http.c in another topic, we may + be able to lift this blanket "GCC12 dangling-pointer warning is + broken and unsalvageable" workaround. + (merge 419141e495 cb/buggy-gcc-12-workaround later to maint). + + * A misconfigured 'branch..remote' led to a bug in configuration + parsing. + (merge f1dfbd9ee0 gc/zero-length-branch-config-fix later to maint). + + * "git -c diff.submodule=log range-diff" did not show anything for + submodules that changed in the ranges being compared, and + "git -c diff.submodule=diff range-diff" did not work correctly. + Fix this by including the "--submodule=short" output + unconditionally to be compared. + + * In Git 2.36 we revamped the way how hooks are invoked. One change + that is end-user visible is that the output of a hook is no longer + directly connected to the standard output of "git" that spawns the + hook, which was noticed post release. This is getting corrected. + (merge a082345372 ab/hooks-regression-fix later to maint). + + * Updating the graft information invalidates the list of parents of + in-core commit objects that used to be in the graft file. + + * "git show-ref --heads" (and "--tags") still iterated over all the + refs only to discard refs outside the specified area, which has + been corrected. + (merge c0c9d35e27 tb/show-ref-optim later to maint). + + * Remove redundant copying (with index v3 and older) or possible + over-reading beyond end of mmapped memory (with index v4) has been + corrected. + (merge 6d858341d2 zh/read-cache-copy-name-entry-fix later to maint). + + * Sample watchman interface hook sometimes failed to produce + correctly formatted JSON message, which has been corrected. + (merge 134047b500 sn/fsmonitor-missing-clock later to maint). + + * Use-after-free (with another forget-to-free) fix. + (merge 323822c72b ab/remote-free-fix later to maint). + + * Remove a coccinelle rule that is no longer relevant. + (merge b1299de4a1 jc/cocci-cleanup later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge e6b2582da3 cm/reftable-0-length-memset later to maint). + (merge 0b75e5bf22 ab/misc-cleanup later to maint). + (merge 52e1ab8a76 ea/rebase-code-simplify later to maint). + (merge 756d15923b sg/safe-directory-tests-and-docs later to maint). + (merge d097a23bfa ds/do-not-call-bug-on-bad-refs later to maint). + (merge c36c27e75c rs/t7812-pcre2-ws-bug-test later to maint). + (merge 1da312742d gf/unused-includes later to maint). + (merge 465b30a92d pb/submodule-recurse-mode-enum later to maint). + (merge 82b28c4ed8 km/t3501-use-test-helpers later to maint). + (merge 72315e431b sa/t1011-use-helpers later to maint). + (merge 95b3002201 cg/vscode-with-gdb later to maint). + (merge fbe5f6b804 tk/p4-utf8-bom later to maint). + (merge 17f273ffba tk/p4-with-explicity-sync later to maint). + (merge 944db25c60 kf/p4-multiple-remotes later to maint). + (merge b014cee8de jc/update-ozlabs-url later to maint). + (merge 4ec5008062 pb/ggg-in-mfc-doc later to maint). + (merge af845a604d tb/receive-pack-code-cleanup later to maint). + (merge 2acf4cf001 js/ci-gcc-12-fixes later to maint). + (merge 05e280c0a6 jc/http-clear-finished-pointer later to maint). + (merge 8c49d704ef fh/transport-push-leakfix later to maint). + (merge 1d232d38bd tl/ls-tree-oid-only later to maint). + (merge db7961e6a6 gc/document-config-worktree-scope later to maint). + (merge ce18a30bb7 fs/ssh-default-key-command-doc later to maint). 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..0570dcd --- /dev/null +++ b/Documentation/RelNotes/2.45.0.txt @@ -0,0 +1,434 @@ +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. + + * The userdiff patterns for C# has been updated. + + +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. + + * Document and apply workaround for a buggy version of dash that + mishandles "local var=val" construct. + + * The codepaths that reach date_mode_from_type() have been updated to + pass "struct date_mode" by value to make them thread safe. + + * The strategy to compact multiple tables of reftables after many + operations accumulate many entries has been improved to avoid + accumulating too many tables uncollected. + + +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). + + * vreportf(), which is usede by error() and friends, has been taught + to give the error message printf-format string when its vsnprintf() + call fails, instead of showing nothing useful to identify the + nature of the error. + (merge c63adab961 rs/usage-fallback-to-show-message-format later to maint). + + * Adjust to an upcoming changes to GNU make that breaks our Makefiles. + (merge 227b8fd902 tb/make-indent-conditional-with-non-spaces later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge f0e578c69c rs/use-xstrncmpz later to maint). + (merge 83e6eb7d7a ba/credential-test-clean-fix later to maint). + (merge 64562d784d jb/doc-interactive-singlekey-do-not-need-perl later to maint). + (merge c431a235e2 cp/t9146-use-test-path-helpers later to maint). + (merge 82d75402d5 ds/doc-send-email-capitalization later to maint). + (merge 41bff66e35 jc/doc-add-placeholder-fix later to maint). + (merge 6835f0efe9 jw/remote-doc-typofix later to maint). + (merge 244001aa20 hs/rebase-not-in-progress later to maint). + (merge 2ca6c07db2 jc/no-include-of-compat-util-from-headers later to maint). + (merge 87bd7fbb9c rs/fetch-simplify-with-starts-with later to maint). + (merge f39addd0d9 rs/name-rev-with-mempool later to maint). + (merge 9a97b43e03 rs/submodule-prefix-simplify later to maint). + (merge 40b8076462 ak/rebase-autosquash later to maint). + (merge 3223204456 eg/add-uflags later to maint). + (merge 5f78d52dce es/config-doc-sort-sections later to maint). + (merge 781fb7b4c2 as/option-names-in-messages later to maint). + (merge 51d41dc243 jk/doc-remote-helpers-markup-fix later to maint). + (merge e1aaf309db pb/ci-win-artifact-names-fix later to maint). + (merge ad538c61da jc/index-pack-fsck-levels later to maint). + (merge 67471bc704 ja/doc-formatting-fix later to maint). + (merge 86f9ce7dd6 bl/doc-config-fixes later to maint). + (merge 0d527842b7 az/grep-group-error-message-update later to maint). + (merge 7c43bdf07b rs/strbuf-expand-bad-format later to maint). + (merge 8b68b48d5c ds/typofix-core-config-doc later to maint). + (merge 39bb692152 rs/imap-send-use-xsnprintf later to maint). + (merge 8d320cec60 jc/t2104-style-fixes later to maint). + (merge b4454d5a7b pw/t3428-cleanup later to maint). + (merge 84a7c33a4b pf/commitish-committish later to maint). + (merge 8882ee9d68 la/mailmap-entry later to maint). 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 3e215f4..c647c7e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,43 +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 a topic that is in `seen`, but not in `master`, - base your work on the tip of that topic. - -* 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 for discussion. Before the final merge, you may have to - wait until some of the dependent topics graduate to `master`, and - rebase your work. - -* 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. @@ -71,13 +129,17 @@ Make sure that you have tests for the bug you are fixing. See [[tests]] When adding a new feature, make sure that you have new tests to show the feature triggers the new behavior when it should, and to show the -feature does not trigger when it shouldn't. After any code change, make -sure that the entire test suite passes. - -If you have an account at GitHub (and you can get one for free to work -on open source projects), you can use their Travis CI integration to -test your changes on Linux, Mac (and hopefully soon Windows). See -GitHub-Travis CI hints section for details. +feature does not trigger when it shouldn't. After any code change, +make sure that the entire test suite passes. When fixing a bug, make +sure you have new tests that break if somebody else breaks what you +fixed by accident to avoid regression. Also, try merging your work to +'next' and 'seen' and make sure the tests still pass; topics by others +that are still in flight may have unexpected interactions with what +you are trying to do in your topic. + +Pushing to a fork of https://github.com/git/git will use their CI +integration to test your changes on Linux, Mac and Windows. See the +<<GHCI,GitHub CI>> section for details. Do not forget to update the documentation to describe the updated behavior and make sure that the resulting documentation set formats @@ -104,6 +166,35 @@ run `git diff --check` on your changes before you commit. [[describe-changes]] === Describe your changes well. +The log message that explains your changes is just as important as the +changes themselves. Your code may be clearly written with in-code +comment to sufficiently explain how it works with the surrounding +code, but those who need to fix or enhance your code in the future +will need to know _why_ your code does what it does, for a few +reasons: + +. Your code may be doing something differently from what you wanted it + to do. Writing down what you actually wanted to achieve will help + them fix your code and make it do what it should have been doing + (also, you often discover your own bugs yourself, while writing the + log message to summarize the thought behind it). + +. Your code may be doing things that were only necessary for your + immediate needs (e.g. "do X to directories" without implementing or + even designing what is to be done on files). Writing down why you + excluded what the code does not do will help guide future developers. + Writing down "we do X to directories, because directories have + characteristic Y" would help them infer "oh, files also have the same + characteristic Y, so perhaps doing X to them would also make sense?". + Saying "we don't do the same X to files, because ..." will help them + decide if the reasoning is sound (in which case they do not waste + time extending your code to cover files), or reason differently (in + which case, they can explain why they extend your code to cover + files, too). + +The goal of your log message is to convey the _why_ behind your +change to help future developers. + The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), and should skip the full stop. It is also conventional in most cases to @@ -118,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 @@ -136,6 +229,13 @@ The body should provide a meaningful commit message, which: . alternate solutions considered but discarded, if any. +[[present-tense]] +The problem statement that describes the status quo is written in the +present tense. Write "The code does X when it is given input Y", +instead of "The code used to do Y when given input X". You do not +have to say "Currently"---the status quo in the problem statement is +about the code _without_ your change, by project convention. + [[imperative-mood]] Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy @@ -145,15 +245,28 @@ without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion. [[commit-reference]] -If you want to reference a previous commit in the history of a stable -branch, use the format "abbreviated hash (subject, date)", like this: + +There are a few reasons why you may want to refer to another commit in +the "more stable" part of the history (i.e. on branches like `maint`, +`master`, and `next`): + +. A commit that introduced the root cause of a bug you are fixing. + +. A commit that introduced a feature that you are enhancing. + +. A commit that conflicts with your work when you made a trial merge + of your work into `next` and `seen` for testing. + +When you reference a commit on a more stable branch (like `master`, +`maint` and `next`), use the format "abbreviated hash (subject, +date)", like this: .... Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) 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`: @@ -167,6 +280,97 @@ or, on an older version of Git without support for --pretty=reference: git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> .... +[[sign-off]] +=== Certify your work by adding your `Signed-off-by` trailer + +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. + +If (and only if) you certify the below D-C-O: + +[[dco]] +.Developer's Certificate of Origin 1.1 +____ +By making a contribution to this project, I certify that: + +a. The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +b. The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +c. The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +d. I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +____ + +you add a "Signed-off-by" trailer to your commit, that looks like +this: + +.... + Signed-off-by: Random J Developer <random@developer.example.org> +.... + +This line can be added by Git if you run the git-commit command with +the -s option. + +Notice that you can place your own `Signed-off-by` trailer when +forwarding somebody else's patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above). + +This procedure originally came from the Linux kernel project, so our +rule is quite similar to theirs, but what exactly it means to sign-off +your patch differs from project to project, so it may be different +from that of the project you are accustomed to. + +[[real-name]] +Also notice that a real name is used in the `Signed-off-by` trailer. Please +don't hide your real name. + +[[commit-trailers]] +If you like, you can put extra tags at the end: + +. `Reported-by:` is used to credit someone who found the bug that + the patch attempts to fix. +. `Acked-by:` says that the person who is more familiar with the area + the patch attempts to modify liked the patch. +. `Reviewed-by:`, unlike the other tags, can only be offered by the + reviewers themselves when they are completely satisfied with the + 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. +. `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. @@ -181,9 +385,14 @@ 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 `master` -branch head. If you are preparing a work based on "next" branch, -that is fine, but please mark it 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]] === Sending your patches. @@ -196,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 @@ -250,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 @@ -287,7 +508,10 @@ Security mailing list{security-ml-ref}. Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the `git contacts` command in `contrib/contacts/` can help to -identify them), to solicit comments and reviews. +identify them), to solicit comments and reviews. Also, when you made +trial merges of your topic to `next` and `seen`, you may have noticed +work by others conflicting with your changes. There is a good possibility +that these people may know the area you are touching well. :current-maintainer: footnote:[The current maintainer: gitster@pobox.com] :git-ml: footnote:[The mailing list: git@vger.kernel.org] @@ -302,85 +526,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and `Tested-by:` lines as necessary to credit people who helped your patch, and "cc:" them when sending such a final version for inclusion. -[[sign-off]] -=== Certify your work by adding your `Signed-off-by` trailer - -To improve tracking of who did what, we ask you to certify that you -wrote the patch or have the right to pass it on under the same license -as ours, by "signing off" your patch. Without sign-off, we cannot -accept your patches. - -If (and only if) you certify the below D-C-O: - -[[dco]] -.Developer's Certificate of Origin 1.1 -____ -By making a contribution to this project, I certify that: - -a. The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -b. The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -c. The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -d. I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -____ - -you add a "Signed-off-by" trailer to your commit, that looks like -this: - -.... - Signed-off-by: Random J Developer <random@developer.example.org> -.... - -This line can be added by Git if you run the git-commit command with -the -s option. - -Notice that you can place your own `Signed-off-by` trailer when -forwarding somebody else's patch with the above rules for -D-C-O. Indeed you are encouraged to do so. Do not forget to -place an in-body "From: " line at the beginning to properly attribute -the change to its true author (see (2) above). - -This procedure originally came from the Linux kernel project, so our -rule is quite similar to theirs, but what exactly it means to sign-off -your patch differs from project to project, so it may be different -from that of the project you are accustomed to. - -[[real-name]] -Also notice that a real name is used in the `Signed-off-by` trailer. Please -don't hide your real name. - -[[commit-trailers]] -If you like, you can put extra tags at the end: - -. `Reported-by:` is used to credit someone who found the bug that - the patch attempts to fix. -. `Acked-by:` says that the person who is more familiar with the area - the patch attempts to modify liked the patch. -. `Reviewed-by:`, unlike the other tags, can only be offered by the - reviewers themselves when they are completely satisfied with the - 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:". - == Subsystems with dedicated maintainers Some parts of the system have dedicated maintainers with their own @@ -392,7 +537,10 @@ repositories. - `gitk-git/` comes from Paul Mackerras's gitk project: - git://ozlabs.org/~paulus/gitk + git://git.ozlabs.org/~paulus/gitk + + 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: @@ -432,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]] @@ -446,16 +594,15 @@ 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. -[[travis]] -== GitHub-Travis CI hints +== GitHub CI[[GHCI]] -With an account at GitHub (you can get one for free to work on open -source projects), you can use Travis CI to test your changes on Linux, -Mac (and hopefully soon Windows). You can find a successful example -test build here: https://travis-ci.org/git/git/builds/120473209 +With an account at GitHub, you can use GitHub CI to test your changes +on Linux, Mac and Windows. See +https://github.com/git/git/actions/workflows/main.yml for examples of +recent CI runs. Follow these steps for the initial setup: @@ -463,36 +610,24 @@ Follow these steps for the initial setup: You can find detailed instructions how to fork here: https://help.github.com/articles/fork-a-repo/ -. Open the Travis CI website: https://travis-ci.org - -. Press the "Sign in with GitHub" button. - -. Grant Travis CI permissions to access your GitHub account. - You can find more information about the required permissions here: - https://docs.travis-ci.com/user/github-oauth-scopes - -. Open your Travis CI profile page: https://travis-ci.org/profile - -. Enable Travis CI builds for your Git fork. - -After the initial setup, Travis CI will run whenever you push new changes +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://travis-ci.org/__<Your GitHub handle>__/git/branches +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 Travis CI job and -scroll all the way down in the log. Find the line "<-- Click here to see -detailed test output!" and click on the triangle next to the log line -number to expand the detailed test output. Here is such a failing -example: https://travis-ci.org/git/git/jobs/122676187 +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. -Fix the problem and push your fix to your Git fork. This will trigger -a new Travis CI build to ensure all tests pass. +Then fix the problem and push your fix to your GitHub fork. This will +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. @@ -576,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 new file mode 100644 index 0000000..ae7690b --- /dev/null +++ b/Documentation/ToolsForGit.txt @@ -0,0 +1,51 @@ +Tools for developing Git +======================== +:sectanchors: + +[[summary]] +== Summary + +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. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +[[emacs]] +=== Emacs + +This is adapted from Linux's suggestion in its CodingStyle document: + +- 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 +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +For a more complete setup, since Git's codebase uses a coding style +similar to the Linux kernel's style, tips given in Linux's CodingStyle +document can be applied here too. + +==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it 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 117f4cf..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 @@ -136,5 +134,16 @@ take effect. option. An empty file name, `""`, will clear the list of revs from previously processed files. +--color-lines:: + Color line annotations in the default format differently if they come from + the same commit as the preceding line. This makes it easier to distinguish + code blocks introduced by different commits. The color defaults to cyan and + can be adjusted using the `color.blame.repeatedLines` config option. + +--color-by-age:: + Color line annotations depending on the age of the line in the default format. + The `color.blame.highlightRecent` config option controls what color is used for + each range of age. + -h:: Show help message. 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 bf82766..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. @@ -159,6 +161,33 @@ all branches that begin with `foo/`. This is useful if your branches are organized hierarchically and you would like to apply a configuration to all the branches in that hierarchy. +`hasconfig:remote.*.url:`:: + The data that follows this keyword is taken to + be a pattern with standard globbing wildcards and two + additional ones, `**/` and `/**`, that can match multiple + components. The first time this keyword is seen, the rest of + the config files will be scanned for remote URLs (without + applying any values). If there exists at least one remote URL + that matches this pattern, the include condition is met. ++ +Files included by this option (directly or indirectly) are not allowed +to contain remote URLs. ++ +Note that unlike other includeIf conditions, resolving this condition +relies on information that is not yet known at the point of reading the +condition. A typical use case is this option being present as a +system-level or global-level config, and the remote URL being in a +local-level config; hence the need to scan ahead when resolving this +condition. In order to avoid the chicken-and-egg problem in which +potentially-included files can affect whether such files are potentially +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 compatibility with +a naming scheme that supports more variable-based include conditions, +but currently Git only supports the exact keyword described above. + A few more notes on matching via `gitdir` and `gitdir/i`: * Symlinks in `$GIT_DIR` are not resolved before matching. @@ -226,6 +255,14 @@ Example ; currently checked out [includeIf "onbranch:foo-branch"] path = foo.inc + +; include only if a remote with the given URL exists (note +; that such a URL may be provided later in a file or in a +; file read after this file is read, as seen in this example) +[includeIf "hasconfig:remote.*.url:https://example.com/**"] + path = foo.inc +[remote "origin"] + url = https://example.com/git ---- Values @@ -262,11 +299,19 @@ color:: colors (at most two, one for foreground and one for background) and attributes (as many as you want), separated by spaces. + -The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, -`blue`, `magenta`, `cyan` and `white`. The first color given is the -foreground; the second is the background. All the basic colors except -`normal` have a bright variant that can be specified by prefixing the -color with `bright`, like `brightred`. +The basic colors accepted are `normal`, `black`, `red`, `green`, +`yellow`, `blue`, `magenta`, `cyan`, `white` and `default`. The first +color given is the foreground; the second is the background. All the +basic colors except `normal` and `default` have a bright variant that can +be specified by prefixing the color with `bright`, like `brightred`. ++ +The color `normal` makes no change to the color. It is the same as an +empty string, but can be used as the foreground color when specifying a +background color alone (for example, "normal red"). ++ +The color `default` explicitly resets the color to the terminal default, +for example to specify a cleared background. Although it varies between +terminals, this is usually not the same as setting to "white black". + Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If @@ -280,6 +325,11 @@ The position of any attributes with respect to the colors be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, `no-ul`, etc). + +The pseudo-attribute `reset` resets all colors and attributes before +applying the specified coloring. For example, `reset green` will result +in a green foreground and default background without any active +attributes. ++ An empty color string produces no color effect at all. This can be used to avoid coloring specific elements without disabling color entirely. + @@ -298,6 +348,15 @@ pathname:: tilde expansion happens to such a string: `~/` is expanded to the value of `$HOME`, and `~user/` to the specified user's home directory. ++ +If a path starts with `%(prefix)/`, the remainder is interpreted as a +path relative to Git's "runtime prefix", i.e. relative to the location +where Git itself was installed. For example, `%(prefix)/bin/` refers to +the directory in which the Git executable itself lives. If Git was +compiled without runtime prefix support, the compiled-in prefix will be +substituted instead. In the unlikely event that a literal path needs to +be specified that should _not_ be expanded, it needs to be prefixed by +`./`, like so: `./%(prefix)/bin`. Variables @@ -312,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[] @@ -344,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[] @@ -360,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[] @@ -388,6 +453,8 @@ include::config/i18n.txt[] include::config/imap.txt[] +include::config/includeif.txt[] + include::config/index.txt[] include::config/init.txt[] @@ -438,7 +505,9 @@ include::config/repack.txt[] include::config/rerere.txt[] -include::config/reset.txt[] +include::config/revert.txt[] + +include::config/safe.txt[] include::config/sendemail.txt[] @@ -446,14 +515,16 @@ include::config/sequencer.txt[] include::config/showbranch.txt[] +include::config/sparse.txt[] + 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 c9f748f..e0354ce 100644 --- a/Documentation/config/add.txt +++ b/Documentation/config/add.txt @@ -7,6 +7,7 @@ add.ignore-errors (deprecated):: variables. add.interactive.useBuiltin:: - [EXPERIMENTAL] Set to `true` to use the experimental built-in - implementation of the interactive version of linkgit:git-add[1] - instead of the Perl script version. Is `false` 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 8b2849f..0e35ae5 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -1,26 +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:: + 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.) @@ -33,17 +72,48 @@ 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. statusAheadBehind:: Shown when linkgit:git-status[1] computes the ahead/behind counts for a local ref compared to its remote tracking ref, @@ -56,71 +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. - resetQuiet:: - Advice to consider using the `--quiet` option to linkgit:git-reset[1] - when the command takes more than 2 seconds to enumerate unstaged - changes 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. - 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. - 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. + submoduleMergeConflict:: + Advice shown when a non-trivial submodule merge conflict is + encountered. + submodulesNotUpdated:: + Shown when a user runs a submodule command that fails + because `git submodule update --init` was not run. + 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 cc5f324..432b9cd 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -7,8 +7,11 @@ branch.autoSetupMerge:: automatic setup is done; `true` -- automatic setup is done when the starting point is a remote-tracking branch; `always` -- automatic setup is done when the starting point is either a - local branch or remote-tracking - branch. This option defaults to true. + local branch or remote-tracking branch; `inherit` -- if the starting point + has a tracking configuration, it is copied to the new + branch; `simple` -- automatic setup is done only when the starting point + is a remote-tracking branch and the new branch has the same name as the + remote branch. This option defaults to true. branch.autoSetupRebase:: When a new branch is created with 'git branch', 'git switch' or 'git checkout' @@ -33,12 +36,13 @@ 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 - configured, or if you are not on any branch, it defaults to - `origin` for fetching and `remote.pushDefault` for pushing. + configured, or if you are not on any branch and there is more than + one remote defined in the repository, it defaults to `origin` for + fetching and `remote.pushDefault` for pushing. Additionally, `.` (a period) is the current local repository (a dot-repository), see `branch.<name>.merge`'s final note below. @@ -60,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. @@ -85,10 +89,6 @@ When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When `preserve` (or just 'p', deprecated in favor of `merges`), also pass -`--preserve-merges` along to 'git rebase' so that locally committed merge -commits will not be flattened by running 'git pull'. -+ When the value is `interactive` (or just 'i'), the rebase is run in interactive mode. + @@ -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 7bcfbd1..0a10efd 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -1,8 +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`:: + 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 e05d520..2f2275a 100644 --- a/Documentation/config/color.txt +++ b/Documentation/config/color.txt @@ -9,26 +9,27 @@ color.advice.hint:: Use customized color for hints. color.blame.highlightRecent:: - This can be used to color the metadata of a blame line depending - on age of the line. + Specify the line annotation color for `git blame --color-by-age` + depending upon the age of the line. + -This setting should be set to a comma-separated list of color and date settings, -starting and ending with a color, the dates should be set from oldest to newest. -The metadata will be colored given the colors if the line was introduced -before the given timestamp, overwriting older timestamped colors. +This setting should be set to a comma-separated list of color and +date settings, starting and ending with a color, the dates should be +set from oldest to newest. The metadata will be colored with the +specified colors if the line was introduced before the given +timestamp, overwriting older timestamped colors. + -Instead of an absolute timestamp relative timestamps work as well, e.g. -2.weeks.ago is valid to address anything older than 2 weeks. +Instead of an absolute timestamp relative timestamps work as well, +e.g. `2.weeks.ago` is valid to address anything older than 2 weeks. + -It defaults to 'blue,12 month ago,white,1 month ago,red', which colors -everything older than one year blue, recent changes between one month and -one year old are kept white, and lines introduced within the last month are -colored red. +It defaults to `blue,12 month ago,white,1 month ago,red`, which +colors everything older than one year blue, recent changes between +one month and one year old are kept white, and lines introduced +within the last month are colored red. color.blame.repeatedLines:: - Use the customized color for the part of git-blame output that - is repeated meta information per line (such as commit id, - author name, date and timezone). Defaults to cyan. + Use the specified color to colorize line annotations for + `git blame --color-lines`, if they come from the same commit as the + preceding line. Defaults to cyan. color.branch:: A boolean to enable/disable color in the output of @@ -104,9 +105,12 @@ color.grep.<slot>:: `matchContext`;; matching text in context lines `matchSelected`;; - matching text in selected lines + matching text in selected lines. Also, used to customize the following + linkgit:git-log[1] subcommands: `--grep`, `--author`, and `--committer`. `selected`;; - non-matching text in selected lines + non-matching text in selected lines. Also, used to customize the + following linkgit:git-log[1] subcommands: `--grep`, `--author` and + `--committer`. `separator`;; separators between fields on a line (`:`, `-`, and `=`) and between hunks (`--`) 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 c04f62a..93d65e1 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -62,22 +62,54 @@ core.protectNTFS:: Defaults to `true` on Windows, and `false` elsewhere. core.fsmonitor:: - If set, the value of this variable is used as a command which - will identify all files that may have changed since the - requested date/time. This information is used to speed up git by - avoiding unnecessary processing of files that have not changed. - See the "fsmonitor-watchman" section of linkgit:githooks[5]. + If set to true, enable the built-in file system monitor + daemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]). ++ +Like hook-based file system monitors, the built-in file system monitor +can speed up Git commands that need to refresh the Git index +(e.g. `git status`) in a working directory with many files. The +built-in monitor eliminates the need to install and maintain an +external third-party tool. ++ +The built-in file system monitor is currently available only on a +limited set of supported platforms. Currently, this includes Windows +and MacOS. ++ + Otherwise, this variable contains the pathname of the "fsmonitor" + hook command. ++ +This hook command is used to identify all files that may have changed +since the requested date/time. This information is used to speed up +git by avoiding unnecessary scanning of files that have not changed. ++ +See the "fsmonitor-watchman" section of linkgit:githooks[5]. ++ +Note that if you concurrently use multiple versions of Git, such +as one version on the command line and another version in an IDE +tool, that the definition of `core.fsmonitor` was extended to +allow boolean values in addition to hook pathnames. Git versions +2.35.1 and prior will not understand the boolean values and will +consider the "true" or "false" values as hook pathnames to be +invoked. Git versions 2.26 thru 2.35.1 default to hook protocol +V2 and will fall back to no fsmonitor (full scan). Git versions +prior to 2.26 default to hook protocol V1 and will silently +assume there were no changes to report (no scan), so status +commands may report incomplete results. For this reason, it is +best to upgrade all of your Git versions before using the built-in +file system monitor. core.fsmonitorHookVersion:: - Sets the version of hook that is to be used when calling fsmonitor. - There are currently versions 1 and 2. When this is not set, - version 2 will be tried first and if it fails then version 1 - will be tried. Version 1 uses a timestamp as input to determine - which files have changes since that time but some monitors - like watchman have race conditions when used with a timestamp. - Version 2 uses an opaque string so that the monitor can return - something that can be used to determine what files have changed - without race conditions. + Sets the protocol version to be used when invoking the + "fsmonitor" hook. ++ +There are currently versions 1 and 2. When this is not set, +version 2 will be tried first and if it fails then version 1 +will be tried. Version 1 uses a timestamp as input to determine +which files have changes since that time but some monitors +like Watchman have race conditions when used with a timestamp. +Version 2 uses an opaque string so that the monitor can return +something that can be used to determine what files have changed +without race conditions. core.trustctime:: If false, the ctime differences between the index and the @@ -412,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 @@ -473,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 @@ -480,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 @@ -547,13 +609,72 @@ core.whitespace:: is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent` errors. The default tab width is 8. Allowed values are 1 to 63. +core.fsync:: + A comma-separated list of components of the repository that + should be hardened via the core.fsyncMethod when created or + modified. You can disable hardening of any component by + prefixing it with a '-'. Items that are not hardened may be + lost in the event of an unclean system shutdown. Unless you + have special requirements, it is recommended that you leave + this option empty or pick one of `committed`, `added`, + or `all`. ++ +When this configuration is encountered, the set of components starts with +the platform default value, disabled components are removed, and additional +components are added. `none` resets the state so that the platform default +is ignored. ++ +The empty string resets the fsync configuration to the platform +default. The default on most platforms is equivalent to +`core.fsync=committed,-loose-object`, which has good performance, +but risks losing recent work in the event of an unclean system shutdown. ++ +* `none` clears the set of fsynced components. +* `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. +* `index` hardens the index when it is modified. +* `objects` is an aggregate option that is equivalent to + `loose-object,pack`. +* `reference` hardens references modified in the repo. +* `derived-metadata` is an aggregate option that is equivalent to + `pack-metadata,commit-graph`. +* `committed` is an aggregate option that is currently equivalent to + `objects`. This mode sacrifices some performance to ensure that work + that is committed to the repository with `git commit` or similar commands + is hardened. +* `added` is an aggregate option that is currently equivalent to + `committed,index`. This mode sacrifices additional performance to + ensure that the results of commands like `git add` and similar operations + are hardened. +* `all` is an aggregate option that syncs all individual components above. + +core.fsyncMethod:: + A value indicating the strategy Git will use to harden repository data + using fsync and related primitives. ++ +* `fsync` uses the fsync() system call or platform equivalents. +* `writeout-only` issues pagecache writeback requests, but depending on the + filesystem and storage hardware, data added to the repository may not be + durable in the event of a system crash. This is the default mode on macOS. +* `batch` enables a mode that uses writeout-only flushes to stage multiple + updates in the disk writeback cache and then does a single full fsync of + a dummy file to trigger the disk cache flush at the end of the operation. ++ +Currently `batch` mode only applies to loose-object files. Other repository +data is made durable as if `fsync` was specified. This mode is expected to +be as safe as `fsync` on macOS for repos stored on HFS+ or APFS filesystems +and on Windows for repos stored on NTFS or ReFS filesystems. + core.fsyncObjectFiles:: This boolean will enable 'fsync()' when writing object files. + This setting is deprecated. Use core.fsync instead. + -This is a total waste of time and effort on a filesystem that orders -data writes properly, but can be useful for filesystems that do not use -journalling (traditional UNIX filesystems) or that only journal metadata -and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback"). +This setting affects data added to the Git repository in loose-object +form. When set to true, Git will issue an fsync or similar system call +to flush caches so that loose-objects remain consistent in the face +of a unclean system shutdown. core.preloadIndex:: Enable parallel index preload for operations like 'git diff' @@ -582,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:: @@ -615,8 +736,10 @@ core.sparseCheckout:: core.sparseCheckoutCone:: Enables the "cone mode" of the sparse checkout feature. When the - sparse-checkout file contains a limited set of patterns, then this - mode provides significant performance advantages. See + 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 more flexible + patterns by setting this variable to 'false'. See linkgit:git-sparse-checkout[1] for more information. core.abbrev:: @@ -628,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 2d3331f..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. @@ -118,9 +128,10 @@ diff.orderFile:: relative to the top of the working tree. diff.renameLimit:: - The number of files to consider when performing the copy/rename - detection; equivalent to the 'git diff' option `-l`. This setting - has no effect if rename detection is turned off. + The number of files to consider in the exhaustive portion of + copy/rename detection; equivalent to the 'git diff' option + `-l`. If not set, the default value is currently 1000. This + setting has no effect if rename detection is turned off. diff.renames:: Whether and how Git detects renames. If set to "false", @@ -177,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:: @@ -233,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 4e23d73..38dce3d 100644 --- a/Documentation/config/extensions.txt +++ b/Documentation/config/extensions.txt @@ -6,3 +6,57 @@ extensions.objectFormat:: 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 + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and + `$GIT_DIR` are the same for the main working tree, while other + working trees have `$GIT_DIR` equal to + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the + `config.worktree` file will override settings from any other + config files. ++ +When enabling `extensions.worktreeConfig`, you must be careful to move +certain values from the common config file to the main working tree's +`config.worktree` file, if present: ++ +* `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to + `$GIT_COMMON_DIR/config.worktree`. +* If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config` + to `$GIT_COMMON_DIR/config.worktree`. ++ +It may also be beneficial to adjust the locations of `core.sparseCheckout` +and `core.sparseCheckoutCone` depending on your desire for customizable +sparse-checkout settings for each worktree. By default, the `git +sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns +these config values on a per-worktree basis, and uses the +`$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each +worktree independently. See linkgit:git-sparse-checkout[1] for more +details. ++ +For historical reasons, `extensions.worktreeConfig` is respected +regardless of the `core.repositoryFormatVersion` setting. 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 63748c0..d7dc461 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -50,24 +50,31 @@ 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 is - sent when negotiating the contents of the packfile to be sent by the - server. Set to "skipping" to use an algorithm that skips commits in an - effort to converge faster, but may result in a larger-than-necessary - packfile; or set to "noop" to not send any information at all, which - will almost certainly result in a larger-than-necessary packfile, but - will skip the negotiation step. - The default is "default" which instructs Git to use the default algorithm - that never skips commits (unless the server has acknowledged it or one - of its descendants). If `feature.experimental` is enabled, then this - setting defaults to "skipping". - Unknown values will cause 'git fetch' to error out. + Control how information about the commits in the local repository + is sent when negotiating the contents of the packfile to be sent by + the server. Set to "consecutive" to use an algorithm that walks + over consecutive commits checking each one. Set to "skipping" to + use an algorithm that skips commits in an effort to converge + faster, but may result in a larger-than-necessary packfile; or set + to "noop" to not send any information at all, which will almost + certainly result in a larger-than-necessary packfile, but will skip + the negotiation step. Set to "default" to override settings made + previously and use the default behaviour. The default is normally + "consecutive", but if `feature.experimental` is true, then the + default is "skipping". Unknown values will cause 'git fetch' to + error out. + See also the `--negotiate-only` and `--negotiation-tip` options to linkgit:git-fetch[1]. @@ -95,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 c834e07..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 @@ -81,14 +81,27 @@ gc.packRefs:: to enable it within all non-bare repos or it can be set to a boolean value. The default is `true`. +gc.cruftPacks:: + Store unreachable objects in a cruft pack (see + linkgit:git-repack[1]) instead of as loose objects. The default + 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'. - Override the grace period with this config variable. The value - "now" may be used to disable this grace period and always prune - unreachable objects immediately, or "never" may be used to - suppress pruning. This feature helps prevent corruption when - 'git gc' runs concurrently with another process writing to the - repository; see the "NOTES" section of linkgit:git-gc[1]. + When 'git gc' is run, it will call 'prune --expire 2.weeks.ago' + (and 'repack --cruft --cruft-expiration 2.weeks.ago' if using + cruft packs via `gc.cruftPacks` or `--cruft`). Override the + grace period with this config variable. The value "now" may be + used to disable this grace period and always prune unreachable + objects immediately, or "never" may be used to suppress pruning. + This feature helps prevent corruption when 'git gc' runs + concurrently with another process writing to the repository; see + the "NOTES" section of linkgit:git-gc[1]. gc.worktreePruneExpire:: When 'git gc' is run, it calls @@ -123,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 d94025c..5cf32b1 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -4,25 +4,28 @@ 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. gpg.format:: Specifies which key format to use when signing with `--gpg-sign`. - Default is "openpgp" and another possible value is "x509". + 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 chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still be used as a legacy synonym for `gpg.openpgp.program`. The default - value for `gpg.x509.program` is "gpgsm". + value for `gpg.x509.program` is "gpgsm" and `gpg.ssh.program` is "ssh-keygen". 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, @@ -33,3 +36,50 @@ gpg.minTrustLevel:: * `marginal` * `fully` * `ultimate` + +gpg.ssh.defaultKeyCommand:: + 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 + key when it is impractical to statically configure `user.signingKey`. + For example when keys or SSH Certificates are rotated frequently or + selection of the right key depends on external factors unknown to git. + +gpg.ssh.allowedSignersFile:: + A file containing ssh public keys which you are willing to trust. + The file consists of one or more lines of principals followed by an ssh + public key. + e.g.: `user1@example.com,user2@example.com ssh-rsa AAAAX1...` + See ssh-keygen(1) "ALLOWED SIGNERS" for details. + The principal is only used to identify the key and is available when + verifying a signature. ++ +SSH has no concept of trust levels like gpg does. To be able to differentiate +between valid signatures and trusted signatures the trust level of a signature +verification is set to `fully` when the public key is present in the allowedSignersFile. +Otherwise the trust level is `undefined` and git verify-commit/tag will fail. ++ +This file can be set to a location outside of the repository and every developer +maintains their own trust store. A central repository server could generate this +file automatically from ssh keys with push access to verify the code against. +In a corporate setting this file is probably generated at a global location +from automation that already handles developer ssh keys. ++ +A repository that only allows signed commits can store the file +in the repository itself using a path relative to the top-level of the working tree. +This way only committers with an already valid key can add or change keys in the keyring. ++ +Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after & +valid-before options. Git will mark signatures as valid if the signing key was +valid at the time of the signature's creation. This allows users to change a +signing key without invalidating all previously made signatures. ++ +Using a SSH CA key with the cert-authority option +(see ssh-keygen(1) "CERTIFICATES") is also valid. + +gpg.ssh.revocationFile:: + Either a SSH KRL or a list of revoked public keys (without the principal prefix). + See ssh-keygen(1) for details. + If a public key is found in this file then it will always be treated + as having trust level "never" and signatures will show as invalid. diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt index 44abe45..10041f2 100644 --- a/Documentation/config/grep.txt +++ b/Documentation/config/grep.txt @@ -8,7 +8,8 @@ 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. + value 'default' will use the `grep.extendedRegexp` option to choose + between 'basic' and 'extended'. grep.extendedRegexp:: If set to true, enable `--extended-regexp` option by default. This @@ -16,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 d30831a..171be77 100644 --- a/Documentation/config/gui.txt +++ b/Documentation/config/gui.txt @@ -11,7 +11,7 @@ gui.displayUntracked:: in the file list. The default is "true". gui.encoding:: - Specifies the default encoding to use for displaying of + Specifies the default character encoding to use for displaying of file contents in linkgit:git-gui[1] and linkgit:gitk[1]. It can be overridden by setting the 'encoding' attribute for relevant files (see linkgit:gitattributes[5]). @@ -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/help.txt b/Documentation/config/help.txt index 783a90a..610701f 100644 --- a/Documentation/config/help.txt +++ b/Documentation/config/help.txt @@ -9,13 +9,15 @@ help.format:: help.autoCorrect:: If git detects typos and can identify exactly one valid command similar - to the error, git will automatically run the intended command after - waiting a duration of time defined by this configuration value in - deciseconds (0.1 sec). If this value is 0, the suggested corrections - will be shown, but not executed. If it is a negative integer, or - "immediate", the suggested command - is run immediately. If "never", suggestions are not shown at all. The - default value is zero. + to the error, git will try to suggest the correct command or even + run the suggestion automatically. Possible config values are: + - 0 (default): show the suggested command. + - positive number: run the suggested command after specified +deciseconds (0.1 sec). + - "immediate": run the suggested command immediately. + - "prompt": show the suggestion and prompt for confirmation to run +the command. + - "never": don't run or show any suggested command. help.htmlPath:: Specify the path where the HTML documentation resides. File system paths diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 7003661..2d4e0c9 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -98,6 +98,22 @@ http.version:: - HTTP/2 - HTTP/1.1 +http.curloptResolve:: + Hostname resolution information that will be used first by + libcurl when sending HTTP requests. This information should + be in one of the following formats: + + - [+]HOST:PORT:ADDRESS[,ADDRESS] + - -HOST:PORT + ++ +The first format redirects all requests to the given `HOST:PORT` +to the provided `ADDRESS`(s). The second format clears all +previous config values for that `HOST:PORT` combination. To +allow easy overriding of all the settings inherited from the +system config, an empty value will reset all resolution +information to the empty list. + http.sslVersion:: The SSL version to use when negotiating an SSL connection, if you want to force the default. The available and default version @@ -187,7 +203,7 @@ http.schannelUseSSLCAInfo:: when the `schannel` backend was configured via `http.sslBackend`, unless `http.schannelUseSSLCAInfo` overrides this behavior. -http.pinnedpubkey:: +http.pinnedPubkey:: Public key of the https service. It may either be the filename of a PEM or DER encoded public key file or a string starting with 'sha256//' followed by the base64 encoded sha256 hash of the @@ -230,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 6b66c83..8851b6c 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -4,7 +4,14 @@ merge.conflictStyle:: shows a `<<<<<<<` conflict marker, changes made by one side, a `=======` marker, changes made by the other side, and then a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` - marker and the original text before the `=======` marker. + 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 + 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 + the beginning or end of a conflict region. merge.defaultToUpstream:: If merge is called without any commit argument, merge the upstream @@ -33,10 +40,12 @@ merge.verifySignatures:: include::fmt-merge-msg.txt[] merge.renameLimit:: - The number of files to consider when performing rename detection - during a merge; if not specified, defaults to the value of - diff.renameLimit. This setting has no effect if rename detection - is turned off. + The number of files to consider in the exhaustive portion of + rename detection during a merge. If not specified, defaults + to the value of diff.renameLimit. If neither + merge.renameLimit nor diff.renameLimit are specified, + currently defaults to 7000. This setting has no effect if + rename detection is turned off. merge.renames:: Whether Git detects renames. If set to "false", rename detection diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index cafbbef..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,12 +45,28 @@ mergetool.meld.useAutoMerge:: value of `false` avoids using `--auto-merge` altogether, and is the default value. +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[] + section in linkgit:git-mergetool[1]. +endif::[] + 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`. @@ -65,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:: @@ -76,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 763f7af..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 @@ -159,10 +181,27 @@ pack.writeBitmapHashCache:: between an older, bitmapped pack and objects that have been pushed since the last gc). The downside is that it consumes 4 bytes per object of disk space. Defaults to true. ++ +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/pull.txt b/Documentation/config/pull.txt index 5404830..9349e09 100644 --- a/Documentation/config/pull.txt +++ b/Documentation/config/pull.txt @@ -18,10 +18,6 @@ When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When `preserve` (or just 'p', deprecated in favor of `merges`), also pass -`--preserve-merges` along to 'git rebase' so that locally committed merge -commits will not be flattened by running 'git pull'. -+ When the value is `interactive` (or just 'i'), the rebase is run in interactive mode. + diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index 6320336..0acbbea 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -1,3 +1,14 @@ +push.autoSetupRemote:: + If set to "true" assume `--set-upstream` on default push when no + upstream tracking exists for the current branch; this option + takes effect with push.default options 'simple', 'upstream', + and 'current'. It is useful if by default you want new branches + to be pushed to the default remote (like the behavior of + 'push.default=current') and you also want the upstream tracking + to be set. Workflows most likely to benefit from this option are + 'simple' central workflows where all branches are expected to + have the same name on the remote. + push.default:: Defines the action `git push` should take if no refspec is given (whether from the command-line, config, or elsewhere). @@ -24,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 @@ -56,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`. @@ -99,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'). @@ -126,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/remote.txt b/Documentation/config/remote.txt index a8e6437..0678b4b 100644 --- a/Documentation/config/remote.txt +++ b/Documentation/config/remote.txt @@ -82,5 +82,7 @@ remote.<name>.promisor:: objects. remote.<name>.partialclonefilter:: - The filter that will be applied when fetching from this - promisor remote. + The filter that will be applied when fetching from this promisor remote. + Changing or clearing this value will only affect fetches for new commits. + To fetch associated objects for commits already present in the local object + database, use the `--refetch` option of linkgit:git-fetch[1]. diff --git a/Documentation/config/repack.txt b/Documentation/config/repack.txt index 9c413e1..c79af6d 100644 --- a/Documentation/config/repack.txt +++ b/Documentation/config/repack.txt @@ -25,3 +25,17 @@ repack.writeBitmaps:: space and extra time spent on the initial repack. This has no effect if multiple packfiles are created. Defaults to true on bare repos, false otherwise. + +repack.updateServerInfo:: + If set to false, linkgit:git-repack[1] will not run + linkgit:git-update-server-info[1]. Defaults to true. Can be overridden + when true by the `-n` option of linkgit:git-repack[1]. + +repack.cruftWindow:: +repack.cruftWindowMemory:: +repack.cruftDepth:: +repack.cruftThreads:: + Parameters used by linkgit:git-pack-objects[1] when generating + a cruft pack and the respective parameters are not given over + the command line. See similarly named `pack.*` configuration + variables for defaults and meaning. 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/reset.txt b/Documentation/config/reset.txt deleted file mode 100644 index 63b7c45..0000000 --- a/Documentation/config/reset.txt +++ /dev/null @@ -1,2 +0,0 @@ -reset.quiet:: - When set to true, 'git reset' will default to the '--quiet' option. diff --git a/Documentation/config/revert.txt b/Documentation/config/revert.txt new file mode 100644 index 0000000..802d6fa --- /dev/null +++ b/Documentation/config/revert.txt @@ -0,0 +1,3 @@ +revert.reference:: + 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 new file mode 100644 index 0000000..577df40 --- /dev/null +++ b/Documentation/config/safe.txt @@ -0,0 +1,61 @@ +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 + current user. By default, Git will refuse to even parse a Git + config of a repository owned by someone else, let alone run its + hooks, and this config setting allows users to specify exceptions, + e.g. for intentionally shared repositories (see the `--shared` + option in linkgit:git-init[1]). ++ +This is a multi-valued setting, i.e. you can add more than one directory +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 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 +path relative to Git's (runtime) prefix. ++ +To completely opt-out of this security check, set `safe.directory` to the +string `*`. This will allow all repositories to be treated as if their +directory was listed in the `safe.directory` list. If `safe.directory=*` +is set in system config and you want to re-enable this protection, then +initialize your list with an empty value before listing the repositories +that you deem safe. ++ +As explained, Git only allows you to access repositories owned by +yourself, i.e. the user who is running Git, by default. When Git +is running as 'root' in a non Windows platform that provides sudo, +however, git checks the SUDO_UID environment variable that sudo creates +and will allow access to the uid recorded as its value in addition to +the id from 'root'. +This is to make it easy to perform a common sequence during installation +"make && sudo make install". A git process running under 'sudo' runs as +'root' but the 'sudo' command exports the environment variable to record +which id the original user has. +If that is not what you would prefer and want git to only trust +repositories that are owned by root instead, then you can remove +the `SUDO_UID` variable from root's environment before invoking git. 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/sparse.txt b/Documentation/config/sparse.txt new file mode 100644 index 0000000..aff49a8 --- /dev/null +++ b/Documentation/config/sparse.txt @@ -0,0 +1,27 @@ +sparse.expectFilesOutsideOfPatterns:: + Typically with sparse checkouts, files not matching any + sparsity patterns are marked with a SKIP_WORKTREE bit in the + index and are missing from the working tree. Accordingly, Git + will ordinarily check whether files with the SKIP_WORKTREE bit + are in fact present in the working tree contrary to + expectations. If Git finds any, it marks those paths as + present by clearing the relevant SKIP_WORKTREE bits. This + option can be used to tell Git that such + present-despite-skipped files are expected and to stop + checking for them. ++ +The default is `false`, which allows Git to automatically recover +from the list of files in the index and working tree falling out of +sync. ++ +Set this to `true` if you are in a setup where some external factor +relieves Git of the responsibility for maintaining the consistency +between the presence of working tree files and sparsity patterns. For +example, if you have a Git-aware virtual file system that has a robust +mechanism for keeping the working tree and the sparsity patterns up to +date based on access patterns. ++ +Regardless of this setting, Git does not check for +present-despite-skipped files unless sparse checkout is enabled, so +this config option has no effect unless `core.sparseCheckout` is +`true`. 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 9ed7752..ec1edae 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -1,21 +1,14 @@ -stash.useBuiltin:: - Unused configuration variable. Used in Git versions 2.22 to - 2.26 as an escape hatch to enable the legacy shellscript - implementation of stash. Now the built-in rewrite of it in C - is always used. Setting this will emit a warning, to alert any - remaining users that setting this now does nothing. - 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 d7a63c8..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. @@ -58,18 +58,34 @@ submodule.active:: commands. See linkgit:gitsubmodules[7] for details. submodule.recurse:: - Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option - (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, - `restore` and `switch`) except `clone` and `ls-files`. + A boolean indicating if commands should enable the `--recurse-submodules` + option by default. Defaults to false. ++ +When set to true, it can be deactivated via the +`--no-recurse-submodules` option. Note that some Git commands +lacking this option may call some of the above commands affected by +`submodule.recurse`; for instance `git remote update` will call +`git fetch` but does not have a `--no-recurse-submodules` option. +For these commands a workaround is to temporarily change the +configuration value by using `git -c submodule.recurse=0`. ++ +The following list shows the commands that accept +`--recurse-submodules` and whether they are supported by this +setting. + +* `checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, +`reset`, `restore` and `switch` are always supported. +* `clone` and `ls-files` are not supported. +* `branch` is supported only if `submodule.propagateBranches` is +enabled + +submodule.propagateBranches:: + [EXPERIMENTAL] A boolean that enables branching support when + using `--recurse-submodules` or `submodule.recurse=true`. + Enabling this will allow certain commands to accept + `--recurse-submodules` and certain commands that already accept + `--recurse-submodules` will now consider branches. Defaults to false. - When set to true, it can be deactivated via the - `--no-recurse-submodules` option. Note that some Git commands - lacking this option may call some of the above commands affected by - `submodule.recurse`; for instance `git remote update` will call - `git fetch` but does not have a `--no-recurse-submodules` option. - For these commands a workaround is to temporarily change the - configuration value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. 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 505126a..f1ce50f 100644 --- a/Documentation/config/transfer.txt +++ b/Documentation/config/transfer.txt @@ -1,3 +1,41 @@ +transfer.credentialsInUrl:: + A configured URL can contain plaintext credentials in the form + `<protocol>://<user>:<password>@<domain>/<path>`. You may want + to warn or forbid the use of such configuration (in favor of + using linkgit:git-credential[1]). This will be used on + linkgit:git-clone[1], linkgit:git-fetch[1], linkgit:git-push[1], + 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>.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 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 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 sensitive +data in git's configuration files. If you do want to use this, set +`transfer.credentialsInUrl` to one of these values: ++ +* `allow` (default): Git will proceed with its activity without warning. +* `warn`: Git will write a warning message to `stderr` when parsing a URL + with a plaintext credential. +* `die`: Git will write a failure message to `stderr` when parsing a URL + with a plaintext credential. + transfer.fsckObjects:: When `fetch.fsckObjects` or `receive.fsckObjects` are not set, the value of this variable is used instead. @@ -52,13 +90,17 @@ If you have multiple hideRefs values, later entries override earlier ones (and entries in more-specific config files override less-specific ones). + If a namespace is in use, the namespace prefix is stripped from each -reference before it is matched against `transfer.hiderefs` patterns. +reference before it is matched against `transfer.hiderefs` patterns. In +order to match refs before stripping, add a `^` in front of the ref name. If +you combine `!` and `^`, `!` must be specified first. ++ For example, if `refs/heads/master` is specified in `transfer.hideRefs` and the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master` -is omitted from the advertisements but `refs/heads/master` and -`refs/namespaces/bar/refs/heads/master` are still advertised as so-called -"have" lines. In order to match refs before stripping, add a `^` in front of -the ref name. If you combine `!` and `^`, `!` must be specified first. +is omitted from the advertisements. If `uploadpack.allowRefInWant` is set, +`upload-pack` will treat `want-ref refs/heads/master` in a protocol v2 +`fetch` command as if `refs/namespaces/foo/refs/heads/master` did not exist. +`receive-pack`, on the other hand, will still advertise the object id the +ref is pointing to without mentioning its name (a so-called ".have" line). + Even if you hide refs, a client may still be able to steal the target objects via the techniques described in the "SECURITY" section of the @@ -73,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 59aec7c..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 @@ -36,3 +36,13 @@ user.signingKey:: commit, you can override the default selection with this variable. This option is passed unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports. + If gpg.format is set to `ssh` this can contain the path to either + 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 + 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 + as "key::ssh-rsa XXXXXX identifier", but this form is deprecated; + use the `key::` form instead. 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/date-formats.txt b/Documentation/date-formats.txt index 99c455f..67645ca 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -5,9 +5,9 @@ The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables support the following date formats: Git internal format:: - It is `<unix timestamp> <time zone offset>`, where `<unix - timestamp>` is the number of seconds since the UNIX epoch. - `<time zone offset>` is a positive or negative offset from UTC. + It is `<unix-timestamp> <time-zone-offset>`, where + `<unix-timestamp>` is the number of seconds since the UNIX epoch. + `<time-zone-offset>` is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is `+0100`. RFC 2822:: diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index fbbd410..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. @@ -59,7 +59,7 @@ Possible status letters are: - D: deletion of a file - M: modification of the contents or mode of a file - R: renaming of a file -- T: change in the type of the file +- T: change in the type of the file (regular file, symbolic link or submodule) - U: file is unmerged (you must complete the merge before it can be committed) - X: "unknown" change type (most probably a bug, please report it) @@ -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 32e6dee..0e94569 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,66 +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):: +-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. ++ +The following formats are supported: + ---diff-merges=(off|none)::: ---no-diff-merges::: +-- +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. The default format could be changed using - `log.diffMerges` configuration parameter, which default value - is `separate`. `-m` implies `-p`. -+ ---diff-merges=first-parent::: ---diff-merges=1::: - This option makes merge commits show the full diff with - respect to the first parent only. -+ ---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. This is the format that `-m` produced - historically. -+ ---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`. +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`. ++ +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. ++ +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. ++ +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). +-- --combined-all-paths:: This flag causes combined diffs (used for merge commits) to @@ -189,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>`. @@ -270,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 @@ -285,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. @@ -588,11 +617,17 @@ When used together with `-B`, omit also the preimage in the deletion part of a delete/create pair. -l<num>:: - The `-M` and `-C` options require O(n^2) processing time where n - is the number of potential rename/copy targets. This - option prevents rename/copy detection from running if - the number of rename/copy targets exceeds the specified - number. + The `-M` and `-C` options involve some preliminary steps that + can detect subsets of renames/copies cheaply, followed by an + exhaustive fallback portion that compares all remaining + unpaired destinations to all relevant sources. (For renames, + only remaining unpaired sources are relevant; for copies, all + original sources are relevant.) For N sources and + destinations, this exhaustive check is O(N^2). This option + prevents the exhaustive portion of rename/copy detection from + running if the number of source/destination files involved + exceeds the specified number. Defaults to diff.renameLimit. + Note that a value of 0 is treated as unlimited. ifndef::git-format-patch[] --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]:: @@ -610,11 +645,8 @@ ifndef::git-format-patch[] Also, these upper-case letters can be downcased to exclude. E.g. `--diff-filter=ad` excludes added and deleted paths. + -Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled. +Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled. -S<string>:: Look for differences that change the number of occurrences of @@ -714,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. @@ -831,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 e967ff1..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>:: @@ -71,12 +72,20 @@ configuration variables documented in linkgit:git-config[1], and the ancestors of the provided `--negotiation-tip=*` arguments, which we have in common with the server. + +This is incompatible with `--recurse-submodules=[yes|on-demand]`. Internally this is used to implement the `push.negotiate` option, see 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` @@ -88,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] @@ -162,6 +171,16 @@ endif::git-pull[] behavior for a remote may be specified with the remote.<name>.tagOpt setting. See linkgit:git-config[1]. +ifndef::git-pull[] +--refetch:: + Instead of negotiating with the server to avoid transferring commits and + associated objects that are already present locally, this option fetches + all objects as a fresh clone would. Use this to reapply a partial clone + filter from configuration or using `--filter=` when the filter + definition has changed. Automatic post-fetch maintenance will perform + object database pack consolidation to remove any duplicate objects. +endif::git-pull[] + --refmap=<refspec>:: When fetching refs listed on the command line, use the specified refspec (can be given more than once) to map the @@ -183,17 +202,25 @@ 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 - populated submodules should be fetched too. It can be used as a - boolean option to completely disable recursion when set to 'no' or to - unconditionally recurse into all populated submodules when set to - 'yes', which is the default when this option is used without any - value. Use 'on-demand' to only recurse into a populated submodule - when the superproject retrieves a commit that updates the submodule's - reference to a commit that isn't already in the local submodule - clone. By default, 'on-demand' is used, unless - `fetch.recurseSubmodules` is set (see linkgit:git-config[1]). + submodules should be fetched too. When recursing through submodules, + `git fetch` always attempts to fetch "changed" submodules, that is, a + submodule that has commits that are referenced by a newly fetched + superproject commit but are missing in the local submodule clone. A + changed submodule can be fetched as long as it is present locally e.g. + in `$GIT_DIR/modules/` (see linkgit:gitsubmodules[7]); if the upstream + adds a new submodule, that submodule cannot be fetched until it is + cloned e.g. by `git submodule update`. ++ +When set to 'on-demand', only changed submodules are fetched. When set +to 'yes', all populated submodules are fetched and submodules that are +both unpopulated and changed are fetched. When set to 'no', submodules +are never fetched. ++ +When unspecified, this uses the value of `fetch.recurseSubmodules` if it +is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset. +When this option is used without any value, it defaults to 'yes'. endif::git-pull[] -j:: 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 be5e3ac..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]] + [--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:: @@ -79,6 +79,13 @@ in linkgit:gitglossary[7]. --force:: Allow adding otherwise ignored files. +--sparse:: + Allow updating index entries outside of the sparse-checkout cone. + Normally, `git add` refuses to update index entries whose paths do + not fit within the sparse-checkout cone, since those files might + be removed from the working tree without warning. See + linkgit:git-sparse-checkout[1] for more details. + -i:: --interactive:: Add modified contents in the working tree interactively to @@ -112,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). @@ -124,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). @@ -138,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:: @@ -181,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 @@ -189,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 @@ -265,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 @@ -273,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). @@ -294,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 `-` @@ -339,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 @@ -424,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 8714dfc..624a6e6 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,21 +9,24 @@ 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>] + [--empty=(stop|drop|keep)] [(<mbox> | <Maildir>)...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)]) +'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty) 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 ------- @@ -63,6 +66,20 @@ OPTIONS --quoted-cr=<action>:: This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]). +--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:: Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]), @@ -83,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 @@ -103,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>:: @@ -120,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 @@ -178,6 +201,8 @@ default. You can use `--no-utf8` to override this. --abort:: Restore the original branch and abort the patching operation. + Revert the contents of files involved in the am operation to their + pre-am state. --quit:: Abort the patching operation but keep HEAD and the index @@ -189,6 +214,11 @@ default. You can use `--no-utf8` to override this. the e-mail message; if `diff`, show the diff portion only. Defaults to `raw`. +--allow-empty:: + After a patch failure on an input e-mail message lacking a patch, + create an empty commit with the contents of the e-mail message + as its log message. + DISCUSSION ---------- @@ -245,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 aa1ae56..9cce68a 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -16,15 +16,15 @@ SYNOPSIS [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] - [--verbose] [--unsafe-paths] [<patch>...] + [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>...] 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 @@ -228,6 +228,11 @@ behavior: current patch being applied will be printed. This option will cause additional information to be reported. +-q:: +--quiet:: + Suppress stderr output. Messages about patch status and progress + will not be printed. + --recount:: Do not trust the line counts in the hunk headers, but infer them by inspecting the patch (e.g. after editing the patch without @@ -251,16 +256,16 @@ When `git apply` is used as a "better GNU patch", the user can pass 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 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-archimport.txt b/Documentation/git-archimport.txt index a595a0f..847777f 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -9,14 +9,14 @@ git-archimport - Import a GNU Arch repository into Git SYNOPSIS -------- [verse] -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] - <archive/branch>[:<git-branch>] ... +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>] + <archive>/<branch>[:<git-branch>]... DESCRIPTION ----------- Imports a project from one or more GNU Arch repositories. It will follow branches -and repositories within the namespaces defined by the <archive/branch> +and repositories within the namespaces defined by the <archive>/<branch> parameters supplied. If it cannot find the remote branch a merge comes from it will just import it as a regular commit. If it can find it, it will mark it as a merge whenever possible (see discussion below). @@ -27,7 +27,7 @@ import new branches within the provided roots. It expects to be dealing with one project only. If it sees branches that have different roots, it will refuse to run. In that case, -edit your <archive/branch> parameters to define clearly the scope of the +edit your <archive>/<branch> parameters to define clearly the scope of the import. 'git archimport' uses `tla` extensively in the background to access the @@ -42,7 +42,7 @@ incremental imports. While 'git archimport' will try to create sensible branch names for the archives that it imports, it is also possible to specify Git branch names -manually. To do so, write a Git branch name after each <archive/branch> +manually. To do so, write a Git branch name after each <archive>/<branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to Git jargon, for example mapping a "PROJECT{litdd}devo{litdd}VERSION" branch to "master". @@ -104,8 +104,8 @@ OPTIONS Override the default tempdir. -<archive/branch>:: - Archive/branch identifier in a format that `tla log` understands. +<archive>/<branch>:: + <archive>/<branch> identifier in a format that `tla log` understands. GIT diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 9f81728..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:: @@ -49,7 +51,9 @@ OPTIONS Report progress to stderr. --prefix=<prefix>/:: - Prepend <prefix>/ to each filename in the archive. + Prepend <prefix>/ to paths in the archive. Can be repeated; its + rightmost value is used for all tracked files. See below which + value gets used by `--add-file` and `--add-virtual-file`. -o <file>:: --output=<file>:: @@ -57,14 +61,36 @@ OPTIONS --add-file=<file>:: Add a non-tracked file to the archive. Can be repeated to add + multiple files. The path of the file in the archive is built by + concatenating the value of the last `--prefix` option (if any) + before this `--add-file` and the basename of <file>. + +--add-virtual-file=<path>:<content>:: + Add the specified contents to the archive. Can be repeated to add multiple files. The path of the file in the archive is built - by concatenating the value for `--prefix` (if any) and the - basename of <file>. + by concatenating the value of the last `--prefix` option (if any) + before this `--add-virtual-file` and `<path>`. ++ +The `<path>` argument can start and end with a literal double-quote +character; the contained file name is interpreted as a C-style string, +i.e. the backslash is interpreted as escape character. The path must +be quoted if it contains a colon, to avoid the colon from being +misinterpreted as the separator between the path and the contents, or +if the path begins or ends with a double-quote character. ++ +The file mode is limited to a regular file, and the option may be +subject to platform-dependent command-line limits. For non-trivial +cases, write an untracked file and use `--add-file` instead. --worktree-attributes:: 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. @@ -93,12 +119,19 @@ BACKEND EXTRA OPTIONS zip ~~~ --0:: - Store the files instead of deflating them. --9:: - Highest and slowest compression level. You can specify any - number from 1 to 9 to adjust compression speed and ratio. +-<digit>:: + Specify compression level. Larger values allow the command + to spend more time to compress to smaller size. Supported + values are from `-0` (store-only) to `-9` (best ratio). + Default is `-6` if not given. +tar +~~~ +-<number>:: + Specify compression level. The value will be passed to the + compression command configured in `tar.<format>.command`. See + manual page of the configured command for the list of supported + levels and the default level if this option isn't specified. CONFIGURATION ------------- @@ -117,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]] @@ -187,6 +219,12 @@ EXAMPLES commit on the current branch. Note that the output format is inferred by the extension of the output file. +`git archive -o latest.tar --prefix=build/ --add-file=configure --prefix= HEAD`:: + + Creates a tar archive that contains the contents of the latest + commit on the current branch with no prefix and the untracked + file 'configure' with the prefix 'build/'. + `git config tar.tar.xz.command "xz -c"`:: Configure a "tar.xz" format for making LZMA-compressed tarfiles. 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 3bf5d5d..b1d7fb5 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -11,8 +11,8 @@ SYNOPSIS 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--ignore-rev <rev>] [--ignore-revs-file <file>] - [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>] - [--] <file> + [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>] + [ --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. @@ -93,6 +93,19 @@ include::blame-options.txt[] is used for a caret to mark the boundary commit. +THE DEFAULT FORMAT +------------------ + +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 the author name and date, unless `-s` or `-e` + is specified); and +- line number + +before the line contents. + THE PORCELAIN FORMAT -------------------- @@ -115,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. @@ -157,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 @@ -197,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. @@ -228,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 94dc9a5..0b08442 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -16,7 +16,8 @@ SYNOPSIS [--points-at <object>] [--format=<format>] [(-r | --remotes) | (-a | --all)] [--list] [<pattern>...] -'git branch' [--track | --no-track] [-f] <branchname> [<start-point>] +'git branch' [--track[=(direct|inherit)] | --no-track] [-f] + [--recurse-submodules] <branchname> [<start-point>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> @@ -115,23 +116,28 @@ 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. In combination with + 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:: - Move/rename a branch and the corresponding reflog. + Move/rename a branch, together with its config and reflog. -M:: Shortcut for `--move --force`. -c:: --copy:: - Copy a branch and the corresponding reflog. + Copy a branch, together with its config and reflog. -C:: Shortcut for `--copy --force`. @@ -150,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 @@ -205,24 +215,54 @@ This option is only applicable in non-verbose mode. Display the full sha1s in the output listing rather than abbreviating them. -t:: ---track:: +--track[=(direct|inherit)]:: When creating a new branch, set up `branch.<name>.remote` and - `branch.<name>.merge` configuration entries to mark the - start-point branch as "upstream" from the new branch. This + `branch.<name>.merge` configuration entries to set "upstream" tracking + configuration for the new branch. This configuration will tell git to show the relationship between the two branches in `git status` and `git branch -v`. Furthermore, it directs `git pull` without arguments to pull from the upstream when the new branch is checked out. + -This behavior is the default when the start point is a remote-tracking branch. -Set the branch.autoSetupMerge configuration variable to `false` if you -want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track` -were given. Set it to `always` if you want this behavior when the -start-point is either a local or remote-tracking branch. +The exact upstream branch is chosen depending on the optional argument: +`-t`, `--track`, or `--track=direct` means to use the start-point branch +itself as the upstream; `--track=inherit` means to copy the upstream +configuration of the start-point branch. ++ +The branch.autoSetupMerge configuration variable specifies how `git switch`, +`git checkout` and `git branch` should behave when neither `--track` nor +`--no-track` are specified: ++ +The default option, `true`, behaves as though `--track=direct` +were given whenever the start-point is a remote-tracking branch. +`false` behaves as if `--no-track` were given. `always` behaves as though +`--track=direct` were given. `inherit` behaves as though `--track=inherit` +were given. `simple` behaves as though `--track=direct` were given only when +the start-point is a remote-tracking branch and the new branch has the same +name as the remote branch. ++ +See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on +how the `branch.<name>.remote` and `branch.<name>.merge` options are used. --no-track:: Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is true. + branch.autoSetupMerge configuration variable is set. + +--recurse-submodules:: + THIS OPTION IS EXPERIMENTAL! Causes the current command to + recurse into submodules if `submodule.propagateBranches` is + enabled. See `submodule.propagateBranches` in + linkgit:git-config[1]. Currently, only branch creation is + supported. ++ +When used in branch creation, a new branch <branchname> will be created +in the superproject and all of the submodules in the superproject's +<start-point>. In submodules, the branch will point to the submodule +commit in the superproject's <start-point> but the branch's tracking +information will be set up based on the submodule's branches and remotes +e.g. `git branch --recurse-submodules topic origin/main` will create the +submodule branch "topic" that points to the submodule commit in the +superproject's "origin/main", but tracks the submodule's "origin/main". --set-upstream:: As this option had confusing syntax, it is no longer supported. @@ -272,7 +312,8 @@ start-point is either a local or remote-tracking branch. 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 @@ -284,7 +325,7 @@ start-point is either a local or remote-tracking branch. 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]. @@ -304,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 66e88c2..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 @@ -40,14 +47,30 @@ OPTIONS ------- -o <path>:: --output-directory <path>:: - Place the resulting bug report file in `<path>` instead of the root of - the Git repository. + Place the resulting bug report file in `<path>` instead of the current + directory. -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 53804ca..3ab42a1 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,30 +9,55 @@ 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>...] -'git bundle' unbundle <file> [<refname>...] +'git bundle' unbundle [--progress] <file> [<refname>...] DESCRIPTION ----------- -Some workflows require that one or more branches of development on one -machine be replicated on another machine, but the two machines cannot -be directly connected, and therefore the interactive Git protocols (git, -ssh, http) cannot be used. +Create, unpack, and manipulate "bundle" files. Bundles are used for +the "offline" transfer of Git objects without an active "server" +sitting on the other side of the network connection. -The 'git bundle' command packages objects and references in an archive -at the originating machine, which can then be imported into another -repository using 'git fetch', 'git pull', or 'git clone', -after moving the archive by some means (e.g., by sneakernet). +They can be used to create both incremental and full backups of a +repository, and to relay the state of the references in one repository +to another. -As no -direct connection between the repositories exists, the user must specify a -basis for the bundle that is held by the destination repository: the -bundle assumes that all objects in the basis are already in the -destination repository. +Git commands that fetch or otherwise "read" via protocols such as +`ssh://` and `https://` can also operate on bundle files. It is +possible linkgit:git-clone[1] a new repository from a bundle, to use +linkgit:git-fetch[1] to fetch from one, and to list the references +contained within it with linkgit:git-ls-remote[1]. There's no +corresponding "write" support, i.e.a 'git push' into a bundle is not +supported. + +See the "EXAMPLES" section below for examples of how to use bundles. + +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 packed archive format itself bundles can either be +self-contained, or be created using exclusions. +See the "OBJECT PREREQUISITES" section below. + +Bundles created using revision exclusions are "thin packs" created +using the `--thin` option to linkgit:git-pack-objects[1], and +unbundled using the `--fix-thin` option to linkgit:git-index-pack[1]. + +There is no option to create a "thick pack" when using revision +exclusions, and users should not be concerned about the difference. By +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 linkgit:gitformat-bundle[5] for more details and the discussion of +"thin pack" in linkgit:gitformat-pack[5] for further details. OPTIONS ------- @@ -41,20 +66,24 @@ 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 cleanly to the current repository. This includes checks on the bundle format itself as well as checking that the prerequisite commits exist and are fully linked in the current repository. - 'git bundle' prints a list of missing commits, if any, and exits - with a non-zero status. + 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 linkgit:gitformat-bundle[5] + for more information. The exit code is zero for success, but will + 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' @@ -62,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 @@ -87,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 @@ -117,28 +131,88 @@ unbundle <file>:: SPECIFYING REFERENCES --------------------- -'git bundle' will only package references that are shown by -'git show-ref': this includes heads, tags, and remote heads. References -such as `master~1` cannot be packaged, but are perfectly suitable for -defining the basis. More than one reference may be packaged, and more -than one basis can be specified. The objects packaged are those not -contained in the union of the given bases. Each basis can be -specified explicitly (e.g. `^master~10`), or implicitly (e.g. -`master~10..master`, `--since=10.days.ago master`). +Revisions must be accompanied by reference names to be packaged in a +bundle. + +More than one reference may be packaged, and more than one set of prerequisite objects can +be specified. The objects packaged are those not contained in the +union of the prerequisites. + +The 'git bundle create' command resolves the reference names for you +using the same rules as `git rev-parse --abbrev-ref=loose`. Each +prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly +(e.g. `master~10..master`, `--since=10.days.ago master`). + +All of these simple cases are OK (assuming we have a "master" and +"next" branch): + +---------------- +$ git bundle create master.bundle master +$ echo master | git bundle create master.bundle --stdin +$ git bundle create master-and-next.bundle master next +$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin +---------------- + +And so are these (and the same but omitted `--stdin` examples): + +---------------- +$ git bundle create recent-master.bundle master~10..master +$ git bundle create recent-updates.bundle master~10..master next~5..next +---------------- + +A revision name or a range whose right-hand-side cannot be resolved to +a reference is not accepted: + +---------------- +$ git bundle create HEAD.bundle $(git rev-parse HEAD) +fatal: Refusing to create empty bundle. +$ git bundle create master-yesterday.bundle master~10..master~5 +fatal: Refusing to create empty bundle. +---------------- + +OBJECT PREREQUISITES +-------------------- + +When creating bundles it is possible to create a self-contained bundle +that can be unbundled in a repository with no common history, as well +as providing negative revisions to exclude objects needed in the +earlier parts of the history. + +Feeding a revision such as `new` to `git bundle create` will create a +bundle file that contains all the objects reachable from the revision +`new`. That bundle can be unbundled in any repository to obtain a full +history that leads to the revision `new`: + +---------------- +$ git bundle create full.bundle new +---------------- + +A revision range such as `old..new` will produce a bundle file that +will require the revision `old` (and any objects reachable from it) +to exist for the bundle to be "unbundle"-able: + +---------------- +$ git bundle create full.bundle old..new +---------------- + +A self-contained bundle without any prerequisites can be extracted +into anywhere, even into an empty repository, or be cloned from +(i.e., `new`, but not `old..new`). -It is very important that the basis used be held by the destination. It is okay to err on the side of caution, causing the bundle file to contain objects already in the destination, as these are ignored when unpacking at the destination. -`git clone` can use any bundle created without negative refspecs -(e.g., `new`, but not `old..new`). If you want to match `git clone --mirror`, which would include your refs such as `refs/remotes/*`, use `--all`. If you want to provide the same set of refs that a clone directly from the source repository would get, use `--branches --tags` for the `<git-rev-list-args>`. +The 'git bundle verify' command can be used to check whether your +recipient repository has the required prerequisite commits for a +bundle. + EXAMPLES -------- @@ -149,7 +223,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1. To bootstrap the process, you can first create a bundle that does not have -any basis. You can use a tag to remember up to what commit you last +any prerequisites. You can use a tag to remember up to what commit you last processed, in order to make it easy to later update the other repository with an incremental bundle: @@ -200,7 +274,7 @@ machineB$ git pull If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the -basis, giving a cut-off point to limit the revisions and objects that go +prerequisites, giving a cut-off point to limit the revisions and objects that go in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the linkgit:git-log[1] command. Here are more examples: @@ -211,7 +285,7 @@ You can use a tag that is present in both: $ git bundle create mybundle v1.0.0..master ---------------- -You can use a basis based on time: +You can use a prerequisite based on time: ---------------- $ git bundle create mybundle --since=10.days master @@ -224,7 +298,7 @@ $ git bundle create mybundle -10 master ---------------- You can run `git-bundle verify` to see if you can extract from a bundle -that was created with a basis: +that was created with a prerequisite: ---------------- $ git bundle verify mybundle @@ -247,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 4eb0421..bd95a6c 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -3,28 +3,32 @@ 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 -------- [verse] -'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object> -'git cat-file' (--batch[=<format>] | --batch-check[=<format>]) [ --textconv | --filters ] [--follow-symlinks] +'git cat-file' <type> <object> +'git cat-file' (-e | -p) <object> +'git cat-file' (-t | -s) [--allow-unknown-type] <object> +'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 ------- @@ -39,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. @@ -57,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 @@ -77,32 +89,89 @@ 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`, `--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: ++ +-- +contents <object>:: + Print object contents for object reference `<object>`. This corresponds to + the output of `--batch`. + +info <object>:: + Print object info for object reference `<object>`. This corresponds to the + output of `--batch-check`. + +flush:: + Used with `--buffer` to execute all preceding commands that were issued + since the beginning or since the last flush was issued. When `--buffer` + is used, no output will come until a `flush` is issued. When `--buffer` + is not used, commands are flushed each time without issuing `flush`. +-- ++ --batch-all-objects:: Instead of reading a list of objects on stdin, perform the requested batch operation on all objects in the repository and any alternate object stores (not just reachable objects). - Requires `--batch` or `--batch-check` be specified. Note that - the objects are visited in order sorted by their hashes. + Requires `--batch` or `--batch-check` be specified. By default, + the objects are visited in order sorted by their hashes; see + also `--unordered` below. Objects are presented as-is, without + respecting the "replace" mechanism of linkgit:git-replace[1]. --buffer:: Normally batch output is flushed after each object is output, so that a process can interactively read and write from `cat-file`. With this option, the output uses normal stdio buffering; this is much more efficient when invoking - `--batch-check` on a large number of objects. + `--batch-check` or `--batch-command` on a large number of objects. --unordered:: When `--batch-all-objects` is in use, visit objects in an @@ -172,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 ------ @@ -194,6 +274,13 @@ from stdin, one per line, and print information about them. By default, the whole line is considered as an object, as if it were fed to linkgit:git-rev-parse[1]. +When `--batch-command` is given, `cat-file` will read commands from stdin, +one per line, and print information based on the command given. With +`--batch-command`, the `info` command followed by an object will print +information about the object the same way `--batch-check` would, and the +`contents` command followed by an object prints contents in the same way +`--batch` would. + You can specify the information shown for each object by using a custom `<format>`. The `<format>` is copied literally to stdout for each object, with placeholders of the form `%(atom)` expanded, followed by a @@ -229,9 +316,9 @@ newline. The available atoms are: If no format is specified, the default format is `%(objectname) %(objecttype) %(objectsize)`. -If `--batch` is specified, the object information is followed by the -object contents (consisting of `%(objectsize)` bytes), followed by a -newline. +If `--batch` is specified, or if `--batch-command` is used with the `contents` +command, the object information is followed by the object contents (consisting +of `%(objectsize)` bytes), followed by a newline. For example, `--batch` without a custom format would produce: @@ -301,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 0c3924a..3e3b4e3 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -33,7 +33,7 @@ OPTIONS Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually - means the path is excluded, but if the pattern begins with '!' + means the path is excluded, but if the pattern begins with "`!`" then it is a negated pattern and matching it means the path is NOT excluded.) + @@ -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. @@ -77,7 +77,7 @@ If `--verbose` is specified, the output is a series of lines of the form: <pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern's source file, and <linenum> is the line number of the pattern within that source. If the pattern -contained a `!` prefix or `/` suffix, it will be preserved in the +contained a "`!`" prefix or "`/`" suffix, it will be preserved in the output. <source> will be an absolute path when referring to the file configured by `core.excludesFile`, or relative to the repository root when referring to `.git/info/exclude` or a per-directory exclude file. 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 4d33e7b..faf8d6c 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -12,12 +12,13 @@ SYNOPSIS 'git checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] [--stage=<number>|all] [--temp] + [--ignore-skip-worktree-bits] [-z] [--stdin] [--] [<file>...] 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 @@ -37,8 +38,9 @@ OPTIONS -a:: --all:: - checks out all files in the index. Cannot be used - together with explicit filenames. + checks out all files in the index except for those with the + skip-worktree bit set (see `--ignore-skip-worktree-bits`). + Cannot be used together with explicit filenames. -n:: --no-create:: @@ -51,17 +53,21 @@ 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. +--ignore-skip-worktree-bits:: + Check out all files, including those with the skip-worktree bit + 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 b1a6fe4..8bdfa54 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -11,9 +11,11 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] [<branch>] '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' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] +'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,9 +43,9 @@ $ 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>]:: +'git checkout' -b|-B <new-branch> [<start-point>]:: Specifying `-b` causes a new branch to be created as if linkgit:git-branch[1] were called and then checked out. In @@ -52,16 +54,18 @@ if exists, for the current branch. `--track` without `-b` implies branch creation; see the description of `--track` below. + -If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it +If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of + ------------ -$ git branch -f <branch> [<start point>] +$ git branch -f <branch> [<start-point>] $ 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>:: @@ -118,8 +122,9 @@ OPTIONS -f:: --force:: When switching branches, proceed even if the index or the - working tree differs from `HEAD`. This is used to throw away - local changes. + working tree differs from `HEAD`, and even if there are untracked + files in the way. This is used to throw away local changes and + any untracked files or directories that are in the way. + When checking out paths from the index, do not fail upon unmerged entries; instead, unmerged entries are ignored. @@ -144,18 +149,20 @@ as `ours` (i.e. "our shared canonical history"), while what you did 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. +-b <new-branch>:: + 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. +-B <new-branch>:: + 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:: +--track[=(direct|inherit)]:: When creating a new branch, set up "upstream" configuration. See "--track" in linkgit:git-branch[1] for details. + @@ -209,16 +216,16 @@ variable. `<commit>` is not a branch name. See the "DETACHED HEAD" section below for details. ---orphan <new_branch>:: - Create a new 'orphan' branch, named `<new_branch>`, started from - `<start_point>` and switch to it. The first commit made on this +--orphan <new-branch>:: + 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 commits. + The index and the working tree are adjusted as if you had previously run -`git checkout <start_point>`. This allows you to start a new history -that records a set of paths similar to `<start_point>` by easily running +`git checkout <start-point>`. This allows you to start a new history +that records a set of paths similar to `<start-point>` by easily running `git commit -a` to make the root commit. + This can be useful when you want to publish the tree from a commit @@ -228,7 +235,7 @@ whose full history contains proprietary or otherwise encumbered bits of code. + If you want to start a disconnected history that records a set of paths -that is totally different from the one of `<start_point>`, then you should +that is totally different from the one of `<start-point>`, then you should clear the index and the working tree right after creating the orphan branch by running `git rm -rf .` from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the @@ -257,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. @@ -265,8 +273,7 @@ When switching branches with `--merge`, staged changes may be lost. The same as `--merge` option above, but changes the way the conflicting hunks are presented, overriding the `merge.conflictStyle` configuration variable. Possible values are - "merge" (default) and "diff3" (in addition to what is shown by - "merge" style, shows the original contents). + "merge" (default), "diff3", and "zdiff3". -p:: --patch:: @@ -340,10 +347,10 @@ As a special case, you may use `A...B` as a shortcut for the merge base of `A` and `B` if there is exactly one merge base. You can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. -<new_branch>:: +<new-branch>:: Name for the new branch. -<start_point>:: +<start-point>:: The name of a commit at which to start the new branch; see linkgit:git-branch[1] for details. Defaults to `HEAD`. + @@ -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 5d75031..81ace90 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- [verse] -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] +'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff] [-S[<keyid>]] <commit>... 'git cherry-pick' (--continue | --skip | --abort | --quit) @@ -81,8 +81,8 @@ OPTIONS described above, and `-r` was to disable it. Now the default is not to do `-x` so this option is a no-op. --m parent-number:: ---mainline parent-number:: +-m <parent-number>:: +--mainline <parent-number>:: Usually you cannot cherry-pick a merge because you do not know which side of the merge should be considered the mainline. This option specifies the parent number (starting from 1) of @@ -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 3fe3810..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>] [--] <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,23 +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:: - Initialize the sparse-checkout file so the working - directory starts with only the files in the root - of the repository. The sparse-checkout file can be - modified to grow the working directory as needed. +`--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]. ---mirror:: +`--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`:: 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 @@ -190,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 @@ -229,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 @@ -269,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 @@ -285,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[] @@ -358,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 f58e9c4..1843164 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -39,7 +39,7 @@ OPTIONS --indent=<string>:: String to be printed at the beginning of each line. ---nl=<N>:: +--nl=<string>:: String to be printed at the end of each line, including newline character. @@ -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 95fec5f..89ecfc6 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -212,8 +212,9 @@ include::signoff-option.txt[] each trailer would appear, and other details. -n:: ---no-verify:: - This option bypasses the pre-commit and commit-msg hooks. +--[no-]verify:: + By default, the pre-commit and commit-msg hooks are run. + When any of `--no-verify` or `-n` is given, these are bypassed. See also linkgit:githooks[5]. --allow-empty:: @@ -346,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]. -- @@ -540,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. @@ -556,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 5cddada..ac61113 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,20 +9,20 @@ 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>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern] -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL -'git config' [<file-option>] [--fixed-value] --unset name [value-pattern] -'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern] -'git config' [<file-option>] --rename-section old_name new_name -'git config' [<file-option>] --remove-section name +'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]] +'git config' [<file-option>] [--type=<type>] [--comment=<message>] --add <name> <value> +'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] --replace-all <name> <value> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL> +'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>] +'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>] +'git config' [<file-option>] --rename-section <old-name> <new-name> +'git config' [<file-option>] --remove-section <name> 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [<file-option>] --get-color name [default] -'git config' [<file-option>] --get-colorbool name [stdout-is-tty] +'git config' [<file-option>] --get-color <name> [<default>] +'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>] 'git config' [<file-option>] -e | --edit DESCRIPTION @@ -71,6 +71,10 @@ codes are: On success, the command returns the exit code 0. +A list of all available configuration variables can be obtained using the +`git help --config` command. + +[[OPTIONS]] OPTIONS ------- @@ -83,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 @@ -98,12 +114,12 @@ OPTIONS in which section and variable names are lowercased, but subsection 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 +--get-urlmatch <name> <URL>:: + When given a two-part <name> as <section>.<key>, the value for + <section>.<URL>.<key> whose <URL> part matches the best to the given URL is returned (if no such key exists, the value for - 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:: @@ -137,15 +153,25 @@ from all available files. See also <<FILES>>. --worktree:: - Similar to `--local` except that `.git/config.worktree` is + Similar to `--local` except that `$GIT_DIR/config.worktree` is read from or written to if `extensions.worktreeConfig` is - present. If not it's the same as `--local`. - --f config-file:: ---file config-file:: - Use the given config file instead of the one specified by GIT_CONFIG. + enabled. If not it's the same as `--local`. Note that `$GIT_DIR` + is equal to `$GIT_COMMON_DIR` for the main working tree, but is of + the form `$GIT_DIR/worktrees/<id>/` for other working trees. See + linkgit:git-worktree[1] to learn how to enable + `extensions.worktreeConfig`. + +-f <config-file>:: +--file <config-file>:: + For writing options: write to the specified file rather than the + repository `.git/config`. ++ +For reading options: read only from the specified file rather than from all +available files. ++ +See also <<FILES>>. ---blob blob:: +--blob <blob>:: Similar to `--file` but use the given blob instead of a file. E.g. you can use 'master:.gitmodules' to read values from the file '.gitmodules' in the master branch. See "SPECIFYING REVISIONS" @@ -187,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.) @@ -234,20 +260,20 @@ Valid `<type>`'s include: --show-scope:: Similar to `--show-origin` in that it augments the output of all queried config options with the scope of that value - (local, global, system, command). + (worktree, local, global, system, command). ---get-colorbool name [stdout-is-tty]:: +--get-colorbool <name> [<stdout-is-tty>]:: - Find the color setting for `name` (e.g. `color.diff`) and output - "true" or "false". `stdout-is-tty` should be either "true" or + Find the color setting for `<name>` (e.g. `color.diff`) and output + "true" or "false". `<stdout-is-tty>` should be either "true" or "false", and is taken into account when configuration says - "auto". If `stdout-is-tty` is missing, then checks the standard + "auto". If `<stdout-is-tty>` is missing, then checks the standard output of the command itself, and exits with status 0 if color is to be used, or exits with status 1 otherwise. When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color name [default]:: +--get-color <name> [<default>]:: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard @@ -261,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 @@ -271,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 ------------- @@ -283,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. @@ -308,38 +332,83 @@ $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 either by command-line options or by environment -variables. The `--global`, `--system` and `--worktree` options will limit -the file used to the global, system-wide or per-worktree file respectively. -The `GIT_CONFIG` environment variable has a similar effect, but you -can specify any filename you want. +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 ----------- -GIT_CONFIG:: - Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. Using the - "--system" option forces this to $(prefix)/etc/gitconfig. - GIT_CONFIG_GLOBAL:: GIT_CONFIG_SYSTEM:: Take the configuration from the given files instead from global or @@ -367,6 +436,12 @@ This is useful for cases where you want to spawn multiple git commands with a common configuration but cannot depend on a configuration file, for example when writing scripts. +GIT_CONFIG:: + If no `--file` option is provided to `git config`, use the file + given by `GIT_CONFIG` as if it were provided via `--file`. This + variable has no effect on other Git commands, and is mostly for + historical compatibility; there is generally no reason to use it + instead of the `--file` option. [[EXAMPLES]] EXAMPLES 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 7051c6b..650a15a 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -1,5 +1,5 @@ -git-credential-cache--daemon(1) -=============================== +git-credential-cache{litdd}daemon(1) +==================================== NAME ---- @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- [verse] -git credential-cache--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 206e3c5..918a0aa 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -git credential <fill|approve|reject> +'git credential' (fill|approve|reject) ------------------ DESCRIPTION @@ -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-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 00154b6..41c8a8a 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- [verse] -'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] - [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>] + [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id> DESCRIPTION diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index de1ebed..90fdc25 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -11,9 +11,9 @@ SYNOPSIS [verse] 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] - [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] - [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [-r <remote>] [-R] [<CVS_module>] + [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] + [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>] + [-r <remote>] [-R] [<CVS-module>] DESCRIPTION @@ -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. @@ -59,7 +59,7 @@ OPTIONS from `CVS/Root`. If no such file exists, it checks for the `CVSROOT` environment variable. -<CVS_module>:: +<CVS-module>:: The CVS module you want to import. Relative to <CVSROOT>. If not given, 'git cvsimport' tries to read it from `CVS/Repository`. @@ -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 f2e4a47..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 ----------- @@ -99,7 +98,7 @@ looks like ------ -Only anonymous access is provided by pserve by default. To commit you +Only anonymous access is provided by pserver by default. To commit you will have to create pserver accounts, simply add a gitcvs.authdb setting in the config file of the repositories you want the cvsserver to allow writes to, for example: @@ -114,21 +113,20 @@ The format of these files is username followed by the encrypted password, for example: ------ - myuser:$1Oyx5r9mdGZ2 - myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./ + myuser:sqkNi8zPf01HI + myuser:$1$9K7FzU28$VfF6EoPYCJEYcVQwATgOP/ + myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3 ------ You can use the 'htpasswd' facility that comes with Apache to make these -files, but Apache's MD5 crypt method differs from the one used by most C -library's crypt() function, so don't use the -m option. +files, but only with the -d option (or -B if your system supports it). -Alternatively you can produce the password with perl's crypt() operator: ------ - perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password ------ +Preferably use the system specific utility that manages password hash +creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or +pwhash in NetBSD) and paste it in the right location. Then provide your password via the pserver method, for example: ------ - cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name> + cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name> ------ No special setup is needed for SSH access, other than having Git tools in the PATH. If you have clients that do not accept the CVS_SERVER @@ -138,7 +136,7 @@ Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like ------ -cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> + cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> ------ This has the advantage that it will be saved in your 'CVS/Root' files and you don't need to worry about always setting the correct environment @@ -186,8 +184,8 @@ allowing access over SSH. + -- ------ - export CVSROOT=:ext:user@server:/var/git/project.git - export CVS_SERVER="git cvsserver" + export CVSROOT=:ext:user@server:/var/git/project.git + export CVS_SERVER="git cvsserver" ------ -- 4. For SSH clients that will make commits, make sure their server-side @@ -199,11 +197,11 @@ 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: + ------ - cvs co -d project-master master + cvs co -d project-master master ------ [[dbbackend]] @@ -226,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 @@ -312,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 906774f..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 27acb31..4de1d4c 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -9,14 +9,14 @@ git-diff-index - Compare a tree to the working tree or index SYNOPSIS -------- [verse] -'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...] +'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...] 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 2fc24c5..143318c 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -11,11 +11,11 @@ SYNOPSIS [verse] 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base] - [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] + [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...] 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 7f4c8a8..c065f02 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -51,16 +51,20 @@ files on disk. --staged is a synonym of --cached. + If --merge-base is given, instead of using <commit>, use the merge base -of <commit> and HEAD. `git diff --merge-base A` is equivalent to -`git diff $(git merge-base A HEAD)`. +of <commit> and HEAD. `git diff --cached --merge-base A` is equivalent to +`git diff --cached $(git merge-base A HEAD)`. -'git diff' [<options>] <commit> [--] [<path>...]:: +'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]:: This form is to view the changes you have in your working tree relative to the named <commit>. You can use HEAD to compare it with the latest commit, or a branch name to compare with the tip of a different branch. ++ +If --merge-base is given, instead of using <commit>, use the merge base +of <commit> and HEAD. `git diff --merge-base A` is equivalent to +`git diff $(git merge-base A HEAD)`. 'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]:: @@ -75,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>...]:: @@ -98,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]. @@ -148,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. @@ -155,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:: + @@ -209,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 c975884..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 @@ -101,6 +101,10 @@ be in a separate packet, and the list must end with a flush packet. current shallow boundary instead of from the tip of each remote branch history. +--refetch:: + Skips negotiating commits with the server in order to fetch all matching + objects. Use to reapply a new partial clone blob/tree filter. + --no-progress:: Do not show the progress. diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 9067c20..50900a5 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -133,7 +133,7 @@ remember to run that, set `fetch.prune` globally, or linkgit:git-config[1]. Here's where things get tricky and more specific. The pruning feature -doesn't actually care about branches, instead it'll prune local <-> +doesn't actually care about branches, instead it'll prune local <--> remote-references as a function of the refspec of the remote (see `<refspec>` and <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> above). @@ -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,14 +294,19 @@ 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 already checked -out submodules right now. When e.g. upstream added a new submodule in the -just fetched commits of the superproject the submodule itself cannot be -fetched, making it impossible to check out that submodule later without -having to do a fetch again. This is expected to be fixed in a future Git -version. +Using --recurse-submodules can only fetch new commits in submodules that are +present locally e.g. in `$GIT_DIR/modules/`. If the upstream adds a new +submodule, that submodule cannot be fetched until it is cloned e.g. by `git +submodule update`. This is expected to be fixed in a future Git version. SEE ALSO -------- 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-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 6793d8f..6f28812 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,7 +9,7 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] +'git fmt-merge-msg' [-m <message>] [--into-name <branch>] [--log[=<n>] | --no-log] 'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file> DESCRIPTION @@ -44,6 +44,10 @@ OPTIONS Use <message> instead of the branch names for the first line of the log message. For use with `--log`. +--into-name <branch>:: + Prepare the merge message as if merging to the branch `<branch>`, + instead of the name of the real branch to which the merge is made. + -F <file>:: --file <file>:: Take the list of merged objects from <file> instead of diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 2ae2478..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,29 @@ 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`. + +raw:size:: + The raw data size of the object. + +Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, +because such language may not support arbitrary binary data in their string +variable type. The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: @@ -275,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 fe2f69d..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>] - [--ignore-if-in-upstream] + [--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:: @@ -192,6 +191,10 @@ will want to ensure that threading is disabled for `git send-email`. patches being generated, and any patch that matches is ignored. +--always:: + Include patches for commits that do not introduce any change, + which are omitted by default. + --cover-from-description=<mode>:: Controls which parts of the cover letter will be automatically populated using the branch's description. @@ -212,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 @@ -226,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>:: @@ -242,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 @@ -271,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. @@ -379,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 @@ -586,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. @@ -689,10 +713,10 @@ You can also use `git format-patch --base=P -3 C` to generate patches for A, B and C, and the identifiers for P, X, Y, Z are appended at the end of the first message. -If set `--base=auto` in cmdline, it will track base commit automatically, -the base commit will be the merge base of tip commit of the remote-tracking +If set `--base=auto` in cmdline, it will automatically compute +the base commit as the merge base of tip commit of the remote-tracking branch and revision-range specified in cmdline. -For a local branch, you need to track a remote branch by `git branch +For a local branch, you need to make it to track a remote branch by `git branch --set-upstream-to` before using this option. EXAMPLES diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bd59661..5b82e46 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] [--[no-]dangling] [--[no-]progress] [--connectivity-only] - [--[no-]name-objects] [<object>*] + [--[no-]name-objects] [<object>...] DESCRIPTION ----------- @@ -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 new file mode 100644 index 0000000..8585d19 --- /dev/null +++ b/Documentation/git-fsmonitor--daemon.txt @@ -0,0 +1,106 @@ +git-fsmonitor{litdd}daemon(1) +============================= + +NAME +---- +git-fsmonitor--daemon - A Built-in Filesystem Monitor + +SYNOPSIS +-------- +[verse] +'git fsmonitor{litdd}daemon' start +'git fsmonitor{litdd}daemon' run +'git fsmonitor{litdd}daemon' stop +'git fsmonitor{litdd}daemon' status + +DESCRIPTION +----------- + +A daemon to watch the working directory for file and directory +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 +instead of the slower linkgit:githooks[5] interface. + +This daemon is built into Git so that no third-party tools are +required. + +OPTIONS +------- + +start:: + Starts a daemon in the background. + +run:: + Runs a daemon in the foreground. + +stop:: + Stops the daemon running in the current working + directory, if present. + +status:: + Exits with zero status if a daemon is watching the + current working directory. + +REMARKS +------- + +This daemon is a long running process used to watch a single working +directory and maintain a list of the recently changed files and +directories. Performance of commands such as `git status` can be +increased if they just ask for a summary of changes to the working +directory and can avoid scanning the disk. + +When `core.fsmonitor` is set to `true` (see linkgit:git-config[1]) +commands, such as `git status`, will ask the daemon for changes and +automatically start it (if necessary). + +For more information see the "File System Monitor" section in +linkgit:git-update-index[1]. + +CAVEATS +------- + +The fsmonitor daemon does not currently know about submodules and does +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 853967d..b5561c4 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -54,6 +54,18 @@ other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. +--[no-]cruft:: + When expiring unreachable objects, pack them separately into a + 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, overridable by the config variable `gc.pruneExpire`). @@ -73,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 ---------- @@ -106,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-gui.txt b/Documentation/git-gui.txt index c9d7e96..e8f3ccb 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- [verse] -'git gui' [<command>] [arguments] +'git gui' [<command>] [<arguments>] DESCRIPTION ----------- 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 44fe886..f0bedc1 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,13 +8,17 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all [--[no-]verbose]] [-g|--guides] - [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE] +'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] +'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. @@ -24,31 +28,38 @@ 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. If an alias is given, git shows the definition of the alias on standard output. To get the manual page for the aliased command, use -`git COMMAND --help`. +`git <command> --help`. Note that `git --help ...` is identical to `git help ...` because the 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. This - option overrides any given command or guide name. + Print all the available commands on the standard output. + +--no-external-commands:: + When used with `--all`, exclude the listing of external "git-*" + commands found in the `$PATH`. + +--no-aliases:: + When used with `--all`, exclude the listing of configured + 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:: @@ -58,8 +69,24 @@ OPTIONS -g:: --guides:: - Prints a list of the Git concept guides on the standard output. This - option overrides any given command or guide name. + 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:: @@ -82,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. @@ -102,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 new file mode 100644 index 0000000..f6cc72d --- /dev/null +++ b/Documentation/git-hook.txt @@ -0,0 +1,50 @@ +git-hook(1) +=========== + +NAME +---- +git-hook - Run git hooks + +SYNOPSIS +-------- +[verse] +'git hook' run [--ignore-missing] [--to-stdin=<path>] <hook-name> [-- <hook-args>] + +DESCRIPTION +----------- + +A command interface for running git hooks (see linkgit:githooks[5]), +for use by other scripted git commands. + +SUBCOMMANDS +----------- + +run:: + Run the `<hook-name>` hook. See linkgit:githooks[5] for + supported hook names. ++ + +Any positional arguments to the hook should be passed after a +mandatory `--` (or `--end-of-options`, see linkgit:gitcli[7]). See +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 + or may not be present. + +SEE ALSO +-------- +linkgit:githooks[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 558966a..f37ddad 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -16,12 +16,14 @@ A simple CGI program to serve the contents of a Git repository to Git clients accessing the repository over http:// and https:// protocols. The program supports clients fetching using both the smart HTTP protocol and the backwards-compatible dumb HTTP protocol, as well as clients -pushing using the smart HTTP protocol. +pushing using the smart HTTP protocol. It also supports Git's +more-efficient "v2" protocol if properly configured; see the +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 @@ -40,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 @@ -77,6 +79,18 @@ Apache 2.x:: SetEnv GIT_PROJECT_ROOT /var/www/git SetEnv GIT_HTTP_EXPORT_ALL ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ + +# This is not strictly necessary using Apache and a modern version of +# git-http-backend, as the webserver will pass along the header in the +# environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into +# GIT_PROTOCOL. But you may need this line (or something similar if you +# are using a different webserver), or if you want to support older Git +# versions that did not do that copying. +# +# Having the webserver set up GIT_PROTOCOL is perfectly fine even with +# modern versions (and will take precedence over HTTP_GIT_PROTOCOL, +# which means it can be used to override the client's request). +SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0 ---------------------------------------------------------------- + To enable anonymous read access but authenticated write access, @@ -251,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 @@ -264,6 +278,16 @@ a repository with an extremely large number of refs. The value can be specified with a unit (e.g., `100M` for 100 megabytes). The default is 10 megabytes. +Clients may probe for optional protocol capabilities (like the v2 +protocol) using the `Git-Protocol` HTTP header. In order to support +these, the contents of that header must appear in the `GIT_PROTOCOL` +environment variable. Most webservers will pass this header to the CGI +via the `HTTP_GIT_PROTOCOL` variable, and `git-http-backend` will +automatically copy that to `GIT_PROTOCOL`. However, some webservers may +be more selective about which headers they'll pass, in which case they +need to be configured explicitly (see the mention of `Git-Protocol` in +the Apache config from the earlier EXAMPLES section). + The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}', ensuring that any reflogs created by 'git-receive-pack' contain some diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 9fa17b6..4ec7c68 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP SYNOPSIS -------- [verse] -'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url> +'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL> DESCRIPTION ----------- @@ -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 ea03a4e..ce0d808 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -9,16 +9,16 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- [verse] -'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] +'git http-push' [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>...] 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 @@ -63,16 +63,15 @@ 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>'. -Each pattern pair consists of the source side (before the colon) -and the destination side (after the colon). The ref to be -pushed is determined by finding a match that matches the source -side, and where it is pushed is determined by using the -destination side. +Each pattern pair '<src>:<dst>' consists of the source side (before +the colon) and the destination side (after the colon). The ref to be +pushed is determined by finding a match that matches the source side, +and where it is pushed is determined by using the destination side. - - It is an error if <src> does not match exactly one of the + - It is an error if '<src>' does not match exactly one of the local refs. - - If <dst> does not match any remote ref, either + - If '<dst>' does not match any remote ref, either * it has to start with "refs/"; <dst> is used as the destination literally in this case. @@ -84,8 +83,8 @@ 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 7fa74b9..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,19 +79,35 @@ 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. ++ +Set the title of the progress bar. The title is "Receiving objects" by +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 @@ -116,6 +132,14 @@ This option cannot be used with --stdin. + include::object-format-disclaimer.txt[] +--promisor[=<message>]:: + Before committing the pack-index, create a .promisor file for this + pack. Particularly helpful when writing a promisor pack with --fix-thin + since the name of the pack is not final until the pack has been fully + written. If a `<message>` is provided, then that content will be + written to the .promisor file for future reference. See + link:technical/partial-clone.html[partial clone] for more information. + NOTES ----- diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 648a6cd..18bf1a3 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository SYNOPSIS -------- [verse] -'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] +'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]] DESCRIPTION diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index b611d80..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,101 +30,114 @@ 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|0xxx)]:: +++--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. -'0xxx':: +_<perm>_:: -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' 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 that is -readable and writable to the current user and group, but inaccessible to others. +_<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). -- 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 @@ -162,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 0498e7b..5796821 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -9,7 +9,7 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [<options>] [<revision range>] [[--] <path>...] +'git log' [<options>] [<revision-range>] [[--] <path>...] DESCRIPTION ----------- @@ -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 @@ -81,13 +91,13 @@ produced by `--stat`, etc. include::line-range-options.txt[] -<revision range>:: +<revision-range>:: Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to `HEAD` (i.e. the + <revision-range> is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` specifies all the commits reachable from the current commit (i.e. `HEAD`), but not from `origin`. For a complete list of - ways to spell <revision range>, see the 'Specifying Ranges' + ways to spell <revision-range>, see the 'Specifying Ranges' section of linkgit:gitrevisions[7]. [--] <path>...:: @@ -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 6d11ab5..d08c7da 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,9 +10,10 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] [-f] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* - (-[c|d|o|i|s|u|k|m])* - [--eol] + [-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>] [-X <file>|--exclude-from=<file>] @@ -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:: @@ -156,7 +181,7 @@ a space) at the start of each line: --recurse-submodules:: Recursively calls ls-files on each active submodule in the repository. - Currently there is only support for the --cached mode. + Currently there is only support for the --cached and --stage modes. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object @@ -187,6 +212,18 @@ Both the <eolinfo> in the index ("i/<eolinfo>") and in the working tree ("w/<eolinfo>") are shown for regular files, followed by the ("attr/<eolattr>"). +--sparse:: + If the index is sparse, show the sparse directories without expanding + 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. @@ -218,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 ---------------- @@ -227,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 @@ -249,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 db02d6d..6572095 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-tree' [-d] [-r] [-t] [-l] [-z] - [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]] + [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>] <tree-ish> [<path>...] DESCRIPTION @@ -59,6 +59,15 @@ OPTIONS --name-only:: --name-status:: List only filenames (instead of the "long" output), one per line. + Cannot be combined with `--object-only`. + +--object-only:: + List only names of the objects, one per line. Cannot be combined + with `--name-only` or `--name-status`. + This is equivalent to specifying `--format='%(objectname)'`, but + for both this option and that exact format the command takes a + hand-optimized codepath instead of going through the generic + formatting mechanism. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object @@ -74,6 +83,16 @@ OPTIONS Do not limit the listing to the current working directory. Implies --full-name. +--format=<format>:: + A string that interpolates `%(fieldname)` from the result + being shown. It also interpolates `%%` to `%`, and + `%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`. + [<path>...]:: When paths are given, show them (note that this isn't really raw pathnames, but rather a list of patterns to match). Otherwise @@ -82,16 +101,29 @@ OPTIONS Output Format ------------- - <mode> SP <type> SP <object> TAB <file> + +The output format of `ls-tree` is determined by either the `--format` +option, or other format-altering options such as `--name-only` etc. +(see `--format` above). + +The use of certain `--format` directives is equivalent to using those +options, but invoking the full formatting machinery can be slower than +using an appropriate formatting option. + +In cases where the `--format` would exactly map to an existing option +`ls-tree` will use the appropriate faster path. Thus the default format +is equivalent to: + + %(objectmode) %(objecttype) %(objectname)%x09%(path) This output format is compatible with what `--index-info --stdin` of 'git update-index' expects. When the `-l` option is used, format changes to - <mode> SP <type> SP <object> SP <object size> TAB <file> + %(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path) -Object size identified by <object> is given in bytes, and right-justified +Object size identified by <objectname> is given in bytes, and right-justified with minimum width of 7 characters. Object size is given only for blobs (file) entries; for other entries `-` character is used in place of size. @@ -100,6 +132,34 @@ 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. +Customized format: + +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-tree --format='%(objectname) %(path)' <tree-ish> + +FIELD NAMES +----------- + +Various values from structured fields can be used to interpolate +into the resulting output. For each outputting line, the following +names can be used: + +objectmode:: + The mode of the object. +objecttype:: + The type of the object (`commit`, `blob` or `tree`). +objectname:: + The name of the object. +objectsize[:padded]:: + The size of a `blob` object ("-" if it's a `commit` or `tree`). + It also supports a padded format of size with "%(objectsize:padded)". +path:: + The pathname of the object. + GIT --- Part of the linkgit:git[1] suite 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 1e738ad..51d0f7e 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -10,6 +10,8 @@ SYNOPSIS -------- [verse] 'git maintenance' run [<options>] +'git maintenance' start [--scheduler=<scheduler>] +'git maintenance' (stop|register|unregister) [<options>] DESCRIPTION @@ -29,14 +31,32 @@ Git repository. SUBCOMMANDS ----------- +run:: + Run one or more maintenance tasks. If one or more `--task` options + are specified, then those tasks are run in that order. Otherwise, + the tasks are determined by which `maintenance.<task>.enabled` + config options are true. By default, only `maintenance.gc.enabled` + is true. + +start:: + Start running maintenance on the current repository. This performs + the same config updates as the `register` subcommand, then updates + the background scheduler to run `git maintenance run --scheduled` + on an hourly basis. + +stop:: + Halt the background maintenance schedule. The current repository + is not removed from the list of maintained repositories, in case + 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 @@ -55,28 +75,14 @@ task: setting `maintenance.auto = false` in the current repository. This config setting will remain after a `git maintenance unregister` command. -run:: - Run one or more maintenance tasks. If one or more `--task` options - are specified, then those tasks are run in that order. Otherwise, - the tasks are determined by which `maintenance.<task>.enabled` - config options are true. By default, only `maintenance.gc.enabled` - is true. - -start:: - Start running maintenance on the current repository. This performs - the same config updates as the `register` subcommand, then updates - the background scheduler to run `git maintenance run --scheduled` - on an hourly basis. - -stop:: - Halt the background maintenance schedule. The current repository - is not removed from the list of maintained repositories, in case - the background maintenance is restarted later. - 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 ----- @@ -96,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. @@ -179,6 +185,17 @@ OPTIONS `maintenance.<task>.enabled` configured as `true` are considered. See the 'TASKS' section for the list of accepted `<task>` values. +--scheduler=auto|crontab|systemd-timer|launchctl|schtasks:: + When combined with the `start` subcommand, specify the scheduler + for running the hourly, daily and weekly executions of + `git maintenance run`. + Possible values for `<scheduler>` are `auto`, `crontab` + (POSIX), `systemd-timer` (Linux), `launchctl` (macOS), and + `schtasks` (Windows). When `auto` is specified, the + appropriate platform-specific scheduler is used; on Linux, + `systemd-timer` is used if available, otherwise + `crontab`. Default is `auto`. + TROUBLESHOOTING --------------- @@ -277,6 +294,52 @@ schedule to ensure you are executing the correct binaries in your schedule. +BACKGROUND MAINTENANCE ON LINUX SYSTEMD SYSTEMS +----------------------------------------------- + +While Linux supports `cron`, depending on the distribution, `cron` may +be an optional package not necessarily installed. On modern Linux +distributions, systemd timers are superseding it. + +If user systemd timers are available, they will be used as a replacement +of `cron`. + +In this case, `git maintenance start` will create user systemd timer units +and start the timers. The current list of user-scheduled tasks can be found +by running `systemctl --user list-timers`. The timers written by `git +maintenance start` are similar to this: + +----------------------------------------------------------------------- +$ systemctl --user list-timers +NEXT LEFT LAST PASSED UNIT ACTIVATES +Thu 2021-04-29 19:00:00 CEST 42min left Thu 2021-04-29 18:00:11 CEST 17min ago git-maintenance@hourly.timer git-maintenance@hourly.service +Fri 2021-04-30 00:00:00 CEST 5h 42min left Thu 2021-04-29 00:00:11 CEST 18h ago git-maintenance@daily.timer git-maintenance@daily.service +Mon 2021-05-03 00:00:00 CEST 3 days left Mon 2021-04-26 00:00:11 CEST 3 days ago git-maintenance@weekly.timer git-maintenance@weekly.service +----------------------------------------------------------------------- + +One timer is registered for each `--schedule=<frequency>` option. + +The definition of the systemd units can be inspected in the following files: + +----------------------------------------------------------------------- +~/.config/systemd/user/git-maintenance@.timer +~/.config/systemd/user/git-maintenance@.service +~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer +~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer +~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer +----------------------------------------------------------------------- + +`git maintenance start` will overwrite these files and start the timer +again with `systemctl --user`, so any customization should be done by +creating a drop-in file, i.e. a `.conf` suffixed file in the +`~/.config/systemd/user/git-maintenance@.service.d` directory. + +`git maintenance stop` will stop the user systemd timers and delete +the above mentioned files. + +For more details, see `systemd.timer(5)`. + + BACKGROUND MAINTENANCE ON MACOS SYSTEMS --------------------------------------- @@ -338,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 f856032..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. @@ -70,12 +83,21 @@ OPTIONS --diff3:: Show conflicts in "diff3" style. +--zdiff3:: + Show conflicts in "zdiff3" style. + --ours:: --theirs:: --union:: 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 -------- @@ -90,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-index.txt b/Documentation/git-merge-index.txt index 2ab84a9..eea56b3 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- [verse] -'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) +'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) ) DESCRIPTION ----------- 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 3819fad..1ab69f6 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -12,19 +12,20 @@ SYNOPSIS 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--[no-]allow-unrelated-histories] - [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...] + [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] + [--into-name <branch>] [<commit>...] 'git merge' (--continue | --abort | --quit) 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 @@ -32,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 @@ -44,23 +46,25 @@ 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 + include::merge-options.txt[] -m <msg>:: @@ -70,10 +74,15 @@ 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>:: + Prepare the default merge message as if merging to the branch + `<branch>`, instead of the name of the real branch to which + the merge is made. + -F <file>:: --file=<file>:: Read the commit message to be used for the merge commit (in @@ -82,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:: @@ -98,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:: @@ -114,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>...:: @@ -138,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 @@ -188,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`. @@ -238,7 +248,8 @@ from the RCS suite to present such a conflicted hunk, like this: ------------ Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed. +ancestor, or cleanly resolved because only one side changed, +or cleanly resolved because both sides changed the same way. <<<<<<< yours:sample.txt Conflict resolution is hard; let's go shopping. @@ -258,17 +269,38 @@ 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" -configuration variable to "diff3". In "diff3" style, the above conflict -may look like this: +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: ------------ Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed. +ancestor, or cleanly resolved because only one side changed, <<<<<<< yours:sample.txt +or cleanly resolved because both sides changed the same way. Conflict resolution is hard; let's go shopping. -||||||| +||||||| base:sample.txt +or cleanly resolved because both sides changed identically. +Conflict resolution is hard. +======= +or cleanly resolved because both sides changed the same way. +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +while in "zdiff3" style, it may look like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed, +or cleanly resolved because both sides changed the same way. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +||||||| base:sample.txt +or cleanly resolved because both sides changed identically. Conflict resolution is hard. ======= Git makes conflict resolution easy. @@ -296,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 @@ -356,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 e587c77..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 @@ -101,6 +102,10 @@ 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 @@ -110,9 +115,16 @@ 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 +---------------------- + +vimdiff +~~~~~~~ +include::mergetools/vimdiff.txt[] + GIT --- Part of the linkgit:git[1] suite 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 27fe2b3..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 as 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 ffd601b..3696506 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -9,8 +9,7 @@ git-multi-pack-index - Write and verify multi-pack-indexes SYNOPSIS -------- [verse] -'git multi-pack-index' [--object-dir=<dir>] [--[no-]progress] - [--preferred-pack=<pack>] <subcommand> +'git multi-pack-index' [--object-dir=<dir>] [--[no-]bitmap] <sub-command> DESCRIPTION ----------- @@ -23,10 +22,13 @@ OPTIONS Use given directory for the location of Git objects. We check `<dir>/packs/multi-pack-index` for the current MIDX file, and `<dir>/packs` for the pack-files to index. ++ +`<dir>` must be an alternate of the current repository. --[no-]progress:: Turn progress on/off explicitly. If neither is specified, progress is - shown if standard error is connected to a terminal. + shown if standard error is connected to a terminal. Supported by + sub-commands `write`, `verify`, `expire`, and `repack. The following subcommands are available: @@ -37,18 +39,41 @@ write:: -- --preferred-pack=<pack>:: Optionally specify the tie-breaking pack used when - multiple packs contain the same object. If not given, - ties are broken in favor of the pack with the lowest - mtime. + multiple packs contain the same object. `<pack>` must + contain at least one object. If not given, ties are + broken in favor of the pack with the lowest mtime. + + --[no-]bitmap:: + Control whether or not a multi-pack bitmap is written. + + --stdin-packs:: + Write a multi-pack index containing only the set of + line-delimited pack index basenames provided over stdin. + + --refs-snapshot=<path>:: + With `--bitmap`, optionally specify a file which + contains a "refs snapshot" taken prior to repacking. ++ +A reference snapshot is composed of line-delimited OIDs corresponding to +the reference tips, usually taken by `git repack` prior to generating a +new pack. A line may optionally start with a `+` character to indicate +that the reference which corresponds to that OID is "preferred" (see +linkgit:git-config[1]'s `pack.preferBitmapTips`.) ++ +The file given at `<path>` is expected to be readable, and can contain +duplicates. (If a given OID is given more than once, it is marked as +preferred if at least one instance of it begins with the special `+` +marker). -- 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 @@ -75,19 +100,26 @@ associated `.keep` file will not be selected for the batch to repack. EXAMPLES -------- -* Write a MIDX file for the packfiles in the current .git folder. +* Write a MIDX file for the packfiles in the current `.git` directory. + ----------------------------------------------- $ git multi-pack-index write ----------------------------------------------- +* Write a MIDX file for the packfiles in the current `.git` directory with a +corresponding bitmap. ++ +------------------------------------------------------------- +$ git multi-pack-index write --preferred-pack=<pack> --bitmap +------------------------------------------------------------- + * Write a MIDX file for the packfiles in an alternate object store. + ----------------------------------------------- $ git multi-pack-index --object-dir <alt> write ----------------------------------------------- -* Verify the MIDX file for the packfiles in the current .git folder. +* Verify the MIDX file for the packfiles in the current `.git` directory. + ----------------------------------------------- $ git multi-pack-index verify @@ -97,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 5cb0eb0..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. @@ -42,11 +42,34 @@ OPTIONS --all:: List all commits reachable from all refs ---stdin:: +--annotate-stdin:: 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. Intended for the scripter's use. + altogether. This option was called `--stdin` in older versions + of Git. ++ +For example: ++ +----------- +$ cat sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907, +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad + +$ git name-rev --annotate-stdin <sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master), +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad + +$ git name-rev --name-only --annotate-stdin <sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is master, +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad +----------- --name-only:: Instead of printing both the SHA-1 and the name, print only @@ -81,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-p4.txt b/Documentation/git-p4.txt index 38e5257..de5ee67 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories SYNOPSIS -------- [verse] -'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... -'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>... +'git p4 sync' [<sync-options>] [<p4-depot-path>...] 'git p4 rebase' -'git p4 submit' [<submit options>] [<master branch name>] +'git p4 submit' [<submit-options>] [<master-branch-name>] DESCRIPTION @@ -361,7 +361,7 @@ These options can be used to modify 'git p4 submit' behavior. p4/master. See the "Sync options" section above for more information. ---commit <sha1>|<sha1..sha1>:: +--commit (<sha1>|<sha1>..<sha1>):: Submit only the specified commit or range of commits, instead of the full list of changes that are in the current Git branch. @@ -636,7 +636,42 @@ git-p4.pathEncoding:: Git expects paths encoded as UTF-8. Use this config to tell git-p4 what encoding Perforce had used for the paths. This encoding is used to transcode the paths to UTF-8. As an example, Perforce on Windows - often uses "cp1252" to encode path names. + often uses "cp1252" to encode path names. If this option is passed + into a p4 clone request, it is persisted in the resulting new git + repo. + +git-p4.metadataDecodingStrategy:: + Perforce keeps the encoding of a changelist descriptions and user + full names as stored by the client on a given OS. The p4v client + uses the OS-local encoding, and so different users can end up storing + different changelist descriptions or user full names in different + encodings, in the same depot. + Git tolerates inconsistent/incorrect encodings in commit messages + and author names, but expects them to be specified in utf-8. + git-p4 can use three different decoding strategies in handling the + encoding uncertainty in Perforce: 'passthrough' simply passes the + original bytes through from Perforce to git, creating usable but + incorrectly-encoded data when the Perforce data is encoded as + anything other than utf-8. 'strict' expects the Perforce data to be + encoded as utf-8, and fails to import when this is not true. + 'fallback' attempts to interpret the data as utf-8, and otherwise + falls back to using a secondary encoding - by default the common + windows encoding 'cp-1252' - with upper-range bytes escaped if + decoding with the fallback encoding also fails. + Under python2 the default strategy is 'passthrough' for historical + reasons, and under python3 the default is 'fallback'. + When 'strict' is selected and decoding fails, the error message will + propose changing this config parameter as a workaround. If this + option is passed into a p4 clone request, it is persisted into the + resulting new git repo. + +git-p4.metadataFallbackEncoding:: + Specify the fallback encoding to use when decoding Perforce author + names and changelists descriptions using the 'fallback' strategy + (see git-p4.metadataDecodingStrategy). The fallback encoding will + only be used when decoding as utf-8 fails. This option defaults to + cp1252, a common windows encoding. If this option is passed into a + p4 clone request, it is persisted into the resulting new git repo. git-p4.largeFileSystem:: Specify the system that is used for large (binary) files. Please note diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index dbfd1f9..e32404c 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -13,8 +13,9 @@ SYNOPSIS [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] - [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list + [--cruft] [--cruft-expiration=<time>] + [--stdout [--filter=<filter-spec>] | <base-name>] + [--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list> DESCRIPTION @@ -95,6 +96,33 @@ base-name:: Incompatible with `--revs`, or options that imply `--revs` (such as `--all`), with the exception of `--unpacked`, which is compatible. +--cruft:: + Packs unreachable objects into a separate "cruft" pack, denoted + by the existence of a `.mtimes` file. Typically used by `git + repack --cruft`. Callers provide a list of pack names and + indicate which packs will remain in the repository, along with + which packs will be deleted (indicated by the `-` prefix). The + contents of the cruft pack are all objects not contained in the + surviving packs which have not exceeded the grace period (see + `--cruft-expiration` below), or which have exceeded the grace + period, but are reachable from an other object which hasn't. ++ +When the input lists a pack containing all reachable objects (and lists +all other packs as pending deletion), the corresponding cruft pack will +contain all unreachable objects (with mtime newer than the +`--cruft-expiration`) along with any unreachable objects whose mtime is +older than the `--cruft-expiration`, but are reachable from an +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`. + +--cruft-expiration=<approxidate>:: + If specified, objects are eliminated from the cruft pack if they + have an mtime older than `<approxidate>`. If unspecified (and + given `--cruft`), then no objects are eliminated. + --window=<n>:: --depth=<n>:: These two options affect how the objects contained in @@ -268,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 f2869da..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 5c3fb67..b2ae496 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -15,14 +15,17 @@ SYNOPSIS DESCRIPTION ----------- -Incorporates changes from a remote repository into the current -branch. In its default mode, `git pull` is shorthand for -`git fetch` followed by `git merge FETCH_HEAD`. - -More precisely, 'git pull' runs 'git fetch' with the given -parameters and calls 'git merge' to merge the retrieved branch -heads into the current branch. -With `--rebase`, it runs 'git rebase' instead of 'git merge'. +Incorporates changes from a remote repository into the current branch. +If the current branch is behind the remote, then by default it will +fast-forward the current branch to match the remote. If the current +branch and the remote have diverged, the user needs to specify how to +reconcile the divergent branches with `--rebase` or `--no-rebase` (or +the corresponding configuration option in `pull.rebase`). + +More precisely, `git pull` runs `git fetch` with the given parameters +and then depending on configuration options or command line flags, +will call either `git rebase` or `git merge` to reconcile diverging +branches. <repository> should be the name of a remote repository as passed to linkgit:git-fetch[1]. <refspec> can name an @@ -84,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 @@ -102,7 +105,7 @@ Options related to merging include::merge-options.txt[] -r:: ---rebase[=false|true|merges|preserve|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 @@ -113,11 +116,7 @@ When set to `merges`, rebase using `git rebase --rebase-merges` so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When set to `preserve` (deprecated in favor of `merges`), rebase with the -`--preserve-merges` option passed to `git rebase` so that locally created -merge commits will not be flattened. -+ -When false, merge the current branch into the upstream branch. +When false, merge the upstream branch into the current branch. + When `interactive`, enable the interactive mode of rebase. + @@ -132,7 +131,7 @@ published that history already. Do *not* use this option unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: - Override earlier --rebase. + This is shorthand for --rebase=false. Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 5fa8bab..1c48c28 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -9,9 +9,8 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- [verse] -'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] - [-u [--exclude-per-directory=<gitignore>] | -i]] - [--index-output=<file>] [--no-sparse-checkout] +'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>) + [-u | -i]] [--index-output=<file>] [--no-sparse-checkout] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) @@ -26,21 +25,22 @@ 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:: Same as -m, except that unmerged entries are discarded instead - of failing. When used with `-u`, updates leading to loss of - working tree changes will not abort the operation. + of failing. When used with `-u`, updates leading to loss of + working tree changes or untracked files or directories will not + abort the operation. -u:: After a successful merge, update the files in the work @@ -88,21 +88,6 @@ OPTIONS The command will refuse to overwrite entries that already existed in the original index file. ---exclude-per-directory=<gitignore>:: - When running the command with `-u` and `-m` options, the - merge result may need to overwrite paths that are not - tracked in the current branch. The command usually - refuses to proceed with the merge to avoid losing such a - path. However this safety valve sometimes gets in the - way. For example, it often happens that the other - branch added a file that used to be a generated file in - your branch, and the safety valve triggers when you try - to switch to that branch after you ran `make` but before - running `make clean` to remove the generated file. This - option tells the command to read per-directory exclude - file (usually '.gitignore') and allows such an untracked - but explicitly ignored file to be overwritten. - --index-output=<file>:: Instead of writing the results out to `$GIT_INDEX_FILE`, write the resulting index in the named file. While the @@ -234,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` @@ -390,9 +375,17 @@ have finished your work-in-progress), attempt the merge again. SPARSE CHECKOUT --------------- +Note: The skip-worktree capabilities in linkgit:git-update-index[1] +and `read-tree` predated the introduction of +linkgit:git-sparse-checkout[1]. Users are encouraged to use the +`sparse-checkout` command in preference to these plumbing commands for +sparse-checkout/skip-worktree related needs. However, the information +below might be useful to users trying to understand the pattern style +used in non-cone mode of the `sparse-checkout` command. + "Sparse checkout" allows populating the working directory sparsely. -It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file in the working directory is worth looking at. +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to +tell Git whether a file in the working directory is worth looking at. 'git read-tree' and other merge-based commands ('git merge', 'git checkout'...) can help maintaining the skip-worktree bitmap and working @@ -400,7 +393,8 @@ directory update. `$GIT_DIR/info/sparse-checkout` is used to define the skip-worktree reference bitmap. When 'git read-tree' needs to update the working directory, it resets the skip-worktree bit in the index based on this file, which uses the same syntax as .gitignore files. -If an entry matches a pattern in this file, skip-worktree will not be +If an entry matches a pattern in this file, or the entry corresponds to +a file present in the working tree, then skip-worktree will not be set on that entry. Otherwise, skip-worktree will be set. Then it compares the new skip-worktree value with the previous one. If @@ -435,8 +429,8 @@ support. SEE ALSO -------- -linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; -linkgit:gitignore[5]; linkgit:git-sparse-checkout[1]; +linkgit:git-write-tree[1], linkgit:git-ls-files[1], +linkgit:gitignore[5], linkgit:git-sparse-checkout[1] GIT --- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 55af6fd..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,9 +86,10 @@ 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. 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): +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): ------------ A---B---C topic @@ -175,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 @@ -200,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 @@ -214,18 +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> <branch>. Running - 'git rebase --keep-base <upstream> <branch>' is equivalent to - running 'git rebase --onto <upstream>... <upstream>'. + merge base of `<upstream>` and `<branch>`. Running + `git rebase --keep-base <upstream> <branch>` is equivalent to + running + `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. @@ -236,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` @@ -261,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. @@ -285,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. @@ -297,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. @@ -309,10 +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. +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. @@ -327,40 +368,26 @@ 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:: - Use merging strategies to rebase. When the recursive (default) merge - strategy is used, this allows rebase to be aware of renames on the - upstream side. This is the default. + 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. -s <strategy>:: --strategy=<strategy>:: - Use the given merge strategy. - If there is no `-s` option 'git merge-recursive' is used - instead. This implies --merge. + 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. @@ -369,15 +396,12 @@ See also INCOMPATIBLE OPTIONS below. --strategy-option=<strategy-option>:: Pass the <strategy-option> through to the merge strategy. This implies `--merge` and, if no strategy has been - specified, `-s recursive`. Note the reversal of 'ours' and + specified, `-s ort`. Note the reversal of 'ours' and 'theirs' as noted above for the `-m` option. + 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>]:: @@ -390,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 @@ -409,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. @@ -434,20 +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`. +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. + @@ -455,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. @@ -504,54 +531,42 @@ 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). -+ -The `--rebase-merges` mode is similar in spirit to the deprecated -`--preserve-merges` but works with interactive rebases, -where commits can be reordered, inserted and dropped at will. +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 -`recursive` merge strategy; Different merge strategies can be used only via +`ort` merge strategy; different merge strategies can be used only via explicit `exec git merge -s <strategy> [...]` commands. + See also REBASING MERGES and INCOMPATIBLE OPTIONS below. --p:: ---preserve-merges:: - [DEPRECATED: use `--rebase-merges` instead] Recreate merge commits - instead of flattening the history by replaying commits a merge commit - introduces. Merge conflict resolutions or manual amendments to merge - commits are not preserved. -+ -This uses the `--interactive` machinery internally, but combining it -with the `--interactive` option explicitly is generally not a good -idea unless you know what you are doing (see BUGS below). -+ -See also 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. + @@ -564,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. + @@ -574,34 +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. - When used together with both --onto and --preserve-merges, - 'all' root commits will be rewritten to have <newbase> as parent - instead. + 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. ++ +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. + -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. +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. @@ -618,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 -------------------- @@ -640,27 +670,18 @@ are incompatible with the following options: * --merge * --strategy * --strategy-option - * --allow-empty-message - * --[no-]autosquash + * --autosquash * --rebase-merges - * --preserve-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: - * --preserve-merges and --interactive - * --preserve-merges and --signoff - * --preserve-merges and --rebase-merges - * --preserve-merges and --empty= - * --preserve-merges and --ignore-whitespace - * --preserve-merges and --committer-date-is-author-date - * --preserve-merges and --ignore-date * --keep-base and --onto * --keep-base and --root * --fork-point and --root @@ -668,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 @@ -679,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 @@ -699,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 @@ -723,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 @@ -735,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, 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. +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. @@ -766,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.) @@ -781,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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -802,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 ---------------- @@ -873,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. @@ -901,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 @@ -928,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 @@ -954,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" @@ -981,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. @@ -1008,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. @@ -1112,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].) @@ -1219,12 +1238,16 @@ successful merge so that the user can edit the message. If a `merge` command fails for any reason other than merge conflicts (i.e. when the merge operation did not even start), it is rescheduled immediately. -At this time, the `merge` command will *always* use the `recursive` -merge strategy for regular merges, and `octopus` for octopus merges, -with no way to choose a different one. To work around -this, an `exec` command can be used to call `git merge` explicitly, -using the fact that the labels are worktree-local refs (the ref -`refs/rewritten/onto` would correspond to the label `onto`, for example). +By default, the `merge` command will use the `ort` merge strategy for +regular merges, and `octopus` for octopus merges. One can specify a +default strategy for all merges using the `--strategy` argument when +invoking rebase, or can override specific merges in the interactive +list of commands by using an `exec` command to call `git merge` +explicitly with a `--strategy` argument. Note that when calling `git +merge` explicitly like this, you can make use of the fact that the +labels are worktree-local refs (the ref `refs/rewritten/onto` would +correspond to the label `onto`, for example) in order to refer to the +branches you want to merge. Note: the first command (`label onto`) labels the revision onto which the commits are rebased; The name `onto` is just a convention, as a nod @@ -1271,32 +1294,11 @@ merge cmake CONFIGURATION ------------- +include::includes/cmd-config-section-all.txt[] + include::config/rebase.txt[] include::config/sequencer.txt[] -BUGS ----- -The todo list presented by the deprecated `--preserve-merges --interactive` -does not represent the topology of the revision graph (use `--rebase-merges` -instead). Editing commits and rewording their commit messages should work -fine, but attempts to reorder commits tend to produce counterintuitive results. -Use `--rebase-merges` in such scenarios instead. - -For example, an attempt to rearrange ------------- -1 --- 2 --- 3 --- 4 --- 5 ------------- -to ------------- -1 --- 2 --- 4 --- 3 --- 5 ------------- -by moving the "pick 4" line will result in the following history: ------------- - 3 - / -1 --- 2 --- 4 --- 5 ------------- - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 25702ed..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,9 +38,14 @@ its behavior, see linkgit:git-config[1]. OPTIONS ------- -<directory>:: +<git-dir>:: The repository to sync into. +--http-backend-info-refs:: + Used by linkgit:git-http-backend[1] to serve up + `$GIT_URL/info/refs?service=git-receive-pack` requests. See + `--http-backend-info-refs` in linkgit:git-upload-pack[1]. + PRE-RECEIVE HOOK ---------------- Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index ff487ff..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 31c29c9..932a5c3 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,15 +10,15 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url> -'git remote rename' <old> <new> +'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL> +'git remote rename' [--[no-]progress] <old> <new> 'git remote remove' <name> 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>) 'git remote set-branches' [--add] <name> <branch>... 'git remote get-url' [--push] [--all] <name> 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> -'git remote set-url --delete' [--push] <name> <url> +'git remote set-url --delete' [--push] <name> <URL> 'git remote' [-v | --verbose] 'show' [-n] <name>... 'git remote prune' [-n | --dry-run] <name>... 'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...] @@ -35,6 +35,8 @@ OPTIONS -v:: --verbose:: Be a little more verbose and show remote url after name. + For promisor remotes, also show which filters (`blob:none` etc.) + are configured. NOTE: This must be placed between `remote` and subcommand. @@ -47,7 +49,7 @@ subcommands are available to perform operations on the remotes. 'add':: Add a remote named <name> for the repository at -<url>. The command `git fetch <name>` can then be used to create and +<URL>. The command `git fetch <name>` can then be used to create and update remote-tracking branches <name>/<branch>. + With `-f` option, `git fetch <name>` is run immediately after @@ -152,7 +154,7 @@ With `--push`, push URLs are manipulated instead of fetch URLs. With `--add`, instead of changing existing URLs, new URL is added. + With `--delete`, instead of changing existing URLs, all URLs matching -regex <url> are deleted for remote <name>. Trying to delete all +regex <URL> are deleted for remote <name>. Trying to delete all non-push URLs is an error. + Note that the push URL and the fetch URL, even though they can diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 24c00c9..c902512 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- [verse] -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] +'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx] DESCRIPTION ----------- @@ -63,6 +63,34 @@ to the new separate pack will be written. Also run 'git prune-packed' to remove redundant loose object files. +--cruft:: + Same as `-a`, unless `-d` is used. Then any unreachable objects + are packed into a separate cruft pack. Unreachable objects can + be pruned using the normal expiry rules with the next `git gc` + invocation (see linkgit:git-gc[1]). Incompatible with `-k`. + +--cruft-expiration=<approxidate>:: + Expire unreachable objects older than `<approxidate>` + 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]. @@ -76,8 +104,9 @@ to the new separate pack will be written. linkgit:git-pack-objects[1]. -q:: - Pass the `-q` option to 'git pack-objects'. See - linkgit:git-pack-objects[1]. +--quiet:: + Show no progress over the standard error stream and pass the `-q` + option to 'git pack-objects'. See linkgit:git-pack-objects[1]. -n:: Do not update the server information with @@ -125,13 +154,37 @@ 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 - only makes sense when used with `-a` or `-A`, as the bitmaps + only makes sense when used with `-a`, `-A` or `-m`, as the bitmaps must be able to refer to all reachable objects. This option - overrides the setting of `repack.writeBitmaps`. This option - has no effect if multiple packfiles are created. + overrides the setting of `repack.writeBitmaps`. This option + has no effect if multiple packfiles are created, unless writing a + MIDX (in which case a multi-pack bitmap is created). --pack-kept-objects:: Include objects in `.keep` files when repacking. Note that we @@ -146,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>:: @@ -167,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 @@ -184,11 +237,17 @@ 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 +linkgit:git-multi-pack-index[1]). + +-m:: +--write-midx:: + Write a multi-pack index (see linkgit:git-multi-pack-index[1]) + containing the non-redundant packs. CONFIGURATION ------------- 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 4d4392d..15dcbb6 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -8,7 +8,7 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- [verse] -'git request-pull' [-p] <start> <url> [<end>] +'git request-pull' [-p] <start> <URL> [<end>] DESCRIPTION ----------- @@ -16,12 +16,12 @@ 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 since that commit, up to the commit named by `<end>`, by visiting -the repository named by `<url>`. +the repository named by `<URL>`. OPTIONS @@ -33,14 +33,14 @@ OPTIONS Commit to start at. This names a commit that is already in the upstream history. -<url>:: +<URL>:: The repository URL to be pulled from. <end>:: Commit to end at (defaults to HEAD). This names the commit at the tip of the history you are asking to be pulled. + -When the repository named by `<url>` has the commit at a tip of a +When the repository named by `<URL>` has the commit at a tip of a ref that is different from the ref you have locally, you can use the `<local>:<remote>` syntax, to have its local name, a colon `:`, and its remote name. @@ -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 252e2d4..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: + -- @@ -69,7 +70,8 @@ linkgit:git-add[1]). --hard:: Resets the index and working tree. Any changes to tracked files in the - working tree since `<commit>` are discarded. + working tree since `<commit>` are discarded. Any untracked files or + directories in the way of writing any tracked files are simply deleted. --merge:: Resets the index and updates the files in the working tree that are @@ -104,10 +106,11 @@ OPTIONS -q:: --quiet:: ---no-quiet:: - Be quiet, only report errors. The default behavior is set by the - `reset.quiet` config option. `--quiet` and `--no-quiet` will - override the default behavior. + Be quiet, only report errors. + +--refresh:: +--no-refresh:: + Refresh the index after a mixed reset. Enabled by default. --pathspec-from-file=<file>:: Pathspec is passed in `<file>` instead of commandline args. If diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 55bde91..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,13 +89,14 @@ 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 conflicting hunks are presented, overriding the `merge.conflictStyle` configuration variable. Possible values - are "merge" (default) and "diff3" (in addition to what is - shown by "merge" style, shows the original contents). + are "merge" (default), "diff3", and "zdiff3". --ignore-unmerged:: When restoring files on the working tree from the index, do @@ -102,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 @@ -196,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 bb92a4a..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,10 +112,16 @@ 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>.", + 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 + default. + SEQUENCER SUBCOMMANDS --------------------- @@ -136,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 26e9b28..363a269 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -72,6 +72,12 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. --ignore-unmatch:: Exit with a zero status even if no files matched. +--sparse:: + Allow updating index entries outside of the sparse-checkout cone. + Normally, `git rm` refuses to update index entries whose paths do + not fit within the sparse-checkout cone. See + linkgit:git-sparse-checkout[1] for more. + -q:: --quiet:: `git rm` normally outputs one line (in the form of an `rm` command) @@ -157,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 3db4eab..c5d664f 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -9,7 +9,8 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- [verse] -'git send-email' [<options>] <file|directory|rev-list options>... +'git send-email' [<options>] (<file>|<directory>)... +'git send-email' [<options>] <format-patch-options> 'git send-email' --dump-aliases @@ -19,7 +20,8 @@ Takes the patches given on the command line and emails them out. Patches can be specified as files, directories (which will send all files in the directory), or directly as a revision list. In the last case, any format accepted by linkgit:git-format-patch[1] can -be passed to git send-email. +be passed to git send-email, as well as options understood by +linkgit:git-format-patch[1]. The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine @@ -66,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. + @@ -91,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. @@ -135,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. @@ -171,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 @@ -257,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). @@ -266,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. @@ -289,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. @@ -301,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 @@ -309,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 @@ -325,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>:: @@ -361,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. @@ -431,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, @@ -446,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 -------- @@ -505,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 44fd146..b9e73f2 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,10 +9,11 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--all] [--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)] - [<host>:]<directory> [<ref>...] + [--[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 c9c7f30..7d0277d 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] -'git shortlog' [<options>] [<revision range>] [[--] <path>...] +'git shortlog' [<options>] [<revision-range>] [[--] <path>...] git log --pretty=short | 'git shortlog' [<options>] DESCRIPTION @@ -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 @@ -89,13 +97,13 @@ counts both authors and co-authors. If width is `0` (zero) then indent the lines of the output without wrapping them. -<revision range>:: +<revision-range>:: Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to `HEAD` (i.e. the + <revision-range> is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` specifies all the commits reachable from the current commit (i.e. `HEAD`), but not from `origin`. For a complete list of - ways to spell <revision range>, see the "Specifying Ranges" + ways to spell <revision-range>, see the "Specifying Ranges" section of linkgit:gitrevisions[7]. [--] <path>...:: 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 fdcf43f..529a8ed 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -3,22 +3,32 @@ git-sparse-checkout(1) NAME ---- -git-sparse-checkout - Initialize and modify the sparse-checkout -configuration, which reduces the checkout to a set of paths -given by a list of patterns. +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 ----------- -Initialize and modify the sparse-checkout configuration, which reduces -the checkout to a set of paths given by a list of patterns. +This command is used to create sparse checkouts, which change the +working tree from having all tracked files present to only having a +subset of those files. It can also switch which subset of files are +present, or undo and go back to having all tracked files present in +the working copy. + +The subset of files is chosen by providing a list of directories in +cone mode (the default), or by providing a list of patterns in +non-cone mode. + +When in a sparse-checkout, other Git commands behave a bit differently. +For example, switching branches will not update paths outside the +sparse-checkout directories/patterns, and `git commit -a` will not record +paths outside the sparse-checkout directories/patterns as deleted. THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN @@ -28,30 +38,50 @@ THE FUTURE. COMMANDS -------- 'list':: - Describe the patterns in the sparse-checkout file. + Describe the directories or patterns in the sparse-checkout file. -'init':: - Enable the `core.sparseCheckout` setting. If the - sparse-checkout file does not exist, then populate it with - patterns that match every file in the root directory and - no other directories, then will remove all directories tracked - by Git. Add patterns to the sparse-checkout file to - repopulate the working directory. +'set':: + Enable the necessary sparse-checkout config settings + (`core.sparseCheckout`, `core.sparseCheckoutCone`, and + `index.sparse`) if they are not already set to the desired values, + populate the sparse-checkout file from the list of arguments + following the 'set' subcommand, and update the working directory to + match. ++ +To ensure that adjusting the sparse-checkout settings within a worktree +does not alter the sparse-checkout settings in other worktrees, the 'set' +subcommand will upgrade your repository config to use worktree-specific +config if not already present. The sparsity defined by the arguments to +the 'set' subcommand are stored in the worktree-specific sparse-checkout +file. See linkgit:git-worktree[1] and the documentation of +`extensions.worktreeConfig` in linkgit:git-config[1] for more details. + -To avoid interfering with other worktrees, it first enables the -`extensions.worktreeConfig` setting and makes sure to set the -`core.sparseCheckout` setting in the worktree-specific config file. +When the `--stdin` option is provided, the directories or patterns are +read from standard in as a newline-delimited list instead of from the +arguments. + -When `--cone` is provided, the `core.sparseCheckoutCone` setting is -also set, allowing for better performance with a limited set of -patterns (see 'CONE PATTERN SET' below). +By default, the input list is considered a list of directories, matching +the output of `git ls-tree -d --name-only`. This includes interpreting +pathnames that begin with a double quote (") as C-style quoted strings. +Note that all files under the specified directories (at any depth) will +be included in the sparse checkout, as well as files that are siblings +of either the given directory or any of its ancestors (see 'CONE PATTERN +SET' below for more details). In the past, this was not the default, +and `--cone` needed to be specified or `core.sparseCheckoutCone` needed +to be enabled. + -Use the `--[no-]sparse-index` option to toggle the use of the sparse -index format. This reduces the size of the index to be more closely -aligned with your sparse-checkout definition. This can have significant -performance advantages for commands such as `git status` or `git add`. -This feature is still experimental. Some commands might be slower with -a sparse index until they are properly integrated with the feature. +When `--no-cone` is passed, the input list is considered a list of +patterns. This mode has a number of drawbacks, including not working +with some options like `--sparse-index`. As explained in the +"Non-cone Problems" section below, we do not recommend using it. ++ +Use the `--[no-]sparse-index` option to use a sparse index (the +default is to not use it). A sparse index reduces the size of the +index to be more closely aligned with your sparse-checkout +definition. This can have significant performance advantages for +commands such as `git status` or `git add`. This feature is still +experimental. Some commands might be slower with a sparse index until +they are properly integrated with the feature. + **WARNING:** Using a sparse index requires modifying the index in a way that is not completely understood by external tools. If you have trouble @@ -60,29 +90,11 @@ to rewrite your index to not be sparse. Older versions of Git will not understand the sparse directory entries index extension and may fail to interact with your repository until it is disabled. -'set':: - Write a set of patterns to the sparse-checkout file, as given as - a list of arguments following the 'set' subcommand. Update the - working directory to match the new patterns. Enable the - core.sparseCheckout config setting if it is not already enabled. -+ -When the `--stdin` option is provided, the patterns are read from -standard in as a newline-delimited list instead of from the arguments. -+ -When `core.sparseCheckoutCone` is enabled, the input list is considered a -list of directories instead of sparse-checkout patterns. The command writes -patterns to the sparse-checkout file to include all files contained in those -directories (recursively) as well as files that are siblings of ancestor -directories. The input format matches the output of `git ls-tree --name-only`. -This includes interpreting pathnames that begin with a double quote (") as -C-style quoted strings. - 'add':: - Update the sparse-checkout file to include additional patterns. - By default, these patterns are read from the command-line arguments, - but they can be read from stdin using the `--stdin` option. When - `core.sparseCheckoutCone` is enabled, the given patterns are interpreted - as directory names as in the 'set' subcommand. + Update the sparse-checkout file to include additional directories + (in cone mode) or patterns (in non-cone mode). By default, these + directories or patterns are read from the command-line arguments, + but they can be read from stdin using the `--stdin` option. 'reapply':: Reapply the sparsity pattern rules to paths in the working tree. @@ -93,23 +105,107 @@ C-style quoted strings. cases, it can make sense to run `git sparse-checkout reapply` later after cleaning up affected paths (e.g. resolving conflicts, undoing or committing changes, etc.). ++ +The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index` +flags, with the same meaning as the flags from the `set` command, in order +to change which sparsity mode you are using without needing to also respecify +all sparsity paths. 'disable':: Disable the `core.sparseCheckout` config setting, and restore the - working directory to include all files. Leaves the sparse-checkout - file intact so a later 'git sparse-checkout init' command may - return the working directory to the same state. + working directory to include all files. + +'init':: + Deprecated command that behaves like `set` with no specified paths. + May be removed in the future. ++ +Historically, `set` did not handle all the necessary config settings, +which meant that both `init` and `set` had to be called. Invoking +both meant the `init` step would first remove nearly all tracked files +(and in cone mode, ignored files too), then the `set` step would add +many of the tracked files (but not ignored files) back. In addition +to the lost files, the performance and UI of this combination was +poor. ++ +Also, historically, `init` would not actually initialize the +sparse-checkout file if it already existed. This meant it was +possible to return to a sparse-checkout without remembering which +paths to pass to a subsequent 'set' or 'add' command. However, +`--cone` and `--sparse-index` options would not be remembered across +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. -SPARSE CHECKOUT ---------------- -"Sparse checkout" allows populating the working directory sparsely. -It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file in the working directory is worth looking at. If -the skip-worktree bit is set, then the file is ignored in the working -directory. Git will not populate the contents of those files, which -makes a sparse checkout helpful when working in a repository with many -files, but only a few are important to the current user. +EXAMPLES +-------- +`git sparse-checkout set MY/DIR1 SUB/DIR2`:: + + Change to a sparse checkout with all files (at any depth) under + MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all + files immediately under MY/ and SUB/ and the toplevel + directory). If already in a sparse checkout, change which files + are present in the working copy to this new selection. Note + that this command will also delete all ignored files in any + directory that no longer has either tracked or + non-ignored-untracked files present. + +`git sparse-checkout disable`:: + + Repopulate the working directory with all files, disabling sparse + checkouts. + +`git sparse-checkout add SOME/DIR/ECTORY`:: + + Add all files under SOME/DIR/ECTORY/ (at any depth) to the + sparse checkout, as well as all files immediately under + SOME/DIR/ and immediately under SOME/. Must already be in a + sparse checkout before using this command. + +`git sparse-checkout reapply`:: + + It is possible for commands to update the working tree in a + way that does not respect the selected sparsity directories. + This can come from tools external to Git writing files, or + even affect Git commands because of either special cases (such + as hitting conflicts when merging/rebasing), or because some + commands didn't fully support sparse checkouts (e.g. the old + `recursive` merge backend had only limited support). This + command reapplies the existing sparse directory specifications + to make the working directory match. + +INTERNALS -- SPARSE CHECKOUT +---------------------------- + +"Sparse checkout" allows populating the working directory sparsely. It +uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git +whether a file in the working directory is worth looking at. If the +skip-worktree bit is set, and the file is not present in the working tree, +then its absence is ignored. Git will avoid populating the contents of +those files, which makes a sparse checkout helpful when working in a +repository with many files, but only a few are important to the current +user. The `$GIT_DIR/info/sparse-checkout` file is used to define the skip-worktree reference bitmap. When Git updates the working @@ -117,66 +213,196 @@ directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. -To enable the sparse-checkout feature, run `git sparse-checkout init` to -initialize a simple sparse-checkout file and enable the `core.sparseCheckout` -config setting. Then, run `git sparse-checkout set` to modify the patterns in -the sparse-checkout file. +INTERNALS -- NON-CONE PROBLEMS +------------------------------ + +The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and +`add` subcommands is defined to be a bunch of patterns (one per line) +using the same syntax as `.gitignore` files. In cone mode, these +patterns are restricted to matching directories (and users only ever +need supply or see directory names), while in non-cone mode any +gitignore-style pattern is permitted. Using the full gitignore-style +patterns in non-cone mode has a number of shortcomings: + + * Fundamentally, it makes various worktree-updating processes (pull, + merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern + matches, where N is the number of patterns and M is the number of + paths in the index. This scales poorly. + + * Avoiding the scaling issue has to be done via limiting the number + of patterns via specifying leading directory name or glob. + + * Passing globs on the command line is error-prone as users may + forget to quote the glob, causing the shell to expand it into all + matching files and pass them all individually along to + sparse-checkout set/add. While this could also be a problem with + e.g. "git grep -- *.c", mistakes with grep/log/status appear in + the immediate output. With sparse-checkout, the mistake gets + recorded at the time the sparse-checkout command is run and might + not be problematic until the user later switches branches or rebases + or merges, thus putting a delay between the user's error and when + they have a chance to catch/notice it. + + * Related to the previous item, sparse-checkout has an 'add' + subcommand but no 'remove' subcommand. Even if a 'remove' + subcommand were added, undoing an accidental unquoted glob runs + the risk of "removing too much", as it may remove entries that had + been included before the accidental add. + + * Non-cone mode uses gitignore-style patterns to select what to + *include* (with the exception of negated patterns), while + .gitignore files use gitignore-style patterns to select what to + *exclude* (with the exception of negated patterns). The + documentation on gitignore-style patterns usually does not talk in + terms of matching or non-matching, but on what the user wants to + "exclude". This can cause confusion for users trying to learn how + to specify sparse-checkout patterns to get their desired behavior. + + * Every other git subcommand that wants to provide "special path + pattern matching" of some sort uses pathspecs, but non-cone mode + for sparse-checkout uses gitignore patterns, which feels + inconsistent. + + * It has edge cases where the "right" behavior is unclear. Two examples: + + First, two users are in a subdirectory, and the first runs + git sparse-checkout set '/toplevel-dir/*.c' + while the second runs + git sparse-checkout set relative-dir + Should those arguments be transliterated into + current/subdirectory/toplevel-dir/*.c + and + current/subdirectory/relative-dir + before inserting into the sparse-checkout file? The user who typed + the first command is probably aware that arguments to set/add are + supposed to be patterns in non-cone mode, and probably would not be + happy with such a transliteration. However, many gitignore-style + patterns are just paths, which might be what the user who typed the + second command was thinking, and they'd be upset if their argument + wasn't transliterated. + + Second, what should bash-completion complete on for set/add commands + for non-cone users? If it suggests paths, is it exacerbating the + 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 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.) + Completing on files or directories might give nasty surprises in + all these cases. + + * The excessive flexibility made other extensions essentially + impractical. `--sparse-index` is likely impossible in non-cone + mode; even if it is somehow feasible, it would have been far more + work to implement and may have been too slow in practice. Some + ideas for adding coupling between partial clones and sparse + checkouts are only practical with a more restricted set of paths + as well. + +For all these reasons, non-cone mode is deprecated. Please switch to +using cone mode. + + +INTERNALS -- CONE MODE HANDLING +------------------------------- + +The "cone mode", which is the default, lets you specify only what +directories to include. For any directory specified, all paths below +that directory will be included, and any paths immediately under +leading directories (including the toplevel directory) will also be +included. Thus, if you specified the directory + Documentation/technical/ +then your sparse checkout would contain: + + * all files in the toplevel-directory + * all files immediately under Documentation/ + * all files at any depth under Documentation/technical/ + +Also, in cone mode, even if no directories are specified, then the +files in the toplevel directory will be included. + +When changing the sparse-checkout patterns in cone mode, Git will inspect each +tracked directory that is not within the sparse-checkout cone to see if it +contains any untracked files. If all of those files are ignored due to the +`.gitignore` patterns, then the directory will be deleted. If any of the +untracked files within that directory is not ignored, then no deletions will +occur within that directory and a warning message will appear. If these files +are important, then reset your sparse-checkout definition so they are included, +use `git add` and `git commit` to store them, then remove any remaining files +manually to ensure Git can behave optimally. + +See also the "Internals -- Cone Pattern Set" section to learn how the +directories are transformed under the hood into a subset of the +Full Pattern Set of sparse-checkout. + + +INTERNALS -- FULL PATTERN SET +----------------------------- -To repopulate the working directory with all files, use the -`git sparse-checkout disable` command. +The full pattern set allows for arbitrary pattern matches and complicated +inclusion/exclusion rules. These can result in O(N*M) pattern matches when +updating the index, where N is the number of patterns and M is the number +of paths in the index. To combat this performance issue, a more restricted +pattern set is allowed when `core.sparseCheckoutCone` is enabled. +The sparse-checkout file uses the same syntax as `.gitignore` files; +see linkgit:gitignore[5] for details. Here, though, the patterns are +usually being used to select which files to include rather than which +files to exclude. (However, it can get a bit confusing since +gitignore-style patterns have negations defined by patterns which +begin with a '!', so you can also select files to _not_ include.) -FULL PATTERN SET ----------------- +For example, to select everything, and then to remove the file +`unwanted` (so that every file will appear in your working tree except +the file named `unwanted`): -By default, the sparse-checkout file uses the same syntax as `.gitignore` -files. + git sparse-checkout set --no-cone '/*' '!unwanted' -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what -files are included, you can also specify what files are _not_ included, -using negative patterns. For example, to remove the file `unwanted`: +These patterns are just placed into the +`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file +at this point would be ---------------- /* !unwanted ---------------- +See also the "Sparse Checkout" section of linkgit:git-read-tree[1] to +learn more about the gitignore-style patterns used in sparse +checkouts. -CONE PATTERN SET ----------------- -The full pattern set allows for arbitrary pattern matches and complicated -inclusion/exclusion rules. These can result in O(N*M) pattern matches when -updating the index, where N is the number of patterns and M is the number -of paths in the index. To combat this performance issue, a more restricted -pattern set is allowed when `core.sparseCheckoutCone` is enabled. +INTERNALS -- CONE PATTERN SET +----------------------------- -The accepted patterns in the cone pattern set are: +In cone mode, only directories are accepted, but they are translated into +the same gitignore-style patterns used in the full pattern set. We refer +to the particular patterns used in those mode as being of one of two types: 1. *Recursive:* All paths inside a directory are included. 2. *Parent:* All files immediately inside a directory are included. -In addition to the above two patterns, we also expect that all files in the -root directory are included. If a recursive pattern is added, then all -leading directories are added as parent patterns. - -By default, when running `git sparse-checkout init`, the root directory is -added as a parent pattern. At this point, the sparse-checkout file contains -the following patterns: +Since cone mode always includes files at the toplevel, when running +`git sparse-checkout set` with no directories specified, the toplevel +directory is added as a parent pattern. At this point, the +sparse-checkout file contains the following patterns: ---------------- /* !/*/ ---------------- -This says "include everything in root, but nothing two levels below root." +This says "include everything immediately under the toplevel +directory, but nothing at any level below that." -When in cone mode, the `git sparse-checkout set` subcommand takes a list of -directories instead of a list of sparse-checkout patterns. In this mode, -the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as -a recursive pattern, the directories `A` and `A/B` are added as parent -patterns. The resulting sparse-checkout file is now +When in cone mode, the `git sparse-checkout set` subcommand takes a +list of directories. The command `git sparse-checkout set A/B/C` sets +the directory `A/B/C` as a recursive pattern, the directories `A` and +`A/B` are added as parent patterns. The resulting sparse-checkout file +is now ---------------- /* @@ -191,14 +417,18 @@ patterns. The resulting sparse-checkout file is now Here, order matters, so the negative patterns are overridden by the positive patterns that appear lower in the file. -If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file -expecting patterns of these types. Git will warn if the patterns do not match. -If the patterns do match the expected format, then Git will use faster hash- -based algorithms to compute inclusion in the sparse-checkout. +Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will +parse the sparse-checkout file expecting patterns of these types. Git will +warn if the patterns do not match. If the patterns do match the expected +format, then Git will use faster hash-based algorithms to compute inclusion +in the sparse-checkout. If they do not match, git will behave as though +`core.sparseCheckoutCone` was false, regardless of its setting. -In the cone mode case, the `git sparse-checkout list` subcommand will list the -directories that define the recursive patterns. For the example sparse-checkout -file above, the output is as follows: +In the cone mode case, despite the fact that full patterns are written +to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout +list` subcommand will list the directories that define the recursive +patterns. For the example sparse-checkout file above, the output is as +follows: -------------------------- $ git sparse-checkout list @@ -211,8 +441,8 @@ case-insensitive check. This corrects for case mismatched filenames in the directory. -SUBMODULES ----------- +INTERNALS -- SUBMODULES +----------------------- If your repository contains one or more submodules, then submodules are populated based on interactions with the `git submodule` command. diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt index 25bcda9..2f6aaa7 100644 --- a/Documentation/git-stage.txt +++ b/Documentation/git-stage.txt @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area SYNOPSIS -------- [verse] -'git stage' args... +'git stage' <arg>... DESCRIPTION diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index be6084c..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] [-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] [-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). @@ -60,7 +63,7 @@ subcommand from making an unwanted stash entry. The two exceptions to this are `stash -p` which acts as alias for `stash push -p` and pathspec elements, which are allowed after a double hyphen `--` for disambiguation. -save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: +save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: This option is deprecated in favour of 'git stash push'. It differs from "stash push" in that it cannot take pathspec. @@ -205,6 +208,16 @@ to learn how to operate the `--patch` mode. The `--patch` option implies `--keep-index`. You can use `--no-keep-index` to override this. +-S:: +--staged:: + This option is only valid for `push` and `save` commands. ++ +Stash only the changes that are currently staged. This is similar to +basic `git commit` except the state is committed to the stash instead +of current branch. ++ +The `--patch` option has priority over this one. + --pathspec-from-file=<file>:: This option is only valid for `push` command. + @@ -341,6 +354,24 @@ $ edit/build/test remaining parts $ git commit foo -m 'Remaining parts' ---------------------------------------------------------------- +Saving unrelated changes for future use:: + +When you are in the middle of massive changes and you find some +unrelated issue that you don't want to forget to fix, you can do the +change(s), stage them, and use `git stash push --staged` to stash them +out for future use. This is similar to committing the staged changes, +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 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 +---------------------------------------------------------------- + Recovering stash entries that were cleared/dropped erroneously:: If you mistakenly drop or clear stash entries, they cannot be recovered @@ -354,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 83f38e3..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]. @@ -207,26 +209,29 @@ show tracked paths: * ' ' = unmodified * 'M' = modified +* 'T' = file type changed (regular file, symbolic link or submodule) * 'A' = added * 'D' = deleted * 'R' = renamed -* 'C' = copied +* 'C' = copied (if config option status.renames is set to "copies") * 'U' = updated but unmerged .... X Y Meaning ------------------------------------------------- [AMD] not updated -M [ MD] updated in index -A [ MD] added to index +M [ MTD] updated in index +T [ MTD] type changed in index +A [ MTD] added to index D deleted from index -R [ MD] renamed in index -C [ MD] copied in index -[MARC] index and work tree matches -[ MARC] M work tree changed since index -[ MARC] D deleted in work tree -[ D] R renamed in work tree -[ D] C copied in work tree +R [ MTD] renamed in index +C [ MTD] copied in index +[MTARC] index and work tree matches +[ MTARC] M work tree changed since index +[ MTARC] T type changed in work tree since index +[ MTARC] D deleted in work tree + R renamed in work tree + C copied in work tree ------------------------------------------------- D D unmerged, both deleted A U unmerged, added by us @@ -242,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 @@ -305,12 +311,20 @@ 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. ------------------------------------------------------------ .... +Stash Information +^^^^^^^^^^^^^^^^^ + +If `--show-stash` is given, one line is printed showing the number of stash +entries if non-zero: + + # stash <N> + Changed Tracked Entries ^^^^^^^^^^^^^^^^^^^^^^^ @@ -363,7 +377,7 @@ Field Meaning Unmerged entries have the following format; the first character is a "u" to distinguish from ordinary changed entries. - u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path> + u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path> .... Field Meaning @@ -446,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 7e5f995..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] [--] [<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 @@ -177,6 +184,10 @@ 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 +applied to the submodule. See linkgit:git-rev-list[1] for details on filter +specifications. -- set-branch (-b|--branch) <branch> [--] <path>:: set-branch (-d|--default) [--] <path>:: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index d5776ff..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 @@ -575,7 +575,7 @@ OPTIONS ------- --shared[=(false|true|umask|group|all|world|everybody)]:: ---template=<template_directory>:: +--template=<template-directory>:: Only used with the 'init' command. These are passed directly to 'git init'. @@ -678,7 +678,6 @@ config key: svn.authorsProg --strategy=<strategy>:: -p:: --rebase-merges:: ---preserve-merges (DEPRECATED):: These are only used with the 'dcommit' and 'rebase' commands. + Passed directly to 'git rebase' when using 'dcommit' if a @@ -727,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 5c438cd..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>:: @@ -137,8 +142,7 @@ should result in deletion of the path). The same as `--merge` option above, but changes the way the conflicting hunks are presented, overriding the `merge.conflictStyle` configuration variable. Possible values are - "merge" (default) and "diff3" (in addition to what is shown by - "merge" style, shows the original contents). + "merge" (default), "diff3", and "zdiff3". -q:: --quiet:: @@ -152,7 +156,7 @@ should result in deletion of the path). attached to a terminal, regardless of `--quiet`. -t:: ---track:: +--track [direct|inherit]:: When creating a new branch, set up "upstream" configuration. `-c` is implied. See `--track` in linkgit:git-branch[1] for details. @@ -172,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:: @@ -266,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 2853f16..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 @@ -351,6 +357,10 @@ unchanged". Note that "assume unchanged" bit is *not* set if the index (use `git update-index --really-refresh` if you want to mark them as "assume unchanged"). +Sometimes users confuse the assume-unchanged bit with the +skip-worktree bit. See the final paragraph in the "Skip-worktree bit" +section below for an explanation of the differences. + EXAMPLES -------- @@ -392,22 +402,47 @@ M foo.c SKIP-WORKTREE BIT ----------------- -Skip-worktree bit can be defined in one (long) sentence: When reading -an entry, if it is marked as skip-worktree, then Git pretends its -working directory version is up to date and read the index version -instead. - -To elaborate, "reading" means checking for file existence, reading -file attributes or file content. The working directory version may be -present or absent. If present, its content may match against the index -version or not. Writing is not affected by this bit, content safety -is still first priority. Note that Git _can_ update working directory -file, that is marked skip-worktree, if it is safe to do so (i.e. -working directory version matches index version) +Skip-worktree bit can be defined in one (long) sentence: Tell git to +avoid writing the file to the working directory when reasonably +possible, and treat the file as unchanged when it is not +present in the working directory. + +Note that not all git commands will pay attention to this bit, and +some only partially support it. + +The update-index flags and the read-tree capabilities relating to the +skip-worktree bit predated the introduction of the +linkgit:git-sparse-checkout[1] command, which provides a much easier +way to configure and handle the skip-worktree bits. If you want to +reduce your working tree to only deal with a subset of the files in +the repository, we strongly encourage the use of +linkgit:git-sparse-checkout[1] in preference to the low-level +update-index and read-tree primitives. + +The primary purpose of the skip-worktree bit is to enable sparse +checkouts, i.e. to have working directories with only a subset of +paths present. When the skip-worktree bit is set, Git commands (such +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 stage a +deletion for these files and `git commit -a` will not make a commit +deleting them either. Although this bit looks similar to assume-unchanged bit, its goal is -different from assume-unchanged bit's. Skip-worktree also takes -precedence over assume-unchanged bit when both are set. +different. The assume-unchanged bit is for leaving the file in the +working tree but having Git omit checking it for changes and presuming +that the file has not been changed (though if it can determine without +stat'ing the file that it has changed, it is free to record the +changes). skip-worktree tells Git to ignore the absence of the file, +avoid updating it when possible with commands that normally update +much of the working directory (e.g. `checkout`, `switch`, `pull`, +etc.), and not have its absence be recorded in commits. Note that in +sparse checkouts (setup by `git sparse-checkout` or by configuring +core.sparseCheckout to true), if a file is marked as skip-worktree in +the index but is found in the working tree, Git will clear the +skip-worktree bit for that file. SPLIT INDEX ----------- @@ -498,7 +533,9 @@ FILE SYSTEM MONITOR This feature is intended to speed up git operations for repos that have large working directories. -It enables git to work together with a file system monitor (see the +It enables git to work together with a file system monitor (see +linkgit:git-fsmonitor{litdd}daemon[1] +and the "fsmonitor-watchman" section of linkgit:githooks[5]) that can inform it as to what files have been modified. This enables git to avoid having to lstat() every file to find modified files. @@ -509,8 +546,8 @@ looking for new files. If you want to enable (or disable) this feature, it is easier to use the `core.fsmonitor` configuration variable (see -linkgit:git-config[1]) than using the `--fsmonitor` option to -`git update-index` in each repository, especially if you want to do so +linkgit:git-config[1]) than using the `--fsmonitor` option to `git +update-index` in each repository, especially if you want to do so across all repositories you use, because you can set the configuration variable in your `$HOME/.gitconfig` just once and have it affect all repositories you touch. 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 9822c1e..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. @@ -36,14 +36,25 @@ OPTIONS This fits with the HTTP POST request processing model where a program may read the request, write a response, and must exit. ---advertise-refs:: - Only the initial ref advertisement is output, and the program exits - immediately. This fits with the HTTP GET request model, where - no request content is received but a response must be produced. +--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 linkgit:gitprotocol-http[5] and "HTTP + Transport" in the linkgit:gitprotocol-v2[5] + documentation. Also understood by + linkgit:git-receive-pack[1]. <directory>:: The repository to sync from. +ENVIRONMENT +----------- + +`GIT_PROTOCOL`:: + Internal variable used for handshaking the wire protocol. Server + admins may need to configure some transports to allow this + variable to be passed. See the discussion in linkgit:git[1]. + SEE ALSO -------- linkgit:gitnamespaces[7] diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 6072f93..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 @@ -59,6 +68,32 @@ ifdef::git-default-pager[] The build you are using chose '{git-default-pager}' as the default. 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-version.txt b/Documentation/git-version.txt new file mode 100644 index 0000000..80fa775 --- /dev/null +++ b/Documentation/git-version.txt @@ -0,0 +1,28 @@ +git-version(1) +============== + +NAME +---- +git-version - Display version information about Git + +SYNOPSIS +-------- +[verse] +'git version' [--build-options] + +DESCRIPTION +----------- +With no options given, the version of 'git' is printed on the standard output. + +Note that `git --version` is identical to `git version` because the +former is internally converted into the latter. + +OPTIONS +------- +--build-options:: + Include additional information about how git was built for diagnostic + purposes. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 8d162b5..f2f996c 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser SYNOPSIS -------- [verse] -'git web{litdd}browse' [<options>] <url|file>... +'git web{litdd}browse' [<options>] (<URL>|<file>)... 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 66e67e6..2a240f5 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,8 +9,9 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>] -'git worktree list' [--porcelain] +'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> 'git worktree prune' [-n] [-v] [--expire <expire>] @@ -25,45 +26,49 @@ Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` a new working -tree is associated with the repository. This new working tree is called a -"linked working tree" as opposed to the "main working tree" prepared by -linkgit:git-init[1] or linkgit:git-clone[1]. -A repository has one main working tree (if it's not a -bare repository) and zero or more linked working trees. When you are done -with a linked working tree, remove it with `git worktree remove`. +tree is associated with the repository, along with additional metadata +that differentiates that working tree from others in the same repository. +The working tree, along with this metadata, is called a "worktree". + +This new worktree is called a "linked worktree" as opposed to the "main +worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1]. +A repository has one main worktree (if it's not a bare repository) and +zero or more linked worktrees. When you are done with a linked worktree, +remove it with `git worktree remove`. In its simplest form, `git worktree add <path>` automatically creates a new branch whose name is the final component of `<path>`, which is convenient if you plan to work on a new topic. For instance, `git worktree add ../hotfix` creates new branch `hotfix` and checks it out at -path `../hotfix`. To instead work on an existing branch in a new working -tree, use `git worktree add <path> <branch>`. On the other hand, if you -just plan to make some experimental changes or do testing without -disturbing existing development, it is often convenient to create a -'throwaway' working tree not associated with any branch. For instance, -`git worktree add -d <path>` creates a new working tree with a detached -`HEAD` at the same commit as the current branch. +path `../hotfix`. To instead work on an existing branch in a new worktree, +use `git worktree add <path> <branch>`. On the other hand, if you just +plan to make some experimental changes or do testing without disturbing +existing development, it is often convenient to create a 'throwaway' +worktree not associated with any branch. For instance, +`git worktree add -d <path>` creates a new worktree with a detached `HEAD` +at the same commit as the current branch. If a working tree is deleted without using `git worktree remove`, then its associated administrative files, which reside in the repository (see "DETAILS" below), will eventually be removed automatically (see `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run -`git worktree prune` in the main or any linked working tree to -clean up any stale administrative files. +`git worktree prune` in the main or any linked worktree to clean up any +stale administrative files. -If a linked working tree is stored on a portable device or network share -which is not always mounted, you can prevent its administrative files from -being pruned by issuing the `git worktree lock` command, optionally -specifying `--reason` to explain why the working tree is locked. +If the working tree for a linked worktree is stored on a portable device +or network share which is not always mounted, you can prevent its +administrative files from being pruned by issuing the `git worktree lock` +command, optionally specifying `--reason` to explain why the worktree is +locked. COMMANDS -------- add <path> [<commit-ish>]:: -Create `<path>` and checkout `<commit-ish>` into it. The new working directory -is linked to the current repository, sharing everything except working -directory specific files such as `HEAD`, `index`, etc. As a convenience, -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. +Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree +is linked to the current repository, sharing everything except per-worktree +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may +be a bare "`-`", which is synonymous with `@{-1}`. + If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, and neither `-b` nor `-B` nor `--detach` are used, but there does @@ -84,100 +89,107 @@ branches from there if `<branch>` is ambiguous but exists on the linkgit:git-config[1]. + If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, -then, as a convenience, the new working tree is associated with a branch -(call it `<branch>`) named after `$(basename <path>)`. If `<branch>` -doesn't 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 working tree, if it's not checked out anywhere -else, otherwise the command will refuse to create the working tree (unless -`--force` is used). +then, as a convenience, the new worktree is associated with a branch (call +it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't +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:: -List details of each working tree. The main working tree is listed first, -followed by each of the linked working trees. The output details include -whether the working tree is bare, the revision currently checked out, the +List details of each worktree. The main worktree is listed first, +followed by each of the linked worktrees. The output details include +whether the worktree is bare, the revision currently checked out, the branch currently checked out (or "detached HEAD" if none), "locked" if -the worktree is locked, "prunable" if the worktree can be pruned by `prune` -command. +the worktree is locked, "prunable" if the worktree can be pruned by the +`prune` command. lock:: -If a working tree is on a portable device or network share which -is not always mounted, lock it to prevent its administrative -files from being pruned automatically. This also prevents it from -being moved or deleted. Optionally, specify a reason for the lock -with `--reason`. +If a worktree is on a portable device or network share which is not always +mounted, lock it to prevent its administrative files from being pruned +automatically. This also prevents it from being moved or deleted. +Optionally, specify a reason for the lock with `--reason`. move:: -Move a working tree to a new location. Note that the main working tree -or linked working trees containing submodules cannot be moved with this -command. (The `git worktree repair` command, however, can reestablish -the connection with linked working trees if you move the main working -tree manually.) +Move a worktree to a new location. Note that the main worktree or linked +worktrees containing submodules cannot be moved with this command. (The +`git worktree repair` command, however, can reestablish the connection +with linked worktrees if you move the main worktree manually.) prune:: -Prune working tree information in `$GIT_DIR/worktrees`. +Prune worktree information in `$GIT_DIR/worktrees`. remove:: -Remove a working tree. Only clean working trees (no untracked files -and no modification in tracked files) can be removed. Unclean working -trees or ones with submodules can be removed with `--force`. The main -working tree cannot be removed. +Remove a worktree. Only clean worktrees (no untracked files and no +modification in tracked files) can be removed. Unclean worktrees or ones +with submodules can be removed with `--force`. The main worktree cannot be +removed. repair [<path>...]:: -Repair working tree administrative files, if possible, if they have -become corrupted or outdated due to external factors. +Repair worktree administrative files, if possible, if they have become +corrupted or outdated due to external factors. + -For instance, if the main working tree (or bare repository) is moved, -linked working trees will be unable to locate it. Running `repair` in -the main working tree will reestablish the connection from linked -working trees back to the main working tree. +For instance, if the main worktree (or bare repository) is moved, linked +worktrees will be unable to locate it. Running `repair` in the main +worktree will reestablish the connection from linked worktrees back to the +main worktree. + -Similarly, if a linked working tree is moved without using `git worktree -move`, the main working tree (or bare repository) will be unable to -locate it. Running `repair` within the recently-moved working tree will -reestablish the connection. If multiple linked working trees are moved, -running `repair` from any working tree with each tree's new `<path>` as -an argument, will reestablish the connection to all the specified paths. +Similarly, if the working tree for a linked worktree is moved without +using `git worktree move`, the main worktree (or bare repository) will be +unable to locate it. Running `repair` within the recently-moved worktree +will reestablish the connection. If multiple linked worktrees are moved, +running `repair` from any worktree with each tree's new `<path>` as an +argument, will reestablish the connection to all the specified paths. + -If both the main working tree and linked working trees have been moved -manually, then running `repair` in the main working tree and specifying the -new `<path>` of each linked working tree will reestablish all connections -in both directions. +If both the main worktree and linked worktrees have been moved manually, +then running `repair` in the main worktree and specifying the new `<path>` +of each linked worktree will reestablish all connections in both +directions. unlock:: -Unlock a working tree, allowing it to be pruned, moved or deleted. +Unlock a worktree, allowing it to be pruned, moved or deleted. OPTIONS ------- -f:: --force:: - By default, `add` refuses to create a new working tree when + By default, `add` refuses to create a new worktree when `<commit-ish>` is a branch name and is already checked out by - another working tree, or if `<path>` is already assigned to some - working tree but is missing (for instance, if `<path>` was deleted + another worktree, or if `<path>` is already assigned to some + worktree but is missing (for instance, if `<path>` was deleted manually). This option overrides these safeguards. To add a missing but - locked working tree path, specify `--force` twice. + locked worktree path, specify `--force` twice. + -`move` refuses to move a locked working tree unless `--force` is specified -twice. If the destination is already assigned to some other working tree but is +`move` refuses to move a locked worktree unless `--force` is specified +twice. If the destination is already assigned to some other worktree but is missing (for instance, if `<new-path>` was deleted manually), then `--force` allows the move to proceed; use `--force` twice if the destination is locked. + -`remove` refuses to remove an unclean working tree unless `--force` is used. -To remove a locked working tree, specify `--force` twice. +`remove` refuses to remove an unclean worktree unless `--force` is used. +To remove a locked worktree, specify `--force` twice. -b <new-branch>:: -B <new-branch>:: With `add`, create a new branch named `<new-branch>` starting at - `<commit-ish>`, and check out `<new-branch>` into the new working tree. + `<commit-ish>`, and check out `<new-branch>` into the new worktree. If `<commit-ish>` is omitted, it defaults to `HEAD`. By default, `-b` refuses to create a new branch if it already exists. `-B` overrides this safeguard, resetting `<new-branch>` to @@ -185,7 +197,7 @@ To remove a locked working tree, specify `--force` twice. -d:: --detach:: - With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" + With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. --[no-]checkout:: @@ -211,7 +223,7 @@ This can also be set up as the default behaviour by using the `--track` in linkgit:git-branch[1] for details. --lock:: - Keep the working tree locked after creation. This is the + Keep the worktree locked after creation. This is the equivalent of `git worktree lock` after `git worktree add`, but without a race condition. @@ -220,10 +232,21 @@ 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 - configuration. See below for details. + configuration. It is recommended to combine this with `-z`. + See below for details. + +-z:: + Terminate each line with a NUL rather than a newline when + `--porcelain` is specified with `list`. This makes it possible + to parse the output when a worktree path contains a newline + character. -q:: --quiet:: @@ -236,43 +259,43 @@ This can also be set up as the default behaviour by using the With `list`, output additional information about worktrees (see below). --expire <time>:: - With `prune`, only expire unused working trees older than `<time>`. + With `prune`, only expire unused worktrees older than `<time>`. + -With `list`, annotate missing working trees as prunable if they are -older than `<time>`. +With `list`, annotate missing worktrees as prunable if they are older than +`<time>`. --reason <string>:: - With `lock`, an explanation why the working tree is locked. + With `lock` or with `add --lock`, an explanation why the worktree + is locked. <worktree>:: - Working trees can be identified by path, either relative or - absolute. + Worktrees can be identified by path, either relative or absolute. + -If the last path components in the working tree's path is unique among -working trees, it can be used to identify a working tree. For example if -you only have two working trees, at `/abc/def/ghi` and `/abc/def/ggg`, -then `ghi` or `def/ghi` is enough to point to the former working tree. +If the last path components in the worktree's path is unique among +worktrees, it can be used to identify a worktree. For example if you only +have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or +`def/ghi` is enough to point to the former worktree. REFS ---- -In multiple working trees, some refs may be shared between all working -trees and some refs are local. One example is `HEAD` which is different for each -working tree. This section is about the sharing rules and how to access -refs of one working tree from another. - -In general, all pseudo refs are per working tree 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. - -Refs that are per working tree can still be accessed from another -working tree via two special paths, `main-worktree` and `worktrees`. The -former gives access to per-working tree refs of the main working tree, -while the latter to all linked working trees. +When using multiple worktrees, some refs are shared between all worktrees, +but others are specific to an individual worktree. One example is `HEAD`, +which is different for each worktree. This section is about the sharing +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`, `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 +access to per-worktree refs of the main worktree, while the latter to all +linked worktrees. For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good` -resolve to the same value as the main working tree's `HEAD` and +resolve to the same value as the main worktree's `HEAD` and `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or `worktrees/bar/refs/bisect/bad` are the same as `$GIT_COMMON_DIR/worktrees/foo/HEAD` and @@ -284,13 +307,13 @@ which will handle refs correctly. CONFIGURATION FILE ------------------ -By default, the repository `config` file is shared across all working -trees. If the config variables `core.bare` or `core.worktree` are -already present in the config file, they will be applied to the main -working trees only. +By default, the repository `config` file is shared across all worktrees. +If the config variables `core.bare` or `core.worktree` are present in the +common config file and `extensions.worktreeConfig` is disabled, then they +will be applied to the main worktree only. -In order to have configuration specific to working trees, you can turn -on the `worktreeConfig` extension, e.g.: +In order to have worktree-specific configuration, you can turn on the +`worktreeConfig` extension, e.g.: ------------ $ git config extensions.worktreeConfig true @@ -303,49 +326,54 @@ versions will refuse to access repositories with this extension. Note that in this file, the exception for `core.bare` and `core.worktree` is gone. If they exist in `$GIT_DIR/config`, you must move -them to the `config.worktree` of the main working tree. You may also -take this opportunity to review and move other configuration that you -do not want to share to all working trees: +them to the `config.worktree` of the main worktree. You may also take this +opportunity to review and move other configuration that you do not want to +share to all worktrees: + + - `core.worktree` should never be shared. + + - `core.bare` should not be shared if the value is `core.bare=true`. - - `core.worktree` and `core.bare` should never be shared + - `core.sparseCheckout` should not be shared, unless you are sure you + always use sparse checkout for all worktrees. - - `core.sparseCheckout` is recommended per working tree, unless you - are sure you always use sparse checkout for all working trees. +See the documentation of `extensions.worktreeConfig` in +linkgit:git-config[1] for more details. DETAILS ------- -Each linked working tree has a private sub-directory in the repository's +Each linked worktree has a private sub-directory in the repository's `$GIT_DIR/worktrees` directory. The private sub-directory's name is usually -the base name of the linked working tree's path, possibly appended with a +the base name of the linked worktree's path, possibly appended with a number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the command `git worktree add /path/other/test-next next` creates the linked -working tree in `/path/other/test-next` and also creates a +worktree in `/path/other/test-next` and also creates a `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` if `test-next` is already taken). -Within a linked working tree, `$GIT_DIR` is set to point to this private +Within a linked worktree, `$GIT_DIR` is set to point to this private directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and -`$GIT_COMMON_DIR` is set to point back to the main working tree's `$GIT_DIR` +`$GIT_COMMON_DIR` is set to point back to the main worktree's `$GIT_DIR` (e.g. `/path/main/.git`). These settings are made in a `.git` file located at -the top directory of the linked working tree. +the top directory of the linked worktree. Path resolution via `git rev-parse --git-path` uses either `$GIT_DIR` or `$GIT_COMMON_DIR` depending on the path. For example, in the -linked working tree `git rev-parse --git-path HEAD` returns +linked worktree `git rev-parse --git-path HEAD` returns `/path/main/.git/worktrees/test-next/HEAD` (not `/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 working trees, 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 `$GIT_DIR` or `$GIT_COMMON_DIR` when you need to directly access something inside `$GIT_DIR`. Use `git rev-parse --git-path` to get the final path. -If you manually move a linked working tree, you need to update the `gitdir` file -in the entry's directory. For example, if a linked working tree is moved +If you manually move a linked worktree, you need to update the `gitdir` file +in the entry's directory. For example, if a linked worktree is moved to `/newpath/test-next` and its `.git` file points to `/path/main/.git/worktrees/test-next`, then update `/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` @@ -354,10 +382,10 @@ automatically. To prevent a `$GIT_DIR/worktrees` entry from being pruned (which can be useful in some situations, such as when the -entry's working tree is stored on a portable device), use the +entry's worktree is stored on a portable device), use the `git worktree lock` command, which adds a file named `locked` to the entry's directory. The file contains the reason in -plain text. For example, if a linked working tree's `.git` file points +plain text. For example, if a linked worktree's `.git` file points to `/path/main/.git/worktrees/test-next` then a file named `/path/main/.git/worktrees/test-next/locked` will prevent the `test-next` entry from being pruned. See @@ -378,11 +406,11 @@ $ git worktree list /path/to/other-linked-worktree 1234abc (detached HEAD) ------------ -The command also shows annotations for each working tree, according to its state. +The command also shows annotations for each worktree, according to its state. These annotations are: - * `locked`, if the working tree is locked. - * `prunable`, if the working tree can be pruned via `git worktree prune`. + * `locked`, if the worktree is locked. + * `prunable`, if the worktree can be pruned via `git worktree prune`. ------------ $ git worktree list @@ -400,23 +428,24 @@ $ git worktree list --verbose /path/to/linked-worktree abcd1234 [master] /path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked /path/to/locked-worktree-with-reason 1234abcd (brancha) - locked: working tree path is mounted on a portable device + locked: worktree path is mounted on a portable device /path/to/prunable-worktree 5678abc1 (detached HEAD) prunable: gitdir file points to non-existent location ------------ Note that the annotation is moved to the next line if the additional information is available, otherwise it stays on the same line as the -working tree itself. +worktree itself. Porcelain Format ~~~~~~~~~~~~~~~~ -The porcelain format has a line per attribute. Attributes are listed with a +The porcelain format has a line per attribute. If `-z` is given then the lines +are terminated with NUL rather than a newline. Attributes are listed with a label and value separated by a single space. Boolean attributes (like `bare` and `detached`) are listed as a label only, and are present only if the value is true. Some attributes (like `locked`) can be listed as a label only or with a value depending upon whether a reason is available. The first -attribute of a working tree is always `worktree`, an empty line indicates the +attribute of a worktree is always `worktree`, an empty line indicates the end of the record. For example: ------------ @@ -449,7 +478,7 @@ prunable gitdir file points to non-existent location ------------ -If the lock reason contains "unusual" characters such as newline, they +Unless `-z` is used any "unusual" characters in the lock reason such as newlines are escaped and the entire reason is quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). For Example: @@ -468,7 +497,7 @@ demands that you fix something immediately. You might typically use linkgit:git-stash[1] to store your changes away temporarily, however, your working tree is in such a state of disarray (with new, moved, and removed files, and other bits and pieces strewn around) that you don't want to risk -disturbing any of it. Instead, you create a temporary linked working tree to +disturbing any of it. Instead, you create a temporary linked worktree to make the emergency fix, remove it when done, and then resume your earlier refactoring session. diff --git a/Documentation/git.txt b/Documentation/git.txt index 6dd241e..7a1b112 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,12 +9,11 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--help] [-C <path>] [-c <name>=<value>] +'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] - [--super-prefix=<path>] [--config-env=<name>=<envvar>] - <command> [<args>] + [--config-env=<name>=<envvar>] <command> [<args>] DESCRIPTION ----------- @@ -39,9 +38,15 @@ or https://git-scm.com/docs. OPTIONS ------- +-v:: --version:: Prints the Git suite version that the 'git' program came from. ++ +This option is internally converted to `git version ...` and accepts +the same options as the linkgit:git-version[1] command. If `--help` is +also given, it takes precedence over `--version`. +-h:: --help:: Prints the synopsis and a list of the most commonly used commands. If the option `--all` or `-a` is given then all @@ -91,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. + @@ -163,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). @@ -202,7 +211,7 @@ If you just want to run git as if it was started in `<path>` then use Do not perform optional operations that require locks. This is equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`. ---list-cmds=group[,group...]:: +--list-cmds=<group>[,<group>...]:: List commands by group. This is an internal/experimental option and may change or be removed in the future. Supported groups are: builtins, parseopt (builtin commands that use @@ -212,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 ------------ @@ -333,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 ----------------------- @@ -435,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 ~~~~~~~~~~~~~~~~~~ @@ -444,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. @@ -507,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 @@ -524,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 ~~~~~~~~~~~ @@ -591,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>. @@ -659,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) @@ -667,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`:: @@ -682,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. @@ -802,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`. + @@ -828,11 +877,16 @@ for full details. `GIT_TRACE_REDACT`:: By default, when tracing is activated, Git redacts the values of - cookies, the "Authorization:" header, and the "Proxy-Authorization:" - header. Set this variable to `0` to prevent this redaction. + cookies, the "Authorization:" header, the "Proxy-Authorization:" + 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 @@ -841,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 @@ -863,27 +922,36 @@ for full details. end user, to be recorded in the body of the reflog. `GIT_REF_PARANOIA`:: - If set to `1`, include broken or badly named refs when iterating - over lists of refs. In a normal, non-corrupted repository, this - does nothing. However, enabling it may help git to detect and - abort some operations in the presence of broken refs. Git sets - this variable automatically when performing destructive - operations like linkgit:git-prune[1]. You should not need to set - it yourself unless you want to be paranoid about making sure - an operation has touched every ref (e.g., because you are - cloning a repository to make a backup). + 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., + linkgit:git-prune[1]) are better off aborting rather than + ignoring broken refs (and thus considering the history they + point to as not worth saving). The default value is `1` (i.e., + be paranoid about detecting and aborting all operations). You + 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 @@ -892,11 +960,26 @@ 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 +pass over some transports. It will be propagated automatically when +accessing local repositories (i.e., `file://` or a filesystem path), as +well as over the `git://` protocol. For git-over-http, it should work +automatically in most configurations, but see the discussion in +linkgit:git-http-backend[1]. For git-over-ssh, the ssh server may need +to be configured to allow clients to pass this variable (e.g., by using +`AcceptEnv GIT_PROTOCOL` with OpenSSH). ++ +This configuration is optional. If the variable is not propagated, then +clients will fall back to the original "v0" protocol (but may miss out +on some performance improvements or features). This variable currently +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 @@ -964,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 @@ -1010,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 83fd4e1..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,24 +174,29 @@ unspecified. `eol` ^^^^^ -This attribute sets a specific line-ending style to be used in the -working directory. It enables end-of-line conversion without any -content checks, effectively setting the `text` attribute. Note that -setting this attribute on paths which are in the index with CRLF line -endings may make the paths to be considered dirty. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -756,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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -827,6 +878,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `kotlin` suitable for source code in the Kotlin language. + - `markdown` suitable for Markdown documents. - `matlab` suitable for source code in the MATLAB and Octave languages. @@ -1084,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 @@ -1103,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) @@ -1151,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 92e4ba6..7c70932 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -19,6 +19,15 @@ Many commands take revisions (most often "commits", but sometimes "tree-ish", depending on the context and command) and paths as their arguments. Here are the rules: + * Options come first and then args. + 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 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 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`, `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` @@ -28,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. @@ -72,24 +81,21 @@ 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` + * Splitting short options to separate words (prefer `git foo -a -b` to `git foo -ab`, the latter may not even work). - * when a command-line option takes an argument, use the 'stuck' form. In + * When a command-line option takes an argument, use the 'stuck' form. In other words, write `git foo -oArg` instead of `git foo -o Arg` for short options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` for long options. An option that takes optional option-argument must be written in the 'stuck' form. - * when you give a revision parameter to a command, make sure the parameter is + * When you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree. E.g. do not write `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. - * many commands allow a long option `--option` to be abbreviated + * Many commands allow a long option `--option` to be abbreviated only to their unique prefix (e.g. if there is no other option whose name begins with `opt`, you may be able to spell `--opt` to invoke the `--option` flag), but you should fully spell them out 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 758bf39..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 ------------------- @@ -132,7 +146,7 @@ because the hostnames differ. Nor would it match `foo.example.com`; Git compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for `http://example.com` would not match: Git compares the protocols exactly. However, you may use wildcards in -the domain name and other pattern matching techniques as with the `http.<url>.*` +the domain name and other pattern matching techniques as with the `http.<URL>.*` options. If the "pattern" URL does include a path component, then this too must match @@ -147,7 +161,7 @@ CONFIGURATION OPTIONS Options for a credential context can be configured either in `credential.*` (which applies to all credentials), or -`credential.<url>.*`, where <url> matches the context as described +`credential.<URL>.*`, where <URL> matches the context as described above. The following options are available in either location: @@ -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/gitfaq.txt b/Documentation/gitfaq.txt index afdaeab..8c1f2d5 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -275,7 +275,7 @@ best to always use a regular merge commit. [[merge-two-revert-one]] If I make a change on two branches but revert it on one, why does the merge of those branches include the change?:: - By default, when Git does a merge, it uses a strategy called the recursive + By default, when Git does a merge, it uses a strategy called the `ort` strategy, which does a fancy three-way merge. In such a case, when Git performs the merge, it considers exactly three points: the two heads and a third point, called the _merge base_, which is usually the common ancestor of diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt index bac558d..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. + +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 + +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,15 +86,26 @@ 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. The only known capability is `object-format`, which specifies -the hash algorithm in use, and can take the same values as the -`extensions.objectFormat` configuration value. +bundle' to abort. + +* `object-format` specifies the hash algorithm in use, and can take the same + values as the `extensions.objectFormat` configuration value. + +* `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 87971c2..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', 'T' }) (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', 'V' }) [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,12 +160,24 @@ 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. + +== Historical Notes: + +The Generation Data (GDA2) and Generation Data Overflow (GDO2) chunks have +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 8d2f42f..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. @@ -294,6 +319,25 @@ Pack file entry: <+ All 4-byte numbers are in network order. +== pack-*.mtimes files have the format: + +All 4-byte numbers are in network byte order. + + - A 4-byte magic number '0x4d544d45' ('MTME'). + + - A 4-byte version identifier (= 1). + + - A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256). + + - A table of 4-byte unsigned integers. The ith value is the + modification time (mtime) of the ith object in the corresponding + pack by lexicographic (index) order. The mtimes count standard + epoch seconds. + + - A trailer, containing a checksum of the corresponding packfile, + and a checksum of all of the above (each having length according + to the specified hash function). + == multi-pack-index (MIDX) files have the following format: The multi-pack-index files refer to multiple pack-files and loose objects. @@ -337,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 @@ -346,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 @@ -376,6 +430,11 @@ CHUNK DATA: [Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'}) 8-byte offsets into large packfiles. + [Optional] Bitmap pack order (ID: {'R', 'I', 'D', 'X'}) + A list of MIDX positions (one per object in the MIDX, num_objects in + total, each a 4-byte unsigned integer in network byte order), sorted + according to their relative bitmap/pseudo-pack positions. + TRAILER: Index checksum of the above contents. @@ -456,9 +515,167 @@ In short, a MIDX's pseudo-pack is the de-duplicated concatenation of objects in packs stored by the MIDX, laid out in pack order, and the packs arranged in MIDX order (with the preferred pack coming first). -Finally, note that the MIDX's reverse index is not stored as a chunk in -the multi-pack-index itself. This is done because the reverse index -includes the checksum of the pack or MIDX to which it belongs, which -makes it impossible to write in the MIDX. To avoid races when rewriting -the MIDX, a MIDX reverse index includes the MIDX's checksum in its -filename (e.g., `multi-pack-index-xyz.rev`). +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 2c9406a..d4d3a31 100644 --- a/Documentation/technical/signature-format.txt +++ b/Documentation/gitformat-signature.txt @@ -1,17 +1,56 @@ -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. - -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`. +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: + +`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 +that the signature applies to), and sometimes appear in the value of +an object header (e.g. a merge commit that merged a signed tag would +have the entire tag contents on its "mergetag" header). In the case +of the latter, the usual multi-line formatting rule for object +headers applies. I.e. the second and subsequent lines are prefixed +with a SP to signal that the line is continued from the previous +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 +primarily to highlight extra whitespace at the end of some lines. The signed payload and the way the signature is embedded depends on the type of the object resp. transaction. @@ -78,7 +117,7 @@ author A U Thor <author@example.com> 1465981137 +0000 committer C O Mitter <committer@example.com> 1465981137 +0000 gpgsig -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 - + $ iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA @@ -128,13 +167,13 @@ mergetag object 04b871796dc0420f8e7561a895b52484b701d51a type commit tag signedtag tagger C O Mitter <committer@example.com> 1465981006 +0000 - + $ signed tag - + $ signed tag message body -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 - + $ iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods @@ -184,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 b51959f..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 ~~~~~~~~~~~~~~~~~~ @@ -698,6 +751,10 @@ and "0" meaning they were not. Only one parameter should be set to "1" when the hook runs. The hook running passing "1", "1" should not be possible. +SEE ALSO +-------- +linkgit:git-hook[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index f8a1fc2..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 @@ -155,7 +157,7 @@ accessed from the index or a tree versus from the filesystem. EXAMPLES -------- - - The pattern `hello.*` matches any file or folder + - The pattern `hello.*` matches any file or directory whose name begins with `hello.`. If one wants to restrict this only to the directory and not in its subdirectories, one can prepend the pattern with a slash, i.e. `/hello.*`; @@ -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 96d89ea..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,9 +236,12 @@ 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 +linkgit:git-upload-pack[1]. + Dumb Server Response ^^^^^^^^^^^^^^^^^^^^ Dumb servers MUST respond with the dumb server reply format. @@ -362,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 @@ -374,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 @@ -406,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 @@ -495,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) @@ -509,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 1040d85..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,8 @@ 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`. In all cases 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. Git Transport @@ -58,12 +70,14 @@ SSH and File Transport When using either the ssh:// or file:// transport, the GIT_PROTOCOL environment variable must be set explicitly to include "version=2". +The server may need to be configured to allow this environment variable +to pass. 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 @@ -81,6 +95,12 @@ A v2 server would reply: Subsequent requests are then made directly to the service `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack). +Uses the `--http-backend-info-refs` option to +linkgit:git-upload-pack[1]. + +The server may need to be configured to pass this header's contents via +the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`. + Capability Advertisement ------------------------ @@ -116,11 +136,11 @@ command can be requested at a time. empty-request = flush-pkt command-request = command capability-list - [command-args] + delim-pkt + command-args flush-pkt command = PKT-LINE("command=" key LF) - command-args = delim-pkt - *command-specific-arg + command-args = *command-specific-arg command-specific-args are packet line framed arguments defined by each individual command. @@ -179,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: @@ -190,7 +210,11 @@ ls-refs takes in the following arguments: Show peeled tags. ref-prefix <prefix> When specified, only references having a prefix matching one of - the provided prefixes are displayed. + the provided prefixes are displayed. Multiple instances may be + given, in which case references matching any prefix will be + shown. Note that this is purely for optimization; a server MAY + show refs not matching the prefix if it chooses, and clients + should filter the result themselves. If the 'unborn' feature is advertised the following argument can be included in the client's request. @@ -221,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: @@ -322,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: @@ -337,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 @@ -510,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 @@ -520,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 ~~~~~~~~~~~ @@ -553,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 891c8da..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) @@ -226,10 +226,10 @@ Workflow for a third party library ---------------------------------- # Add a submodule - git submodule add <url> <path> + 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 59ef5ce..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 +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 3cc9b03..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. @@ -547,7 +547,7 @@ like this: # make the front page an internal rewrite to the gitweb script RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] - # look for a public_git folder in unix users' home + # look for a public_git directory in unix users' home # http://git.example.org/~<user>/ RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 47cf97f..5930526 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -394,7 +394,7 @@ request to do so by mail. Such a request looks like ------------------------------------- Please pull from - <url> <branch> + <URL> <branch> ------------------------------------- In that case, 'git pull' can do the fetch and merge in one go, as @@ -403,7 +403,7 @@ follows. .Push/pull: Merging remote topics [caption="Recipe: "] ===================================== -`git pull <url> <branch>` +`git pull <URL> <branch>` ===================================== Occasionally, the maintainer may get merge conflicts when they try to @@ -440,7 +440,7 @@ merge because you cannot format-patch merges): .format-patch/am: Keeping topics up to date [caption="Recipe: "] ===================================== -`git pull --rebase <url> <branch>` +`git pull --rebase <URL> <branch>` ===================================== You can then fix the conflicts during the rebase. Presumably you have diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index c077971..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 @@ -312,7 +353,7 @@ Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", and many other commands to limit the scope of operations to some subset of the tree or -worktree. See the documentation of each command for whether +working tree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows: + @@ -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 @@ -446,7 +491,7 @@ exclude;; interface than the <<def_plumbing,plumbing>>. [[def_per_worktree_ref]]per-worktree ref:: - Refs that are per-<<def_working_tree,worktree>>, rather than + Refs that are per-<<def_worktree,worktree>>, rather than global. This is presently only <<def_HEAD,HEAD>> and any refs that start with `refs/bisect/`, but might later include other unusual refs. @@ -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>>. @@ -669,3 +747,12 @@ The most notable example is `HEAD`. The tree of actual checked out files. The working tree normally contains the contents of the <<def_HEAD,HEAD>> commit's tree, plus any local changes that you have made but not yet committed. + +[[def_worktree]]worktree:: + A repository can have zero (i.e. bare repository) or one or + more worktrees attached to it. One "worktree" consists of a + "working tree" and repository metadata, most of which are + shared among other worktrees of a single repository, and + some of which are maintained separately per worktree + (e.g. the index, HEAD and pseudorefs like MERGE_HEAD, + per-worktree refs and per-worktree configuration file). 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-gitlink.perl b/Documentation/lint-gitlink.perl index b22a367..1c61dd9 100755 --- a/Documentation/lint-gitlink.perl +++ b/Documentation/lint-gitlink.perl @@ -5,11 +5,12 @@ use warnings; # Parse arguments, a simple state machine for input like: # -# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...] +# <file-to-check.txt> <valid-files-to-link-to> --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...] my %TXT; my %SECTION; my $section; my $lint_these = 0; +my $to_check = shift @ARGV; for my $arg (@ARGV) { if (my ($sec) = $arg =~ /^--section=(\d+)$/s) { $section = $sec; @@ -30,13 +31,14 @@ sub report { my ($pos, $line, $target, $msg) = @_; substr($line, $pos) = "' <-- HERE"; $line =~ s/^\s+//; - print "$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\n"; - print "$ARGV:$.:\t'$line\n"; + print STDERR "$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\n"; + print STDERR "$ARGV:$.:\t'$line\n"; $exit_code = 1; } @ARGV = sort values %TXT; -die "BUG: Nothing to process!" unless @ARGV; +die "BUG: No list of valid linkgit:* files given" unless @ARGV; +@ARGV = $to_check; while (<>) { my $line = $_; while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) { diff --git a/Documentation/lint-man-end-blurb.perl b/Documentation/lint-man-end-blurb.perl index d69312e..6bdb13a 100755 --- a/Documentation/lint-man-end-blurb.perl +++ b/Documentation/lint-man-end-blurb.perl @@ -6,7 +6,7 @@ use warnings; my $exit_code = 0; sub report { my ($target, $msg) = @_; - print "error: $target: $msg\n"; + print STDERR "error: $target: $msg\n"; $exit_code = 1; } diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl index b05f915..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++, @@ -46,7 +49,7 @@ my $SECTION_RX = do { my $exit_code = 0; sub report { my ($msg) = @_; - print "$ARGV:$.: $msg\n"; + print STDERR "$ARGV:$.: $msg\n"; $exit_code = 1; } 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 eb0aabd..3eaefc4 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -2,6 +2,9 @@ --no-commit:: Perform the merge and commit the result. This option can be used to override --no-commit. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] + With --no-commit perform the merge and stop just before creating a merge commit, to give the user a chance to inspect and further @@ -39,6 +42,7 @@ set to `no` at the beginning of them. to `MERGE_MSG` before being passed on to the commit machinery in the case of a merge conflict. +ifdef::git-merge[] --ff:: --no-ff:: --ff-only:: @@ -47,6 +51,22 @@ set to `no` at the beginning of them. default unless merging an annotated (and possibly signed) tag that is not stored in its natural place in the `refs/tags/` hierarchy, in which case `--no-ff` is assumed. +endif::git-merge[] +ifdef::git-pull[] +--ff-only:: + Only update to the new history if there is no divergent local + history. This is the default when no method for reconciling + divergent histories is provided (via the --rebase=* flags). + +--ff:: +--no-ff:: + When merging rather than rebasing, specifies how a merge is + handled when the merged-in history is already a descendant of + the current history. If merging is requested, `--ff` is the + default unless merging an annotated (and possibly signed) tag + that is not stored in its natural place in the `refs/tags/` + hierarchy, in which case `--no-ff` is assumed. +endif::git-pull[] + With `--ff`, when possible resolve the merge as a fast-forward (only update the branch pointer to match the merged branch; do not create a @@ -55,9 +75,11 @@ descendant of the current history), create a merge commit. + With `--no-ff`, create a merge commit in all cases, even when the merge could instead be resolved as a fast-forward. +ifdef::git-merge[] + With `--ff-only`, resolve the merge as a fast-forward when possible. When not possible, refuse to merge and exit with a non-zero status. +endif::git-merge[] -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -73,6 +95,9 @@ When not possible, refuse to merge and exit with a non-zero status. In addition to branch names, populate the log message with one-line descriptions from at most <n> actual commits that are being merged. See also linkgit:git-fmt-merge-msg[1]. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] + With --no-log do not list one-line descriptions from the actual commits being merged. @@ -102,18 +127,26 @@ With --no-squash perform the merge and commit the result. This option can be used to override --squash. + With --squash, --commit is not allowed, and will fail. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] ---no-verify:: - This option bypasses the pre-merge and commit-msg hooks. +--[no-]verify:: + By default, the pre-merge and commit-msg hooks are run. + When `--no-verify` is given, these are bypassed. See also linkgit:githooks[5]. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] -s <strategy>:: --strategy=<strategy>:: Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no `-s` option, a built-in list of strategies - is used instead ('git merge-recursive' when merging a single - head, 'git merge-octopus' otherwise). + is used instead (`ort` when merging a single head, + `octopus` otherwise). -X <option>:: --strategy-option=<option>:: @@ -127,6 +160,10 @@ With --squash, --commit is not allowed, and will fail. default trust model, this means the signing key has been signed by a trusted key. If the tip commit of the side branch is not signed with a valid key, the merge is aborted. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] --summary:: --no-summary:: @@ -154,7 +191,8 @@ endif::git-pull[] --autostash:: --no-autostash:: Automatically create a temporary stash entry before the operation - begins, and apply it after the operation ends. This means + 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 merge might result in non-trivial conflicts. @@ -166,3 +204,7 @@ endif::git-pull[] projects that started their lives independently. As that is a very rare occasion, no configuration variable to enable this by default exists and will not be added. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 2912de7..5fc54ec 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -6,28 +6,23 @@ backend 'merge strategies' to be chosen with `-s` option. Some strategies can also take their own options, which can be passed by giving `-X<option>` arguments to `git merge` and/or `git pull`. -resolve:: - This can only resolve two heads (i.e. the current branch - and another branch you pulled from) using a 3-way merge - algorithm. It tries to carefully detect criss-cross - merge ambiguities and is considered generally safe and - fast. - -recursive:: - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames, but currently cannot make use of detected - copies. This is the default merge strategy when pulling - or merging one branch. +ort:: + This is the default merge strategy when pulling or merging one + branch. This strategy can only resolve two heads using a + 3-way merge algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a merged + tree of the common ancestors and uses that as the reference + tree for the 3-way merge. This has been reported to result in + fewer merge conflicts without causing mismerges by tests done + on actual merge commits taken from Linux 2.6 kernel + development history. Additionally this strategy can detect + and handle merges involving renames. It does not make use of + detected copies. The name for this algorithm is an acronym + ("Ostensibly Recursive's Twin") and came from the fact that it + was written as a replacement for the previous default + algorithm, `recursive`. + -The 'recursive' strategy can take the following options: +The 'ort' strategy can take the following options: ours;; This option forces conflicting hunks to be auto-resolved cleanly by @@ -43,19 +38,6 @@ theirs;; This is the opposite of 'ours'; note that, unlike 'ours', there is no 'theirs' merge strategy to confuse this merge option with. -patience;; - With this option, 'merge-recursive' spends a little extra time - to avoid mismerges that sometimes occur due to unimportant - matching lines (e.g., braces from distinct functions). Use - this when the branches to be merged have diverged wildly. - See also linkgit:git-diff[1] `--patience`. - -diff-algorithm=[patience|minimal|histogram|myers];; - Tells 'merge-recursive' to use a different diff algorithm, which - 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`. - ignore-space-change;; ignore-all-space;; ignore-space-at-eol;; @@ -84,11 +66,6 @@ no-renormalize;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. -no-renames;; - Turn off rename detection. This overrides the `merge.renames` - configuration variable. - See also linkgit:git-diff[1] `--no-renames`. - find-renames[=<n>];; Turn on rename detection, optionally setting the similarity threshold. This is the default. This overrides the @@ -105,6 +82,46 @@ subtree[=<path>];; is prefixed (or stripped from the beginning) to make the shape of two trees to match. +recursive:: + This can only resolve two heads using a 3-way merge + algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a + merged tree of the common ancestors and uses that as + the reference tree for the 3-way merge. This has been + reported to result in fewer merge conflicts without + causing mismerges by tests done on actual merge commits + taken from Linux 2.6 kernel development history. + Additionally this can detect and handle merges involving + renames. It does not make use of detected copies. This was + the default strategy for resolving two heads from Git v0.99.9k + until v2.33.0. ++ +The 'recursive' strategy takes the same options as 'ort'. However, +there are three additional options that 'ort' ignores (not documented +above) that are potentially useful with the 'recursive' strategy: + +patience;; + Deprecated synonym for `diff-algorithm=patience`. + +diff-algorithm=[patience|minimal|histogram|myers];; + Use a different diff algorithm while merging, which 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`. Note that `ort` + specifically uses `diff-algorithm=histogram`, while `recursive` + defaults to the `diff.algorithm` config setting. + +no-renames;; + Turn off rename detection. This overrides the `merge.renames` + configuration variable. + See also linkgit:git-diff[1] `--no-renames`. + +resolve:: + This can only resolve two heads (i.e. the current branch + and another branch you pulled from) using a 3-way merge + algorithm. It tries to carefully detect criss-cross + merge ambiguities. It does not handle renames. + octopus:: This resolves cases with more than two heads, but refuses to do a complex merge that needs manual resolution. It is @@ -121,13 +138,13 @@ ours:: the 'recursive' merge strategy. subtree:: - This is a modified recursive strategy. When merging trees A and + This is a modified `ort` strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common ancestor tree. -With the strategies that use 3-way merge (including the default, 'recursive'), +With the strategies that use 3-way merge (including the default, 'ort'), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.txt new file mode 100644 index 0000000..befa86d --- /dev/null +++ b/Documentation/mergetools/vimdiff.txt @@ -0,0 +1,195 @@ +Description +^^^^^^^^^^^ + +When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4 +windows layout distributed in the following way: +.... +------------------------------------------ +| | | | +| LOCAL | BASE | REMOTE | +| | | | +------------------------------------------ +| | +| MERGED | +| | +------------------------------------------ +.... +`LOCAL`, `BASE` and `REMOTE` are read-only buffers showing the contents of the +conflicting file in specific commits ("commit you are merging into", "common +ancestor commit" and "commit you are merging from" respectively) + +`MERGED` is a writable buffer where you have to resolve the conflicts (using the +other read-only buffers as a reference). Once you are done, save and exit Vim as +usual (`:wq`) or, if you want to abort, exit using `:cq`. + +Layout configuration +^^^^^^^^^^^^^^^^^^^^ + +You can change the windows layout used by Vim by setting configuration variable +`mergetool.vimdiff.layout` which accepts a string where the following separators +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 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 as follows (you can use parentheses to change +it): + + `@` > `+` > `/` > `,` + +Let's see some examples to understand how it works: + +* `layout = "(LOCAL,BASE,REMOTE)/MERGED"` ++ +-- +This is exactly the same as the default layout we have already seen. + +Note that `/` has precedence over `,` and thus the parenthesis are not +needed in this case. The next layout definition is equivalent: + + layout = "LOCAL,BASE,REMOTE / MERGED" +-- +* `layout = "LOCAL,MERGED,REMOTE"` ++ +-- +If, for some reason, we are not interested in the `BASE` buffer. +.... +------------------------------------------ +| | | | +| | | | +| LOCAL | MERGED | REMOTE | +| | | | +| | | | +------------------------------------------ +.... +-- +* `layout = "MERGED"` ++ +-- +Only the `MERGED` buffer will be shown. Note, however, that all the other +ones are still loaded in vim, and you can access them with the "buffers" +command. +.... +------------------------------------------ +| | +| | +| MERGED | +| | +| | +------------------------------------------ +.... +-- +* `layout = "@LOCAL,REMOTE"` ++ +-- +When `MERGED` is not present in the layout, you must "mark" one of the +buffers with an asterisk. That will become the buffer you need to edit and +save after resolving the conflicts. +.... +------------------------------------------ +| | | +| | | +| | | +| LOCAL | REMOTE | +| | | +| | | +| | | +------------------------------------------ +.... +-- +* `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"` ++ +-- +Three tabs will open: the first one is a copy of the default layout, while +the other two only show the differences between (`BASE` and `LOCAL`) and +(`BASE` and `REMOTE`) respectively. +.... +------------------------------------------ +| <TAB #1> | TAB #2 | TAB #3 | | +------------------------------------------ +| | | | +| LOCAL | BASE | REMOTE | +| | | | +------------------------------------------ +| | +| MERGED | +| | +------------------------------------------ +.... +.... +------------------------------------------ +| TAB #1 | <TAB #2> | TAB #3 | | +------------------------------------------ +| | | +| | | +| | | +| BASE | LOCAL | +| | | +| | | +| | | +------------------------------------------ +.... +.... +------------------------------------------ +| TAB #1 | TAB #2 | <TAB #3> | | +------------------------------------------ +| | | +| | | +| | | +| BASE | REMOTE | +| | | +| | | +| | | +------------------------------------------ +.... +-- +* `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED"` ++ +-- +Same as the previous example, but adds a fourth tab with the same +information as the first tab, with a different layout. +.... +--------------------------------------------- +| TAB #1 | TAB #2 | TAB #3 | <TAB #4> | +--------------------------------------------- +| LOCAL | | +|---------------------| | +| BASE | MERGED | +|---------------------| | +| REMOTE | | +--------------------------------------------- +.... +Note how in the third tab definition we need to use parentheses to make `,` +have precedence over `/`. +-- + +Variants +^^^^^^^^ + +Instead of `--tool=vimdiff`, you can also use one of these other variants: + + * `--tool=gvimdiff`, to open gVim instead of Vim. + + * `--tool=nvimdiff`, to open Neovim instead of Vim. + +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` (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: +`vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout. +In other words, using `--tool=[g,n,]vimdiffx` is the same as using +`--tool=[g,n,]vimdiff` and setting configuration variable +`mergetool.[g,n,]vimdiff.layout` to... + + * `x=1`: `"@LOCAL, REMOTE"` + * `x=2`: `"LOCAL, MERGED, REMOTE"` + * `x=3`: `"MERGED"` + +Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL, +MERGED and REMOTE). 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 ef6bd42..8ee940b 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -20,7 +20,7 @@ built-in formats: * 'oneline' - <hash> <title line> + <hash> <title-line> + This is designed to be as compact as possible. @@ -29,17 +29,17 @@ This is designed to be as compact as possible. commit <hash> Author: <author> - <title line> + <title-line> * 'medium' commit <hash> Author: <author> - Date: <author date> + Date: <author-date> - <title line> + <title-line> - <full commit message> + <full-commit-message> * 'full' @@ -47,25 +47,25 @@ This is designed to be as compact as possible. Author: <author> Commit: <committer> - <title line> + <title-line> - <full commit message> + <full-commit-message> * 'fuller' commit <hash> Author: <author> - AuthorDate: <author date> + AuthorDate: <author-date> Commit: <committer> - CommitDate: <committer date> + CommitDate: <committer-date> - <title line> + <title-line> - <full commit message> + <full-commit-message> * 'reference' - <abbrev hash> (<title line>, <short author date>) + <abbrev-hash> (<title-line>, <short-author-date>) + This format is used to refer to another commit in a commit message and is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`. By default, @@ -78,10 +78,10 @@ placeholders, its output is not affected by other options like From <hash> <date> From: <author> - Date: <author date> - Subject: [PATCH] <title line> + Date: <author-date> + Subject: [PATCH] <title-line> - <full commit message> + <full-commit-message> * 'mboxrd' + @@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is shown e.g. with `git log --raw`. To get full object names in a raw diff format, use `--no-abbrev`. -* 'format:<string>' +* 'format:<format-string>' + -The 'format:<string>' format allows you to specify which information +The 'format:<format-string>' format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with '%n' instead of '\n'. @@ -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,14 +224,37 @@ 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. +** 'abbrev=<number>': Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. ** 'match=<pattern>': Only consider tags matching the given `glob(7)` pattern, excluding the "refs/tags/" prefix. ** 'exclude=<pattern>': Do not consider tags matching the given @@ -265,20 +300,13 @@ 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. + -The boolean options accept an optional value `[=<BOOL>]`. The values -`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean" -sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean -option is given with no value, it's enabled. -+ -** 'key=<K>': only show trailers with specified key. Matching is done +** 'key=<key>': only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the `only` option so that @@ -286,25 +314,23 @@ option is given with no value, it's enabled. desired it can be disabled with `only=false`. E.g., `%(trailers:key=Reviewed-by)` shows trailer lines with key `Reviewed-by`. -** 'only[=<BOOL>]': select whether non-trailer lines from the trailer +** '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 )` shows all trailer lines whose key is "Ticket" separated by a comma and a space. -** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold` +** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold` option was given. E.g., `%(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. +** '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 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 @@ -313,6 +339,11 @@ insert an empty string unless we are traversing reflog entries (e.g., by decoration format if `--decorate` was not already provided on the command line. +The boolean options accept an optional value `[=<bool-value>]`. The values +`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean +option is given with no value, it's enabled. + If you add a `+` (plus sign) after '%' of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 27ddaf8..23888cd 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -33,20 +33,22 @@ people using 80-column terminals. used together. --encoding=<encoding>:: - The commit objects record the encoding used for the log message + Commit objects record the character encoding used for the log message in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this defaults to UTF-8. Note that if an object claims to be encoded in `X` and we are outputting in `X`, we will output the object verbatim; this means that invalid sequences in the original - commit may be copied to the output. + commit may be copied to the output. Likewise, if iconv(3) fails + to convert the commit, we will quietly output the original + object verbatim. --expand-tabs=<n>:: --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`, @@ -71,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 @@ -85,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 24569b0..00ccf68 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -25,6 +25,11 @@ ordering and formatting options, such as `--reverse`. --after=<date>:: Show commits more recent than a specific date. +--since-as-filter=<date>:: + Show all commits more recent than a specific date. This visits + all commits in the range, rather than stopping at the first commit which + is older than a specific date. + --until=<date>:: --before=<date>:: Show commits older than a specific date. @@ -51,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 @@ -67,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:: @@ -122,22 +127,34 @@ again. Equivalent forms are `--min-parents=0` (any commit has 0 or more parents) and `--max-parents=-1` (negative numbers denote no upper limit). --first-parent:: - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. + When finding commits to include, follow only the first + parent commit upon seeing a merge commit. This option + can give a better overview when viewing the evolution of + a particular topic branch, because merges into a topic + branch tend to be only about adjusting to updated upstream + from time to time, and this option allows you to ignore + the individual commits brought in to your history by such + a merge. ifdef::git-log[] + This option also changes default diff format for merge commits to `first-parent`, see `--diff-merges=first-parent` for details. endif::git-log[] +--exclude-first-parent-only:: + When finding commits to exclude (with a '{caret}'), follow only + the first parent commit upon seeing a merge commit. + This can be used to find the set of changes in a topic branch + from the point where it diverged from the remote branch, given + that arbitrary merges can be valid topic branch changes. + --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 @@ -182,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>`. @@ -215,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:: @@ -229,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 @@ -236,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:: @@ -285,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 @@ -310,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 @@ -376,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. @@ -555,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: + @@ -591,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. @@ -646,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` @@ -842,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 @@ -872,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 @@ -887,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. @@ -959,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 @@ -1047,18 +1114,18 @@ omitted. has no effect. `--date=format:...` feeds the format `...` to your system `strftime`, -except for %z and %Z, which are handled internally. +except for %s, %z, and %Z, which are handled internally. Use `--date=format:%c` to show the date in your system locale's 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 8be4f4d..665c496 100644 --- a/Documentation/technical/api-error-handling.txt +++ b/Documentation/technical/api-error-handling.txt @@ -1,12 +1,34 @@ Error reporting in git ====================== -`BUG`, `die`, `usage`, `error`, and `warning` report errors of +`BUG`, `bug`, `die`, `usage`, `error`, and `warning` report errors of various kinds. - `BUG` is for failed internal assertions that should never happen, i.e. a bug in git itself. +- `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but + prints a "BUG" message instead of calling `abort()`. ++ +A call to `bug()` will then result in a "real" call to the `BUG()` +function, either explicitly by invoking `BUG_if_bug()` after call(s) +to `bug()`, or implicitly at `exit()` time where we'll check if we +encountered any outstanding `bug()` invocations. ++ +If there were no prior calls to `bug()` before invoking `BUG_if_bug()` +the latter is a NOOP. The `BUG_if_bug()` function takes the same +arguments as `BUG()` itself. Calling `BUG_if_bug()` explicitly isn't +necessary, but ensures that we die as soon as possible. ++ +If you know you had prior calls to `bug()` then calling `BUG()` itself +is equivalent to calling `BUG_if_bug()`, the latter being a wrapper +calling `BUG()` if we've set a flag indicating that we've called +`bug()`. ++ +This is for the convenience of APIs who'd like to potentially report +more than one "bug", such as the optbug() validation in +parse-options.c. + - `die` is for fatal application errors. It prints a message to the user and exits with status 128. @@ -24,7 +46,7 @@ various kinds. 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 5a60bbf..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 -------------- @@ -198,11 +235,6 @@ There are some macros to easily define options: The filename will be prefixed by passing the filename along with the prefix argument of `parse_options()` to `prefix_filename()`. -`OPT_ARGUMENT(long, &int_var, description)`:: - Introduce a long-option argument that will be kept in `argv[]`. - If this option was seen, `int_var` will be set to one (except - if a `NULL` pointer was passed). - `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: Recognize numerical options like -123 and feed the integer as if it was an argument to the function given by `func_ptr`. @@ -241,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 037a91c..de5fc25 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -5,7 +5,7 @@ information to stderr or a file. The Trace2 feature is inactive unless explicitly enabled by enabling one or more Trace2 Targets. The Trace2 API is intended to replace the existing (Trace1) -printf-style tracing provided by the existing `GIT_TRACE` and +`printf()`-style tracing provided by the existing `GIT_TRACE` and `GIT_TRACE_PERFORMANCE` facilities. During initial implementation, Trace2 and Trace1 may operate in parallel. @@ -24,8 +24,8 @@ for example. Trace2 is controlled using `trace2.*` config values in the system and global config files and `GIT_TRACE2*` environment variables. Trace2 does -not read from repo local or worktree config files or respect `-c` -command line config settings. +not read from repo local or worktree config files, nor does it respect +`-c` command line config settings. == Trace2 Targets @@ -34,8 +34,8 @@ Format details are given in a later section. === The Normal Format Target -The normal format target is a tradition printf format and similar -to GIT_TRACE format. This format is enabled with the `GIT_TRACE2` +The normal format target is a traditional `printf()` format and similar +to the `GIT_TRACE` format. This format is enabled with the `GIT_TRACE2` environment variable or the `trace2.normalTarget` system or global config setting. @@ -69,8 +69,8 @@ $ cat ~/log.normal === The Performance Format Target The performance format target (PERF) is a column-based format to -replace GIT_TRACE_PERFORMANCE and is suitable for development and -testing, possibly to complement tools like gprof. This format is +replace `GIT_TRACE_PERFORMANCE` and is suitable for development and +testing, possibly to complement tools like `gprof`. This format is enabled with the `GIT_TRACE2_PERF` environment variable or the `trace2.perfTarget` system or global config setting. @@ -128,7 +128,7 @@ yields ------------ $ cat ~/log.event -{"event":"version","sid":"sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"2","exe":"2.20.1.155.g426c96fcdb"} +{"event":"version","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"3","exe":"2.20.1.155.g426c96fcdb"} {"event":"start","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621027Z","file":"common-main.c","line":39,"t_abs":0.001173,"argv":["git","version"]} {"event":"cmd_name","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621122Z","file":"git.c","line":432,"name":"version","hierarchy":"version"} {"event":"exit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621236Z","file":"git.c","line":662,"t_abs":0.001227,"code":0} @@ -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. @@ -170,54 +168,9 @@ Some functions have a `_va_fl()` suffix to indicate that they also take a `va_list` argument. Some functions have a `_printf_fl()` suffix to indicate that they also -take a varargs argument. - -There are CPP wrapper macros and ifdefs 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)`. +take a `printf()` style format with a variable number of arguments. -=== 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 @@ -234,7 +187,7 @@ Events are written as lines of the form: is the event name. `<event-message>`:: - is a free-form printf message intended for human consumption. + is a free-form `printf()` message intended for human consumption. + Note that this may contain embedded LF or CRLF characters that are not escaped, so the event may spill across multiple lines. @@ -300,7 +253,7 @@ This field is in anticipation of in-proc submodules in the future. indicate a broad category, such as "index" or "status". `<perf-event-message>`:: - is a free-form printf message intended for human consumption. + is a free-form `printf()` message intended for human consumption. ------------ 15:33:33.532712 wt-status.c:2310 | d0 | main | region_enter | r1 | 0.126064 | | status | label:print @@ -391,7 +344,7 @@ only present on the "start" and "atexit" events. { "event":"version", ... - "evt":"2", # EVENT format version + "evt":"3", # EVENT format version "exe":"2.20.1.155.g426c96fcdb" # git version } ------------ @@ -465,8 +418,8 @@ completed.) ------------ `"error"`:: - This event is emitted when one of the `BUG()`, `error()`, `die()`, - `warning()`, or `usage()` functions are called. + This event is emitted when one of the `BUG()`, `bug()`, `error()`, + `die()`, `warning()`, or `usage()` functions are called. + ------------ { @@ -493,6 +446,20 @@ about specific error arguments. } ------------ +`"cmd_ancestry"`:: + This event contains the text command name for the parent (and earlier + generations of parents) of the current process, in an array ordered from + nearest parent to furthest great-grandparent. It may not be implemented + on all platforms. ++ +------------ +{ + "event":"cmd_ancestry", + ... + "ancestry":["bash","tmux: server","systemd"] +} +------------ + `"cmd_name"`:: This event contains the command name for this git process and the hierarchy of commands from parent git processes. @@ -519,7 +486,7 @@ these special values are used: ------------ `"cmd_mode"`:: - This event, when present, describes the command variant This + This event, when present, describes the command variant. This event may be emitted more than once. + ------------ @@ -574,7 +541,7 @@ with "?". `"child_exit"`:: This event is generated after the current process has returned - from the waitpid() and collected the exit information from the + from the `waitpid()` and collected the exit information from the child. + ------------ @@ -595,10 +562,50 @@ process may be a shell script which doesn't have a session-id.) + Note that the `t_rel` field contains the observed run time in seconds for the child process (starting before the fork/exec/spawn and -stopping after the waitpid() and includes OS process creation overhead). +stopping after the `waitpid()` and includes OS process creation overhead). So this time will be slightly larger than the atexit time reported by the child process itself. +`"child_ready"`:: + This event is generated after the current process has started + a background process and released all handles to it. ++ +------------ +{ + "event":"child_ready", + ... + "child_id":2, + "pid":14708, # child PID + "ready":"ready", # child ready state + "t_rel":0.110605 # observed run-time of child process +} +------------ ++ +Note that the session-id of the child process is not available to +the current/spawning process, so the child's PID is reported here as +a hint for post-processing. (But it is only a hint because the child +process may be a shell script which doesn't have a session-id.) ++ +This event is generated after the child is started in the background +and given a little time to boot up and start working. If the child +starts up normally while the parent is still waiting, the "ready" +field will have the value "ready". +If the child is too slow to start and the parent times out, the field +will have the value "timeout". +If the child starts but the parent is unable to probe it, the field +will have the value "error". ++ +After the parent process emits this event, it will release all of its +handles to the child process and treat the child as a background +daemon. So even if the child does eventually finish booting up, +the parent will not emit an updated event. ++ +Note that the `t_rel` field contains the observed run time in seconds +when the parent released the child process into the background. +The child is assumed to be a long-running daemon process and may +outlive the parent process. So the parent's child event times should +not be compared to the child's atexit times. + `"exec"`:: This event is generated before git attempts to `exec()` another command rather than starting a child process. @@ -631,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). + ------------ { @@ -644,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. + ------------ { @@ -663,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" } @@ -761,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 @@ -895,7 +970,7 @@ atexit elapsed:3.868970 code:0 Regions:: - Regions can be use to time an interesting section of code. + Regions can be used to time an interesting section of code. + ---------------- void wt_status_collect(struct wt_status *s) @@ -1049,9 +1124,9 @@ Thread Events:: Thread messages added to a thread-proc. + -For example, the multithreaded preload-index code can be +For example, the multi-threaded preload-index code can be instrumented with a region around the thread pool and then -per-thread start and exit events within the threadproc. +per-thread start and exit events within the thread-proc. + ---------------- static void *preload_thread(void *_data) @@ -1151,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 @@ -1160,11 +1328,11 @@ as each thread starts and allocates TLS storage. There are a few issues to resolve before we can completely switch to Trace2. -* Updating existing tests that assume GIT_TRACE format messages. +* Updating existing tests that assume `GIT_TRACE` format messages. -* How to best handle custom GIT_TRACE_<key> messages? +* How to best handle custom `GIT_TRACE_<key>` messages? -** The GIT_TRACE_<key> mechanism allows each <key> to write to a +** The `GIT_TRACE_<key>` mechanism allows each <key> to write to a different file (in addition to just stderr). ** Do we want to maintain that ability or simply write to the existing diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt index f8c18a0..f5d2009 100644 --- a/Documentation/technical/bitmap-format.txt +++ b/Documentation/technical/bitmap-format.txt @@ -1,93 +1,157 @@ GIT bitmap v1 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 with full closure - (i.e. where every single object in the packfile can find - its parent links inside the same packfile). 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. 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 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 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** 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. +== Pack and multi-pack bitmaps + +Bitmaps store reachability information about the set of objects in a packfile, +or a multi-pack index (MIDX). The former is defined obviously, and the latter is +defined as the union of objects in packs contained in the MIDX. + +A bitmap may belong to either one pack, or the repository's multi-pack index (if +it exists). A repository may have at most one bitmap. + +An object is uniquely described by its bit position within a bitmap: + + - If the bitmap belongs to a packfile, the __n__th bit corresponds to + the __n__th object in pack order. For a function `offset` which maps + objects to their byte offset within a pack, pack order is defined as + follows: + + o1 <= o2 <==> offset(o1) <= offset(o2) + + - If the bitmap belongs to a MIDX, the __n__th bit corresponds to the + __n__th object in MIDX order. With an additional function `pack` which + maps objects to the pack they were selected from by the MIDX, MIDX order + 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 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 +difference is the interpretation of the bits, which is described above. + +Certain bitmap extensions are supported (see: Appendix B). No extensions are +required for bitmaps corresponding to packfiles. For bitmaps that correspond to +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: + + ** {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 @@ -100,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 @@ -146,10 +210,11 @@ Name-hash cache --------------- If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains -a cache of 32-bit values, one per object in the pack. The value at +a cache of 32-bit values, one per object in the pack/MIDX. The value at position `i` is the hash of the pathname at which the `i`th object -(counting in index order) in the pack can be found. This can be fed -into the delta heuristics to compare objects with similar pathnames. +(counting in index or multi-pack index order) in the pack/MIDX can be found. +This can be fed into the delta heuristics to compare objects with similar +pathnames. The hash algorithm used is: @@ -162,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/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt index 49b83ef..029ee2c 100644 --- a/Documentation/technical/directory-rename-detection.txt +++ b/Documentation/technical/directory-rename-detection.txt @@ -2,9 +2,9 @@ Directory rename detection ========================== Rename detection logic in diffcore-rename that checks for renames of -individual files is aggregated and analyzed in merge-recursive for cases -where combinations of renames indicate that a full directory has been -renamed. +individual files is also aggregated there and then analyzed in either +merge-ort or merge-recursive for cases where combinations of renames +indicate that a full directory has been renamed. Scope of abilities ------------------ @@ -88,9 +88,11 @@ directory rename detection support in: Folks have requested in the past that `git diff` detect directory renames and somehow simplify its output. It is not clear whether this would be desirable or how the output should be simplified, so this was - simply not implemented. Further, to implement this, directory rename - detection logic would need to move from merge-recursive to - diffcore-rename. + simply not implemented. Also, while diffcore-rename has most of the + logic for detecting directory renames, some of the logic is still found + within merge-ort and merge-recursive. Fully supporting directory + rename detection in diffs would require copying or moving the remaining + bits of logic to the diff machinery. * am 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/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index fb68897..f2221d2 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -17,13 +17,14 @@ is not feasible due to storage space or excessive repack times. The multi-pack-index (MIDX for short) stores a list of objects and their offsets into multiple packfiles. It contains: -- A list of packfile names. -- A sorted list of object IDs. -- A list of metadata for the ith object ID including: - - A value j referring to the jth packfile. - - An offset within the jth packfile for the object. -- If large offsets are required, we use another list of large +* A list of packfile names. +* A sorted list of object IDs. +* A list of metadata for the ith object ID including: +** A value j referring to the jth packfile. +** An offset within the jth packfile for the object. +* If large offsets are required, we use another list of large offsets similar to version 2 pack-indexes. +- An optional list of objects in pseudo-pack order (used with MIDX bitmaps). Thus, we can provide O(log N) lookup time for any number of packfiles. @@ -36,7 +37,9 @@ Design Details directory of an alternate. It refers only to packfiles in that same directory. -- The core.multiPackIndex config setting must be on to consume MIDX files. +- The core.multiPackIndex config setting must be on (which is the + default) to consume MIDX files. Setting it to `false` prevents + Git from reading a MIDX file, even if one exists. - The file format includes parameters for the object ID hash function, so a future change of hash algorithm does not require @@ -71,14 +74,10 @@ Future Work still reducing the number of binary searches required for object lookups. -- The reachability bitmap is currently paired directly with a single - packfile, using the pack-order as the object order to hopefully - compress the bitmaps well using run-length encoding. This could be - extended to pair a reachability bitmap with a multi-pack-index. If - the multi-pack-index is extended to store a "stable object order" +- If the multi-pack-index is extended to store a "stable object order" (a function Order(hash) = integer that is constant for a given hash, - even as the multi-pack-index is updated) then a reachability bitmap - could point to a multi-pack-index and be updated independently. + even as the multi-pack-index is updated) then MIDX bitmaps could be + updated independently of the MIDX. - Packfiles can be marked as "special" using empty files that share the initial name but replace ".pack" with ".keep" or ".promisor". @@ -89,11 +88,6 @@ Future Work helpful to organize packfiles by object type (commit, tree, blob, etc.) and use this metadata to help that maintenance. -- The partial clone feature records special "promisor" packs that - may point to objects that are not stored locally, but available - on request to a server. The multi-pack-index does not currently - track these promisor packs. - Related Links ------------- [0] https://bugs.chromium.org/p/git/issues/detail?id=6 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 a0dd7c6..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. @@ -181,6 +181,9 @@ Fetching Missing Objects currently fetches all objects referred to by the requested objects, even though they are not necessary. +- Fetching with `--refetch` will request a complete new filtered packfile from + the remote, which can be used to change a filter without needing to + dynamically fetch missing objects. Using many promisor remotes --------------------------- @@ -253,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 @@ -262,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." @@ -319,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 d7c3b64..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, @@ -443,7 +443,7 @@ Obj block format Object blocks are optional. Writers may choose to omit object blocks, especially if readers will not use the object name to ref mapping. -Object blocks use unique, abbreviated 2-32 object name keys, mapping to +Object blocks use unique, abbreviated 2-31 byte object name keys, mapping to ref blocks containing references pointing to that object directly, or as the peeled value of an annotated tag. Like ref blocks, object blocks use the file's standard block size. The abbreviation length is available in 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 af5f9fc..580f233 100644 --- a/Documentation/technical/rerere.txt +++ b/Documentation/technical/rerere.txt @@ -14,9 +14,9 @@ conflicts before writing them to the rerere database. Different conflict styles and branch names are normalized by stripping the labels from the conflict markers, and removing the common ancestor -version from the `diff3` conflict style. Branches that are merged -in different order are normalized by sorting the conflict hunks. More -on each of those steps in the following sections. +version from the `diff3` or `zdiff3` conflict styles. Branches that +are merged in different order are normalized by sorting the conflict +hunks. More on each of those steps in the following sections. Once these two normalization operations are applied, a conflict ID is calculated based on the normalized conflict, which is later used by @@ -42,8 +42,8 @@ get a conflict like the following: >>>>>>> AC Doing the analogous with AC2 (forking a branch ABAC2 off of branch AB -and then merging branch AC2 into it), using the diff3 conflict style, -we get a conflict like the following: +and then merging branch AC2 into it), using the diff3 or zdiff3 +conflict style, we get a conflict like the following: <<<<<<< HEAD B @@ -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 bd184cd..bf17012 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -26,14 +26,16 @@ config file would appear like this: ------------ [remote "<name>"] - url = <url> + url = <URL> pushurl = <pushurl> push = <refspec> fetch = <refspec> ------------ 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> @@ -67,10 +69,10 @@ This file should have the following format: ------------ - <url>#<head> + <URL>#<head> ------------ -`<url>` is required; `#<head>` is optional. +`<URL>` is required; `#<head>` is optional. Depending on the operation, git will use one of the following refspecs, if you don't provide one on the command line. 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 9624059..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: @@ -3190,7 +3217,7 @@ that *updated* thing--the old state that you added originally ends up not being pointed to by any commit or tree, so it's now a dangling blob object. -Similarly, when the "recursive" merge strategy runs, and finds that +Similarly, when the "ort" merge strategy runs, and finds that there are criss-cross merges and thus more than one merge base (which is fairly unusual, but it does happen), it will generate one temporary midway tree (or possibly even more, if you had lots of criss-crossing @@ -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. |