diff options
Diffstat (limited to 'Documentation')
368 files changed, 18891 insertions, 8680 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 3ef54e0adb..9022d48355 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -13,3 +13,5 @@ mergetools-*.txt manpage-base-url.xsl SubmittingPatches.txt tmp-doc-diff/ +GIT-ASCIIDOCFLAGS +/GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 48aa4edfbd..227f46ae40 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -75,7 +75,7 @@ For shell scripts specifically (not exhaustive): - If you want to find out if a command is available on the user's $PATH, you should use 'type <command>', instead of 'which <command>'. - The output of 'which' is not machine parseable and its exit code + The output of 'which' is not machine parsable and its exit code is not reliable across platforms. - We use POSIX compliant parameter substitutions and avoid bashisms; @@ -91,16 +91,10 @@ For shell scripts specifically (not exhaustive): - No shell arrays. - - No strlen ${#parameter}. - - No pattern replacement ${parameter/pattern/string}. - We use Arithmetic Expansion $(( ... )). - - Inside Arithmetic Expansion, spell shell variables with $ in front - of them, as some shells do not grok $((x)) while accepting $(($x)) - just fine (e.g. dash older than 0.5.4). - - We do not use Process Substitution <(list) or >(list). - Do not write control structures on a single line with semicolon. @@ -118,6 +112,24 @@ For shell scripts specifically (not exhaustive): do this fi + - If a command sequence joined with && or || or | spans multiple + lines, put each command on a separate line and put && and || and | + operators at the end of each line, rather than the start. This + means you don't need to use \ to join lines, since the above + operators imply the sequence isn't finished. + + (incorrect) + grep blob verify_pack_result \ + | awk -f print_1.awk \ + | sort >actual && + ... + + (correct) + grep blob verify_pack_result | + awk -f print_1.awk | + sort >actual && + ... + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell @@ -177,10 +189,30 @@ 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. That means that you should not use C99 - initializers, even if a lot of compilers grok it. + including old ones. You should not use features from newer C + standard, even if your compiler groks them. + + There are a few exceptions to this guideline: + + . since early 2012 with e1327023ea, we have been using an enum + definition whose last element is followed by a comma. This, like + an array initializer that ends with a trailing comma, can be used + to reduce the patch noise when adding a new identifier at the end. + + . since mid 2017 with cbc0f81d, we have been using designated + initializers for struct (e.g. "struct t v = { .val = 'a' };"). - - Variables have to be declared at the beginning of the block. + . 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. + + - 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. @@ -200,6 +232,18 @@ For C programs: while( condition ) func (bar+1); + - Do not explicitly compare an integral value with constant 0 or '\0', + or a pointer value with constant NULL. For instance, to validate that + counted array <ptr, cnt> is initialized but has no elements, write: + + if (!ptr || cnt) + BUG("empty array expected"); + + and not: + + if (ptr == NULL || cnt != 0); + BUG("empty array expected"); + - We avoid using braces unnecessarily. I.e. if (bla) { @@ -358,7 +402,10 @@ For C programs: string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - - When you come up with an API, document it. + - When you come up with an API, document its functions and structures + in the header file that exposes the API to its callers. Use what is + in "strbuf.h" as a model for the appropriate tone and level of + detail. - The first #include in C files, except in platform specific compat/ implementations, must be either "git-compat-util.h", "cache.h" or @@ -391,6 +438,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + For Perl programs: - Most of the C guidelines above apply. @@ -559,11 +612,14 @@ Writing Documentation: or commands: Literal examples (e.g. use of command-line options, command names, - branch names, configuration and environment variables) must be - typeset in monospace (i.e. wrapped with backticks): + 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` diff --git a/Documentation/Makefile b/Documentation/Makefile index a42dcfc745..15d9d04f31 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -7,12 +7,14 @@ ARTICLES = SP_ARTICLES = OBSOLETE_HTML = +-include GIT-EXCLUDED-PROGRAMS + MAN1_TXT += $(filter-out \ + $(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \ $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) MAN1_TXT += git.txt MAN1_TXT += gitk.txt -MAN1_TXT += gitremote-helpers.txt MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt @@ -28,22 +30,29 @@ MAN7_TXT += gitcredentials.txt MAN7_TXT += gitcvs-migration.txt MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.txt +MAN7_TXT += gitfaq.txt MAN7_TXT += gitglossary.txt MAN7_TXT += gitnamespaces.txt +MAN7_TXT += gitremote-helpers.txt MAN7_TXT += gitrevisions.txt MAN7_TXT += gitsubmodules.txt MAN7_TXT += gittutorial-2.txt MAN7_TXT += gittutorial.txt MAN7_TXT += gitworkflows.txt +ifdef MAN_FILTER +MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) +else MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) +MAN_FILTER = $(MAN_TXT) +endif + MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) GIT_MAN_REF = master OBSOLETE_HTML += everyday.html OBSOLETE_HTML += git-remote-helpers.html -DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML) ARTICLES += howto-index ARTICLES += git-tools @@ -68,11 +77,14 @@ SP_ARTICLES += howto/maintain-git 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 += MyFirstContribution +TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches 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 @@ -88,11 +100,13 @@ TECH_DOCS += technical/trivial-merge SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index -DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) +ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) +HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML) +DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML)) -DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT)) -DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT)) -DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT)) +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT))) +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT))) +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT))) prefix ?= $(HOME) bindir ?= $(prefix)/bin @@ -111,7 +125,8 @@ ASCIIDOC_HTML = xhtml11 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_CONF = -f asciidoc.conf ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ - -agit_version=$(GIT_VERSION) + -amanversion=$(GIT_VERSION) \ + -amanmanual='Git Manual' -amansource='Git' TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) MANPAGE_XSL = manpage-normal.xsl @@ -135,32 +150,9 @@ endif -include ../config.mak.autogen -include ../config.mak -# -# For docbook-xsl ... -# -1.68.1, no extra settings are needed? -# 1.69.0, set ASCIIDOC_ROFF? -# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? -# 1.71.1, set ASCIIDOC_ROFF? -# 1.72.0, set DOCBOOK_XSL_172. -# 1.73.0-, no extra settings are needed -# - -ifdef DOCBOOK_XSL_172 -ASCIIDOC_EXTRA += -a git-asciidoc-no-roff -MANPAGE_XSL = manpage-1.72.xsl -else - ifndef ASCIIDOC_ROFF - # docbook-xsl after 1.72 needs the regular XSL, but will not - # pass-thru raw roff codes from asciidoc.conf, so turn them off. - ASCIIDOC_EXTRA += -a git-asciidoc-no-roff - endif -endif ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif -ifdef DOCBOOK_SUPPRESS_SP -XMLTO_EXTRA += -m manpage-suppress-sp.xsl -endif # Newer DocBook stylesheet emits warning cruft in the output when # this is not set, and if set it shows an absolute link. Older @@ -185,11 +177,13 @@ ifdef USE_ASCIIDOCTOR ASCIIDOC = asciidoctor ASCIIDOC_CONF = ASCIIDOC_HTML = xhtml5 -ASCIIDOC_DOCBOOK = docbook45 +ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' DBLATEX_COMMON = +XMLTO_EXTRA += --skip-validation +XMLTO_EXTRA += -x manpage.xsl endif SHELL_PATH ?= $(SHELL) @@ -285,7 +279,7 @@ docdep_prereqs = \ mergetools-list.made $(mergetools_txt) \ cmd-list.made $(cmds_txt) -doc.dep : $(docdep_prereqs) $(wildcard *.txt) build-docdep.perl +doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl $(QUIET_GEN)$(RM) $@+ $@ && \ $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ mv $@+ $@ @@ -323,6 +317,15 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ date >$@ +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) + +GIT-ASCIIDOCFLAGS: FORCE + @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ + if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \ + echo >&2 " * new asciidoc flags"; \ + echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \ + fi + clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info @@ -332,30 +335,31 @@ clean: $(RM) SubmittingPatches.txt $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) manpage-base-url.xsl + $(RM) GIT-ASCIIDOCFLAGS -$(MAN_HTML): %.html : %.txt asciidoc.conf +$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_HTML) -d manpage -o $@+ $< && \ mv $@+ $@ -$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_HTML) -o $@+ $< && \ mv $@+ $@ manpage-base-url.xsl: manpage-base-url.xsl.in - sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ + $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt asciidoc.conf +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d manpage -o $@+ $< && \ mv $@+ $@ -user-manual.xml: user-manual.txt user-manual.conf +user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(TXT_TO_XML) -d book -o $@+ $< && \ mv $@+ $@ @@ -365,7 +369,8 @@ technical/api-index.txt: technical/api-index-skel.txt \ $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf +$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \ + asciidoc.conf GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt SubmittingPatches.txt: SubmittingPatches @@ -422,7 +427,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt WEBDOC_DEST = /pub/software/scm/git/docs howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt +$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ sed -e '1,/^$$/d' $< | \ $(TXT_TO_HTML) - >$@+ && \ @@ -456,4 +461,9 @@ print-man1: lint-docs:: $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl +ifeq ($(wildcard po/Makefile),po/Makefile) +doc-l10n install-l10n:: + $(MAKE) -C po $@ +endif + .PHONY: FORCE diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt new file mode 100644 index 0000000000..427274df4d --- /dev/null +++ b/Documentation/MyFirstContribution.txt @@ -0,0 +1,1217 @@ +My First Contribution to the Git Project +======================================== +:sectanchors: + +[[summary]] +== Summary + +This is a tutorial demonstrating the end-to-end workflow of creating a change to +the Git tree, sending it for review, and making changes based on comments. + +[[prerequisites]] +=== Prerequisites + +This tutorial assumes you're already fairly familiar with using Git to manage +source code. The Git workflow steps will largely remain unexplained. + +[[related-reading]] +=== Related Reading + +This tutorial aims to summarize the following documents, but the reader may find +useful additional context: + +- `Documentation/SubmittingPatches` +- `Documentation/howto/new-command.txt` + +[[getting-help]] +=== Getting Help + +If you get stuck, you can seek help in the following places. + +==== git@vger.kernel.org + +This is the main Git project mailing list where code reviews, version +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 +available to view in a browser. + +==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] + +This mailing list is targeted to new contributors and was created as a place to +post questions and receive answers outside of the public eye of the main list. +Veteran contributors who are especially interested in helping mentor newcomers +are present on the list. In order to avoid search indexers, group membership is +required to view messages; anyone can join and no approval is required. + +==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode + +This IRC channel is for conversations between Git contributors. If someone is +currently online and knows the answer to your question, you can receive help +in real time. Otherwise, you can read the +https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see +whether someone answered you. IRC does not allow offline private messaging, so +if you try to private message someone and then log out of IRC, they cannot +respond to you. It's better to ask your questions in the channel so that you +can be answered if you disconnect and so that others can learn from the +conversation. + +[[getting-started]] +== Getting Started + +[[cloning]] +=== Clone the Git Repository + +Git is mirrored in a number of locations. Clone the repository from one of them; +https://git-scm.com/downloads suggests one of the best places to clone from is +the mirror on GitHub. + +---- +$ git clone https://github.com/git/git git +$ cd git +---- + +[[dependencies]] +=== Installing Dependencies + +To build Git from source, you need to have a handful of dependencies installed +on your system. For a hint of what's needed, you can take a look at +`INSTALL`, paying close attention to the section about Git's dependencies on +external programs and libraries. That document mentions a way to "test-drive" +our freshly built Git without installing; that's the method we'll be using in +this tutorial. + +Make sure that your environment has everything you need by building your brand +new clone of Git from the above step: + +---- +$ make +---- + +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + +[[identify-problem]] +=== Identify Problem to Solve + +//// +Use + to indicate fixed-width here; couldn't get ` to work nicely with the +quotes around "Pony Saying 'Um, Hello'". +//// +In this tutorial, we will add a new command, +git psuh+, short for ``Pony Saying +`Um, Hello''' - a feature which has gone unimplemented despite a high frequency +of invocation during users' typical daily workflow. + +(We've seen some other effort in this space with the implementation of popular +commands such as `sl`.) + +[[setup-workspace]] +=== Set Up Your Workspace + +Let's start by making a development branch to work on our changes. Per +`Documentation/SubmittingPatches`, since a brand new command is a new feature, +it's fine to base your work on `master`. However, in the future for bugfixes, +etc., you should check that document and base it on the appropriate branch. + +For the purposes of this document, we will base all our work on the `master` +branch of the upstream project. Create the `psuh` branch you will use for +development like so: + +---- +$ git checkout -b psuh origin/master +---- + +We'll make a number of commits here in order to demonstrate how to send a topic +with multiple patches up for review simultaneously. + +[[code-it-up]] +== Code It Up! + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/psuh. + +[[add-new-command]] +=== Adding a New Command + +Lots of the subcommands are written as builtins, which means they are +implemented in C and compiled into the main `git` executable. Implementing the +very simple `psuh` command as a built-in will demonstrate the structure of the +codebase, the internal API, and the process of working together as a contributor +with the reviewers and maintainer to integrate this change into the system. + +Built-in subcommands are typically implemented in a function named "cmd_" +followed by the name of the subcommand, in a source file named after the +subcommand and contained within `builtin/`. So it makes sense to implement your +command in `builtin/psuh.c`. Create that file, and within it, write the entry +point for your command in a function matching the style and signature: + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix) +---- + +We'll also need to add the declaration of psuh; open up `builtin.h`, find the +declaration for `cmd_pull`, and add a new line for `psuh` immediately before it, +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`. + +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. + +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 +localizable. Take a look at `po/README` under "Marking strings for translation". +Throughout the tutorial, we will mark strings for translation as necessary; you +should also do so when writing your user-facing commands in the future. + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix) +{ + printf(_("Pony saying hello goes here.\n")); + return 0; +} +---- + +Let's try to build it. Open `Makefile`, find where `builtin/pull.o` is added +to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in +alphabetical order. Once you've done so, move to the top-level directory and +build simply with `make`. Also add the `DEVELOPER=1` variable to turn on +some additional warnings: + +---- +$ echo DEVELOPER=1 >config.mak +$ make +---- + +NOTE: When you are developing the Git project, it's preferred that you use the +`DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn +it off, but it's a good idea to mention the problem to the mailing list. + +Great, now your new command builds happily on its own. But nobody invokes it. +Let's change that. + +The list of commands lives in `git.c`. We can register a new command by adding +a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string +with the command name, a function pointer to the command implementation, and a +setup option flag. For now, let's keep mimicking `push`. Find the line where +`cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new +line in alphabetical order (immediately before `cmd_pull`). + +The options are documented in `builtin.h` under "Adding a new built-in." Since +we hope to print some data about the user's current workspace context later, +we need a Git directory, so choose `RUN_SETUP` as your only option. + +Go ahead and build again. You should see a clean build, so let's kick the tires +and see if it works. There's a binary you can use to test with in the +`bin-wrappers` directory. + +---- +$ ./bin-wrappers/git psuh +---- + +Check it out! You've got a command! Nice work! Let's commit this. + +`git status` reveals modified `Makefile`, `builtin.h`, and `git.c` as well as +untracked `builtin/psuh.c` and `git-psuh`. First, let's take care of the binary, +which should be ignored. Open `.gitignore` in your editor, find `/git-pull`, and +add an entry for your new command in alphabetical order: + +---- +... +/git-prune-packed +/git-psuh +/git-pull +/git-push +/git-quiltimport +/git-range-diff +... +---- + +Checking `git status` again should show that `git-psuh` has been removed from +the untracked list and `.gitignore` has been added to the modified list. Now we +can stage and commit: + +---- +$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore +$ git commit -s +---- + +You will be presented with your editor in order to write a commit message. Start +the commit with a 50-column or less subject line, including the name of the +component you're working on, followed by a blank line (always required) and then +the body of your commit message, which should provide the bulk of the context. +Remember to be explicit and provide the "Why" of your change, especially if it +couldn't easily be understood from your diff. When editing your commit message, +don't remove the Signed-off-by line which was added by `-s` above. + +---- +psuh: add a built-in by popular demand + +Internal metrics indicate this is a command many users expect to be +present. So here's an implementation to help drive customer +satisfaction and engagement: a pony which doubtfully greets the user, +or, a Pony Saying "Um, Hello" (PSUH). + +This commit message is intentionally formatted to 72 columns per line, +starts with a single line as "commit message subject" that is written as +if to command the codebase to do something (add this, teach a command +that). The body of the message is designed to add information about the +commit that is not readily deduced from reading the associated diff, +such as answering the question "why?". + +Signed-off-by: A U Thor <author@example.com> +---- + +Go ahead and inspect your new commit with `git show`. "psuh:" indicates you +have modified mainly the `psuh` command. The subject line gives readers an idea +of what you've changed. The sign-off line (`-s`) indicates that you agree to +the Developer's Certificate of Origin 1.1 (see the +`Documentation/SubmittingPatches` +++[[dco]]+++ header). + +For the remainder of the tutorial, the subject line only will be listed for the +sake of brevity. However, fully-fleshed example commit messages are available +on the reference implementation linked at the top of this document. + +[[implementation]] +=== Implementation + +It's probably useful to do at least something besides printing out a string. +Let's start by having a look at everything we get. + +Modify your `cmd_psuh` implementation to dump the args you're passed, keeping +existing `printf()` calls in place: + +---- + int i; + + ... + + printf(Q_("Your args (there is %d):\n", + "Your args (there are %d):\n", + argc), + argc); + for (i = 0; i < argc; i++) + printf("%d: %s\n", i, argv[i]); + + printf(_("Your current working directory:\n<top-level>%s%s\n"), + prefix ? "/" : "", prefix ? prefix : ""); + +---- + +Build and try it. As you may expect, there's pretty much just whatever we give +on the command line, including the name of our command. (If `prefix` is empty +for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so +helpful. So what other context can we get? + +Add a line to `#include "config.h"`. Then, add the following bits to the +function body: + +---- + const char *cfg_name; + +... + + git_config(git_default_config, NULL); + if (git_config_get_string_const("user.name", &cfg_name) > 0) + printf(_("No name is found in config\n")); + else + printf(_("Your name: %s\n"), cfg_name); +---- + +`git_config()` will grab the configuration from config files known to Git and +apply standard precedence rules. `git_config_get_string_const()` will look up +a specific key ("user.name") and give you the value. There are a number of +single-key lookup functions like this one; you can see them all (and more info +about how to use `git_config()`) in `Documentation/technical/api-config.txt`. + +You should see that the name printed matches the one you see when you run: + +---- +$ git config --get user.name +---- + +Great! Now we know how to check for values in the Git config. Let's commit this +too, so we don't lose our progress. + +---- +$ git add builtin/psuh.c +$ git commit -sm "psuh: show parameters & config opts" +---- + +NOTE: Again, the above is for sake of brevity in this tutorial. In a real change +you should not use `-m` but instead use the editor to write a meaningful +message. + +Still, it'd be nice to know what the user's working context is like. Let's see +if we can print the name of the user's current branch. We can mimic the +`git status` implementation; the printer is located in `wt-status.c` and we can +see that the branch is held in a `struct wt_status`. + +`wt_status_print()` gets invoked by `cmd_status()` in `builtin/commit.c`. +Looking at that implementation we see the status config being populated like so: + +---- +status_init_config(&s, git_status_config); +---- + +But as we drill down, we can find that `status_init_config()` wraps a call +to `git_config()`. Let's modify the code we wrote in the previous commit. + +Be sure to include the header to allow you to use `struct wt_status`: +---- +#include "wt-status.h" +---- + +Then modify your `cmd_psuh` implementation to declare your `struct wt_status`, +prepare it, and print its contents: + +---- + struct wt_status status; + +... + + wt_status_prepare(the_repository, &status); + git_config(git_default_config, &status); + +... + + printf(_("Your current branch: %s\n"), status.branch); +---- + +Run it again. Check it out - here's the (verbose) name of your current branch! + +Let's commit this as well. + +---- +$ git add builtin/psuh.c +$ git commit -sm "psuh: print the current branch" +---- + +Now let's see if we can get some info about a specific commit. + +Luckily, there are some helpers for us here. `commit.h` has a function called +`lookup_commit_reference_by_name` to which we can simply provide a hardcoded +string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't +require a full format object to be passed. + +Add the following includes: + +---- +#include "commit.h" +#include "pretty.h" +---- + +Then, add the following lines within your implementation of `cmd_psuh()` near +the declarations and the logic, respectively. + +---- + struct commit *c = NULL; + struct strbuf commitline = STRBUF_INIT; + +... + + c = lookup_commit_reference_by_name("origin/master"); + + if (c != NULL) { + pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline); + printf(_("Current commit: %s\n"), commitline.buf); + } +---- + +The `struct strbuf` provides some safety belts to your basic `char*`, one of +which is a length member to prevent buffer overruns. It needs to be initialized +nicely with `STRBUF_INIT`. Keep it in mind when you need to pass around `char*`. + +`lookup_commit_reference_by_name` resolves the name you pass it, so you can play +with the value there and see what kind of things you can come up with. + +`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single +format enum shorthand, rather than an entire format struct. It then +pretty-prints the commit according to that shorthand. These are similar to the +formats available with `--pretty=FOO` in many Git commands. + +Build it and run, and if you're using the same name in the example, you should +see the subject line of the most recent commit in `origin/master` that you know +about. Neat! Let's commit that as well. + +---- +$ git add builtin/psuh.c +$ git commit -sm "psuh: display the top of origin/master" +---- + +[[add-documentation]] +=== Adding Documentation + +Awesome! You've got a fantastic new command that you're ready to share with the +community. But hang on just a minute - this isn't very user-friendly. Run the +following: + +---- +$ ./bin-wrappers/git help psuh +---- + +Your new command is undocumented! Let's fix that. + +Take a look at `Documentation/git-*.txt`. These are the manpages for the +subcommands that Git knows about. You can open these up and take a look to get +acquainted with the format, but then go ahead and make a new file +`Documentation/git-psuh.txt`. Like with most of the documentation in the Git +project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing +Documentation" section). Use the following template to fill out your own +manpage: + +// Surprisingly difficult to embed AsciiDoc source within AsciiDoc. +[listing] +.... +git-psuh(1) +=========== + +NAME +---- +git-psuh - Delight users' typo with a shy horse + + +SYNOPSIS +-------- +[verse] +'git-psuh [<arg>...]' + +DESCRIPTION +----------- +... + +OPTIONS[[OPTIONS]] +------------------ +... + +OUTPUT +------ +... + +GIT +--- +Part of the linkgit:git[1] suite +.... + +The most important pieces of this to note are the file header, underlined by =, +the NAME section, and the SYNOPSIS, which would normally contain the grammar if +your command took arguments. Try to use well-established manpage headers so your +documentation is consistent with other Git and UNIX manpages; this makes life +easier for your user, who can skip to the section they know contains the +information they need. + +Now that you've written your manpage, you'll need to build it explicitly. We +convert your AsciiDoc to troff which is man-readable like so: + +---- +$ make all doc +$ man Documentation/git-psuh.1 +---- + +or + +---- +$ make -C Documentation/ git-psuh.1 +$ man Documentation/git-psuh.1 +---- + +NOTE: You may need to install the package `asciidoc` to get this to work. + +While this isn't as satisfying as running through `git help`, you can at least +check that your help page looks right. + +You can also check that the documentation coverage is good (that is, the project +sees that your command has been implemented as well as documented) by running +`make check-docs` from the top-level. + +Go ahead and commit your new documentation change. + +[[add-usage]] +=== Adding Usage Text + +Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end. +That's because `-h` is a special case which your command should handle by +printing usage. + +Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy +tool for pulling out options you need to be able to handle, and it takes a +usage string. + +In order to use it, we'll need to prepare a NULL-terminated array of usage +strings and a `builtin_psuh_options` array. + +Add a line to `#include "parse-options.h"`. + +At global scope, add your array of usage strings: + +---- +static const char * const psuh_usage[] = { + N_("git psuh [<arg>...]"), + NULL, +}; +---- + +Then, within your `cmd_psuh()` implementation, we can declare and populate our +`option` struct. Ours is pretty boring but you can add more to it if you want to +explore `parse_options()` in more detail: + +---- + struct option options[] = { + OPT_END() + }; +---- + +Finally, before you print your args and prefix, add the call to +`parse-options()`: + +---- + argc = parse_options(argc, argv, prefix, options, psuh_usage, 0); +---- + +This call will modify your `argv` parameter. It will strip the options you +specified in `options` from `argv` and the locations pointed to from `options` +entries will be updated. Be sure to replace your `argc` with the result from +`parse_options()`, or you will be confused if you try to parse `argv` later. + +It's worth noting the special argument `--`. As you may be aware, many Unix +commands use `--` to indicate "end of named parameters" - all parameters after +the `--` are interpreted merely as positional arguments. (This can be handy if +you want to pass as a parameter something which would usually be interpreted as +a flag.) `parse_options()` will terminate parsing when it reaches `--` and give +you the rest of the options afterwards, untouched. + +Now that you have a usage hint, you can teach Git how to show it in the general +command list shown by `git help git` or `git help -a`, which is generated from +`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh' +line above it in alphabetical order. Now, we can add some attributes about the +command which impacts where it shows up in the aforementioned help commands. The +top of `command-list.txt` shares some information about what each attribute +means; in those help pages, the commands are sorted according to these +attributes. `git psuh` is user-facing, or porcelain - so we will mark it as +"mainporcelain". For "mainporcelain" commands, the comments at the top of +`command-list.txt` indicate we can also optionally add an attribute from another +list; since `git psuh` shows some information about the user's workspace but +doesn't modify anything, let's mark it as "info". Make sure to keep your +attributes in the same style as the rest of `command-list.txt` using spaces to +align and delineate them: + +---- +git-prune-packed plumbingmanipulators +git-psuh mainporcelain info +git-pull mainporcelain remote +git-push mainporcelain remote +---- + +Build again. Now, when you run with `-h`, you should see your usage printed and +your command terminated before anything else interesting happens. Great! + +Go ahead and commit this one, too. + +[[testing]] +== Testing + +It's important to test your code - even for a little toy command like this one. +Moreover, your patch won't be accepted into the Git tree without tests. Your +tests should: + +* Illustrate the current behavior of the feature +* Prove the current behavior matches the expected behavior +* Ensure the externally-visible behavior isn't broken in later changes + +So let's write some tests. + +Related reading: `t/README` + +[[overview-test-structure]] +=== Overview of Testing Structure + +The tests in Git live in `t/` and are named with a 4-digit decimal number using +the schema shown in the Naming Tests section of `t/README`. + +[[write-new-test]] +=== Writing Your Test + +Since this a toy command, let's go ahead and name the test with t9999. However, +as many of the family/subcmd combinations are full, best practice seems to be +to find a command close enough to the one you've added and share its naming +space. + +Create a new file `t/t9999-psuh-tutorial.sh`. Begin with the header as so (see +"Writing Tests" and "Source 'test-lib.sh'" in `t/README`): + +---- +#!/bin/sh + +test_description='git-psuh test + +This test runs git-psuh and makes sure it does not crash.' + +. ./test-lib.sh +---- + +Tests are framed inside of a `test_expect_success` in order to output TAP +formatted results. Let's make sure that `git psuh` doesn't exit poorly and does +mention the right animal somewhere: + +---- +test_expect_success 'runs correctly with no args and good output' ' + git psuh >actual && + test_i18ngrep Pony actual +' +---- + +Indicate that you've run everything you wanted by adding the following at the +bottom of your script: + +---- +test_done +---- + +Make sure you mark your test script executable: + +---- +$ chmod +x t/t9999-psuh-tutorial.sh +---- + +You can get an idea of whether you created your new test script successfully +by running `make -C t test-lint`, which will check for things like test number +uniqueness, executable bit, and so on. + +[[local-test]] +=== Running Locally + +Let's try and run locally: + +---- +$ make +$ cd t/ && prove t9999-psuh-tutorial.sh +---- + +You can run the full test suite and ensure `git-psuh` didn't break anything: + +---- +$ cd t/ +$ prove -j$(nproc) --shuffle t[0-9]*.sh +---- + +NOTE: You can also do this with `make test` or use any testing harness which can +speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the +tests are run in, which makes them resilient against unwanted inter-test +dependencies. `prove` also makes the output nicer. + +Go ahead and commit this change, as well. + +[[ready-to-share]] +== Getting Ready to Share + +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 +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 +different methods of formatting your patchset and getting it reviewed. + +The first method to be covered is GitGitGadget, which is useful for those +already familiar with GitHub's common pull request workflow. This method +requires a GitHub account. + +The second method to be covered is `git send-email`, which can give slightly +more fine-grained control over the emails to be sent. This method requires some +setup which can change depending on your system and will not be covered in this +tutorial. + +Regardless of which method you choose, your engagement with reviewers will be +the same; the review process will be covered after the sections on GitGitGadget +and `git send-email`. + +[[howto-ggg]] +== Sending Patches via GitGitGadget + +One option for sending patches is to follow a typical pull request workflow and +send your patches out via GitGitGadget. GitGitGadget is a tool created by +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. + +[[create-fork]] +=== Forking `git/git` on GitHub + +Before you can send your patch off to be reviewed using GitGitGadget, you will +need to fork the Git project and upload your changes. First thing - make sure +you have a GitHub account. + +Head to the https://github.com/git/git[GitHub mirror] and look for the Fork +button. Place your fork wherever you deem appropriate and create it. + +[[upload-to-fork]] +=== Uploading to Your Own Fork + +To upload your branch to your own fork, you'll need to add the new fork as a +remote. You can use `git remote -v` to show the remotes you have added already. +From your new fork's page on GitHub, you can press "Clone or download" to get +the URL; then you need to run the following to add, replacing your own URL and +remote name for the examples provided: + +---- +$ git remote add remotename git@github.com:remotename/git.git +---- + +or to use the HTTPS URL: + +---- +$ git remote add remotename https://github.com/remotename/git/.git +---- + +Run `git remote -v` again and you should see the new remote showing up. +`git fetch remotename` (with the real name of your remote replaced) in order to +get ready to push. + +Next, double-check that you've been doing all your development in a new branch +by running `git branch`. If you didn't, now is a good time to move your new +commits to their own branch. + +As mentioned briefly at the beginning of this document, we are basing our work +on `master`, so go ahead and update as shown below, or using your preferred +workflow. + +---- +$ git checkout master +$ git pull -r +$ git rebase master psuh +---- + +Finally, you're ready to push your new topic branch! (Due to our branch and +command name choices, be careful when you type the command below.) + +---- +$ git push remotename psuh +---- + +Now you should be able to go and check out your newly created branch on GitHub. + +[[send-pr-ggg]] +=== Sending a PR to GitGitGadget + +In order to have your code tested and formatted for review, you need to start by +opening a Pull Request against `gitgitgadget/git`. Head to +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. + +[[run-ci-ggg]] +=== Running CI and Getting Ready to Send + +If it's your first time using GitGitGadget (which is likely, as you're using +this tutorial) then someone will need to give you permission to use the tool. +As mentioned in the GitGitGadget documentation, you just need someone who +already uses it to comment on your PR with `/allow <username>`. GitGitGadget +will automatically run your PRs through the CI even without the permission given +but you will not be able to `/submit` your changes until someone allows you to +use the tool. + +NOTE: You can typically find someone who can `/allow` you on GitGitGadget by +either examining recent pull requests where someone has been granted `/allow` +(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search: +is:pr is:open "/allow"]), in which case both the author and the person who +granted the `/allow` can now `/allow` you, or by inquiring on the +https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode +linking your pull request and asking for someone to `/allow` you. + +If the CI fails, you can update your changes with `git rebase -i` and push your +branch again: + +---- +$ git push -f remotename psuh +---- + +In fact, you should continue to make changes this way up until the point when +your patch is accepted into `next`. + +//// +TODO https://github.com/gitgitgadget/gitgitgadget/issues/83 +It'd be nice to be able to verify that the patch looks good before sending it +to everyone on Git mailing list. +[[check-work-ggg]] +=== Check Your Work +//// + +[[send-mail-ggg]] +=== Sending Your Patches + +Now that your CI is passing and someone has granted you permission to use +GitGitGadget with the `/allow` command, sending out for review is as simple as +commenting on your PR with `/submit`. + +[[responding-ggg]] +=== Updating With Comments + +Skip ahead to <<reviewing,Responding to Reviews>> for information on how to +reply to review comments you will receive on the mailing list. + +Once you have your branch again in the shape you want following all review +comments, you can submit again: + +---- +$ git push -f remotename psuh +---- + +Next, go look at your pull request against GitGitGadget; you should see the CI +has been kicked off again. Now while the CI is running is a good time for you +to modify your description at the top of the pull request thread; it will be +used again as the cover letter. You should use this space to describe what +has changed since your previous version, so that your reviewers have some idea +of what they're looking at. When the CI is done running, you can comment once +more with `/submit` - GitGitGadget will automatically add a v2 mark to your +changes. + +[[howto-git-send-email]] +== Sending Patches with `git send-email` + +If you don't want to use GitGitGadget, you can also use Git itself to mail your +patches. Some benefits of using Git this way include finer grained control of +subject line (for example, being able to use the tag [RFC PATCH] in the subject) +and being able to send a ``dry run'' mail to yourself to ensure it all looks +good before going out to the list. + +[[setup-git-send-email]] +=== Prerequisite: Setting Up `git send-email` + +Configuration for `send-email` can vary based on your operating system and email +provider, and so will not be covered in this tutorial, beyond stating that in +many distributions of Linux, `git-send-email` is not packaged alongside the +typical `git` install. You may need to install this additional package; there +are a number of resources online to help you do so. You will also need to +determine the right way to configure it to use your SMTP server; again, as this +configuration can change significantly based on your system and email setup, it +is out of scope for the context of this tutorial. + +[[format-patch]] +=== Preparing Initial Patchset + +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 +---- + +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 `-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. + +`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 +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 +normal way using `git rebase -i` or by adding a new commit than by modifying a +patch. + +NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject +with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for +comments'' and indicates that while your code isn't quite ready for submission, +you'd like to begin the code review process. This can also be used when your +patch is a proposal, but you aren't sure whether the community wants to solve +the problem with that approach or not - to conduct a sort of design review. You +may also see on the list patches marked ``WIP'' - this means they are incomplete +but want reviewers to look at what they have so far. You can add this flag with +`--subject-prefix=WIP`. + +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 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. + +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: + +---- +Subject: [PATCH 0/7] adding 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. + +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. +---- + +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. +The one generated for `psuh` from the sample implementation looks like this: + +---- + Documentation/git-psuh.txt | 40 +++++++++++++++++++++ + Makefile | 1 + + builtin.h | 1 + + builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++ + git.c | 1 + + t/t9999-psuh-tutorial.sh | 12 +++++++ + 6 files changed, 128 insertions(+) + create mode 100644 Documentation/git-psuh.txt + create mode 100644 builtin/psuh.c + create mode 100755 t/t9999-psuh-tutorial.sh +---- + +Finally, the letter will include the version of Git used to generate the +patches. You can leave that string alone. + +[[sending-git-send-email]] +=== Sending Email + +At this point you should have a directory `psuh/` which is filled with your +patches and a cover letter. Time to mail it out! You can send it like this: + +---- +$ git send-email --to=target@example.com psuh/*.patch +---- + +NOTE: Check `git help send-email` for some other options which you may find +valuable, such as changing the Reply-to address or adding more CC and BCC lines. + +NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but +please don't send your patchset from the tutorial to the real mailing list! For +now, you can send it to yourself, to make sure you understand how it will look. + +After you run the command above, you will be presented with an interactive +prompt for each patch that's about to go out. This gives you one last chance to +edit or quit sending something (but again, don't edit code this way). Once you +press `y` or `a` at these prompts your emails will be sent! Congratulations! + +Awesome, now the community will drop everything and review your changes. (Just +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. + +When you're ready with the next iteration of your patch, the process is fairly +similar. + +First, generate your v2 patches again: + +---- +$ git format-patch -v2 --cover-letter -o psuh/ master..psuh +---- + +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. + +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 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 +header. It should match: + +---- +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. + +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 +these CC lines directly to your cover letter with a line like so in the header +(before the Subject line): + +---- +CC: author@example.com, Othe R <other@example.com> +---- + +Now send the emails again, paying close attention to which messages you pass in +to the command: + +---- +$ git send-email --to=target@example.com + --in-reply-to="<foo.12345.author@example.com>" + psuh/v2* +---- + +[[single-patch]] +=== Bonus Chapter: One-Patch Changes + +In some cases, your very small change may consist of only one patch. When that +happens, you only need to send one email. Your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, but if you need to supply even more context, you can do so below +the `---` in your patch. Take the example below, which was generated with `git +format-patch` on a single commit, and then edited to add the content between +the `---` and the diffstat. + +---- +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001 +From: A U Thor <author@example.com> +Date: Thu, 18 Apr 2019 15:11:02 -0700 +Subject: [PATCH] README: change the grammar + +I think it looks better this way. This part of the commit message will +end up in the commit-log. + +Signed-off-by: A U Thor <author@example.com> +--- +Let's have a wild discussion about grammar on the mailing list. This +part of my email will never end up in the commit log. Here is where I +can add additional context to the mailing list about my intent, outside +of the context of the commit log. This section was added after `git +format-patch` was run, by editing the patch file in a text editor. + + README.md | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) + +diff --git a/README.md b/README.md +index 88f126184c..38da593a60 100644 +--- a/README.md ++++ b/README.md +@@ -3,7 +3,7 @@ + Git - fast, scalable, distributed revision control system + ========================================================= + +-Git is a fast, scalable, distributed revision control system with an ++Git is a fast, scalable, and distributed revision control system with an + unusually rich command set that provides both high-level operations + and full access to internals. + +-- +2.21.0.392.gf8f6787159e-goog +---- + +[[now-what]] +== My Patch Got Emailed - Now What? + +[[reviewing]] +=== Responding to Reviews + +After a few days, you will hopefully receive a reply to your patchset with some +comments. Woohoo! Now you can get back to work. + +It's good manners to reply to each comment, notifying the reviewer that you have +made the change requested, feel the original is better, or that the comment +inspired you to do something a new way which is superior to both the original +and the suggested change. This way reviewers don't need to inspect your v2 to +figure out whether you implemented their comment or not. + +If you are going to push back on a comment, be polite and explain why you feel +your original is better; be prepared that the reviewer may still disagree with +you, and the rest of the community may weigh in on one side or the other. As +with all code reviews, it's important to keep an open mind to doing something a +different way than you originally planned; other reviewers have a different +perspective on the project than you do, and may be thinking of a valid side +effect which had not occurred to you. It is always okay to ask for clarification +if you aren't sure why a change was suggested, or what the reviewer is asking +you to do. + +Make sure your email client has a plaintext email mode and it is turned on; the +Git list rejects HTML email. Please also follow the mailing list etiquette +outlined in the +https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's +Note], which are similar to etiquette rules in most open source communities +surrounding bottom-posting and inline replies. + +When you're making changes to your code, it is cleanest - that is, the resulting +commits are easiest to look at - if you use `git rebase -i` (interactive +rebase). Take a look at this +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview] +from O'Reilly. The general idea is to modify each commit which requires changes; +this way, instead of having a patch A with a mistake, a patch B which was fine +and required no upstream reviews in v1, and a patch C which fixes patch A for +v2, you can just ship a v2 with a correct patch A and correct patch B. This is +changing history, but since it's local history which you haven't shared with +anyone, that is okay for now! (Later, it may not make sense to do this; take a +look at the section below this one for some context.) + +[[after-approval]] +=== After Review Approval + +The Git project has four integration branches: `pu`, `next`, `master`, and +`maint`. Your change will be placed into `pu` fairly early on by the maintainer +while it is still in the review process; from there, when it is ready for wider +testing, it will be merged into `next`. Plenty of early testers use `next` and +may report issues. Eventually, changes in `next` will make it to `master`, +which is typically considered stable. Finally, when a new release is cut, +`maint` is used to base bugfixes onto. As mentioned at the beginning of this +document, you can read `Documents/SubmittingPatches` for some more info about +the use of the various integration branches. + +Back to now: your code has been lauded by the upstream reviewers. It is perfect. +It is ready to be accepted. You don't need to do anything else; the maintainer +will merge your topic branch to `next` and life is good. + +However, if you discover it isn't so perfect after this point, you may need to +take some special steps depending on where you are in the process. + +If the maintainer has announced in the "What's cooking in git.git" email that +your topic is marked for `next` - that is, that they plan to merge it to `next` +but have not yet done so - you should send an email asking the maintainer to +wait a little longer: "I've sent v4 of my series and you marked it for `next`, +but I need to change this and that - please wait for v5 before you merge it." + +If the topic has already been merged to `next`, rather than modifying your +patches with `git rebase -i`, you should make further changes incrementally - +that is, with another commit, based on top of the maintainer's topic branch as +detailed in https://github.com/gitster/git. Your work is still in the same topic +but is now incremental, rather than a wholesale rewrite of the topic branch. + +The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so +if you're sending your reviews out that way, you should be sure to open your PR +against the appropriate GitGitGadget/Git branch. + +If you're using `git send-email`, you can use it the same way as before, but you +should generate your diffs from `<topic>..<mybranch>` and base your work on +`<topic>` instead of `master`. diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt new file mode 100644 index 0000000000..c3f2d1a831 --- /dev/null +++ b/Documentation/MyFirstObjectWalk.txt @@ -0,0 +1,902 @@ += My First Object Walk + +== What's an Object Walk? + +The object walk is a key concept in Git - this is the process that underpins +operations like object transfer and fsck. Beginning from a given commit, the +list of objects is found by walking parent relationships between commits (commit +X based on commit W) and containment relationships between objects (tree Y is +contained within commit X, and blob Z is located within tree Y, giving our +working tree for commit X something like `y/z.txt`). + +A related concept is the revision walk, which is focused on commit objects and +their parent relationships and does not delve into other object types. The +revision walk is used for operations like `git log`. + +=== Related Reading + +- `Documentation/user-manual.txt` under "Hacking Git" contains some coverage of + the revision walker in its various incarnations. +- `revision.h` +- https://eagain.net/articles/git-for-computer-scientists/[Git for Computer Scientists] + gives a good overview of the types of objects in Git and what your object + walk is really describing. + +== Setting Up + +Create a new branch from `master`. + +---- +git checkout -b revwalk origin/master +---- + +We'll put our fiddling into a new command. For fun, let's name it `git walken`. +Open up a new file `builtin/walken.c` and set up the command handler: + +---- +/* + * "git walken" + * + * Part of the "My First Object Walk" tutorial. + */ + +#include "builtin.h" + +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + trace_printf(_("cmd_walken incoming...\n")); + return 0; +} +---- + +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`. + +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). + +---- +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() + }; + + argc = parse_options(argc, argv, prefix, options, walken_usage, 0); + + ... +} +---- + +Also add the relevant line in `builtin.h` near `cmd_whatchanged()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix); +---- + +Include the command in `git.c` in `commands[]` near the entry for `whatchanged`, +maintaining alphabetical ordering: + +---- +{ "walken", cmd_walken, RUN_SETUP }, +---- + +Add it to the `Makefile` near the line for `builtin/worktree.o`: + +---- +BUILTIN_OBJS += builtin/walken.o +---- + +Build and test out your command, without forgetting to ensure the `DEVELOPER` +flag is set, and with `GIT_TRACE` enabled so the debug output can be seen: + +---- +$ echo DEVELOPER=1 >>config.mak +$ make +$ GIT_TRACE=1 ./bin-wrappers/git walken +---- + +NOTE: For a more exhaustive overview of the new command process, take a look at +`Documentation/MyFirstContribution.txt`. + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/revwalk. + +=== `struct rev_cmdline_info` + +The definition of `struct rev_cmdline_info` can be found in `revision.h`. + +This struct is contained within the `rev_info` struct and is used to reflect +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 +used to track the allocated size of the list. + +Per entry, we find: + +`item` is the object provided upon which to base the object walk. Items in Git +can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.txt`.) + +`name` is the object ID (OID) of the object - a hex string you may be familiar +with from using Git to organize your source in the past. Check the tutorial +mentioned above towards the top for a discussion of where the OID can come +from. + +`whence` indicates some information about what to do with the parents of the +specified object. We'll explore this flag more later on; take a look at +`Documentation/revisions.txt` to get an idea of what could set the `whence` +value. + +`flags` are used to hint the beginning of the revision walk and are the first +block under the `#include`s in `revision.h`. The most likely ones to be set in +the `rev_cmdline_info` are `UNINTERESTING` and `BOTTOM`, but these same flags +can be used during the walk, as well. + +=== `struct rev_info` + +This one is quite a bit longer, and many fields are only used during the walk +by `revision.c` - not configuration options. Most of the configurable flags in +`struct rev_info` have a mirror in `Documentation/rev-list-options.txt`. It's a +good idea to take some time and read through that document. + +== Basic Commit Walk + +First, let's see if we can replicate the output of `git log --oneline`. We'll +refer back to the implementation frequently to discover norms when performing +an object walk of our own. + +To do so, we'll first find all the commits, in order, which preceded the current +commit. We'll extract the name and subject of the commit from each. + +Ideally, we will also be able to find out which ones are currently at the tip of +various branches. + +=== Setting Up + +Preparing for your object walk has some distinct stages. + +1. Perform default setup for this mode, and others which may be invoked. +2. Check configuration files for relevant settings. +3. Set up the `rev_info` struct. +4. Tweak the initialized `rev_info` to suit the current walk. +5. Prepare the `rev_info` for the walk. +6. Iterate over the objects, processing each one. + +==== Default Setups + +Before examining configuration files which may modify command behavior, set up +default state for switches or options your command may have. If your command +utilizes other Git components, ask them to set up their default states as well. +For instance, `git log` takes advantage of `grep` and `diff` functionality, so +its `init_log_defaults()` sets its own state (`decoration_style`) and asks +`grep` and `diff` to initialize themselves by calling each of their +initialization functions. + +For our first example within `git walken`, we don't intend to use any other +components within Git, and we don't have any configuration to do. However, we +may want to add some later, so for now, we can add an empty placeholder. Create +a new function in `builtin/walken.c`: + +---- +static void init_walken_defaults(void) +{ + /* + * We don't actually need the same components `git log` does; leave this + * empty for now. + */ +} +---- + +Make sure to add a line invoking it inside of `cmd_walken()`. + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + init_walken_defaults(); +} +---- + +==== Configuring From `.gitconfig` + +Next, we should have a look at any relevant configuration settings (i.e., +settings readable and settable from `git config`). This is done by providing a +callback to `git_config()`; within that callback, you can also invoke methods +from other components you may need that need to intercept these options. Your +callback will be invoked once per each configuration value which Git knows about +(global, local, worktree, etc.). + +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`: + +---- +static int git_walken_config(const char *var, const char *value, 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); +} +---- + +Make sure to invoke `git_config()` with it in your `cmd_walken()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + ... + + git_config(git_walken_config, NULL); + + ... +} +---- + +==== Setting Up `rev_info` + +Now that we've gathered external configuration and options, it's time to +initialize the `rev_info` object which we will use to perform the walk. This is +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: +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + /* This can go wherever you like in your declarations.*/ + struct rev_info rev; + ... + + /* This should go after the git_config() call. */ + repo_init_revisions(the_repository, &rev, prefix); + + ... +} +---- + +==== Tweaking `rev_info` For the Walk + +We're getting close, but we're still not quite ready to go. Now that `rev` is +initialized, we can modify it to fit our needs. This is usually done within a +helper for clarity, so let's add one: + +---- +static void final_rev_info_setup(struct rev_info *rev) +{ + /* + * We want to mimic the appearance of `git log --oneline`, so let's + * force oneline format. + */ + get_commit_format("oneline", rev); + + /* Start our object walk at HEAD. */ + add_head_to_pending(rev); +} +---- + +[NOTE] +==== +Instead of using the shorthand `add_head_to_pending()`, you could do +something like this: +---- + struct setup_revision_opt opt; + + memset(&opt, 0, sizeof(opt)); + opt.def = "HEAD"; + opt.revarg_opt = REVARG_COMMITTISH; + setup_revisions(argc, argv, rev, &opt); +---- +Using a `setup_revision_opt` gives you finer control over your walk's starting +point. +==== + +Then let's invoke `final_rev_info_setup()` after the call to +`repo_init_revisions()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + ... + + final_rev_info_setup(&rev); + + ... +} +---- + +Later, we may wish to add more arguments to `final_rev_info_setup()`. But for +now, this is all we need. + +==== Preparing `rev_info` For the Walk + +Now that `rev` is all initialized and configured, we've got one more setup step +before we get rolling. We can do this in a helper, which will both prepare the +`rev_info` for the walk, and perform the walk itself. Let's start the helper +with the call to `prepare_revision_walk()`, which can return an error without +dying on its own: + +---- +static void walken_commit_walk(struct rev_info *rev) +{ + if (prepare_revision_walk(rev)) + die(_("revision walk setup failed")); +} +---- + +NOTE: `die()` prints to `stderr` and exits the program. Since it will print to +`stderr` it's likely to be seen by a human, so we will localize it. + +==== Performing the Walk! + +Finally! We are ready to begin the walk itself. Now we can see that `rev_info` +can also be used as an iterator; we move to the next item in the walk by using +`get_revision()` repeatedly. Add the listed variable declarations at the top and +the walk loop below the `prepare_revision_walk()` call within your +`walken_commit_walk()`: + +---- +static void walken_commit_walk(struct rev_info *rev) +{ + struct commit *commit; + struct strbuf prettybuf = STRBUF_INIT; + + ... + + while ((commit = get_revision(rev))) { + strbuf_reset(&prettybuf); + pp_commit_easy(CMIT_FMT_ONELINE, commit, &prettybuf); + puts(prettybuf.buf); + } + strbuf_release(&prettybuf); +} +---- + +NOTE: `puts()` prints a `char*` to `stdout`. Since this is the part of the +command we expect to be machine-parsed, we're sending it directly to stdout. + +Give it a shot. + +---- +$ make +$ ./bin-wrappers/git walken +---- + +You should see all of the subject lines of all the commits in +your tree's history, in order, ending with the initial commit, "Initial revision +of "git", the information manager from hell". Congratulations! You've written +your first revision walk. You can play with printing some additional fields +from each commit if you're curious; have a look at the functions available in +`commit.h`. + +=== Adding a Filter + +Next, let's try to filter the commits we see based on their author. This is +equivalent to running `git log --author=<pattern>`. We can add a filter by +modifying `rev_info.grep_filter`, which is a `struct grep_opt`. + +First some setup. Add `init_grep_defaults()` to `init_walken_defaults()` and add +`grep_config()` to `git_walken_config()`: + +---- +static void init_walken_defaults(void) +{ + init_grep_defaults(the_repository); +} + +... + +static int git_walken_config(const char *var, const char *value, void *cb) +{ + grep_config(var, value, cb); + return git_default_config(var, value, cb); +} +---- + +Next, we can modify the `grep_filter`. This is done with convenience functions +found in `grep.h`. For fun, we're filtering to only commits from folks using a +`gmail.com` email address - a not-very-precise guess at who may be working on +Git as a hobby. Since we're checking the author, which is a specific line in the +header, we'll use the `append_header_grep_pattern()` helper. We can use +the `enum grep_header_field` to indicate which part of the commit header we want +to search. + +In `final_rev_info_setup()`, add your filter line: + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + append_header_grep_pattern(&rev->grep_filter, GREP_HEADER_AUTHOR, + "gmail"); + compile_grep_patterns(&rev->grep_filter); + + ... +} +---- + +`append_header_grep_pattern()` adds your new "gmail" pattern to `rev_info`, but +it won't work unless we compile it with `compile_grep_patterns()`. + +NOTE: If you are using `setup_revisions()` (for example, if you are passing a +`setup_revision_opt` instead of using `add_head_to_pending()`), you don't need +to call `compile_grep_patterns()` because `setup_revisions()` calls it for you. + +NOTE: We could add the same filter via the `append_grep_pattern()` helper if we +wanted to, but `append_header_grep_pattern()` adds the `enum grep_context` and +`enum grep_pat_token` for us. + +=== Changing the Order + +There are a few ways that we can change the order of the commits during a +revision walk. Firstly, we can use the `enum rev_sort_order` to choose from some +typical orderings. + +`topo_order` is the same as `git log --topo-order`: we avoid showing a parent +before all of its children have been shown, and we avoid mixing commits which +are in different lines of history. (`git help log`'s section on `--topo-order` +has a very nice diagram to illustrate this.) + +Let's see what happens when we run with `REV_SORT_BY_COMMIT_DATE` as opposed to +`REV_SORT_BY_AUTHOR_DATE`. Add the following: + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + rev->topo_order = 1; + rev->sort_order = REV_SORT_BY_COMMIT_DATE; + + ... +} +---- + +Let's output this into a file so we can easily diff it with the walk sorted by +author date. + +---- +$ make +$ ./bin-wrappers/git walken > commit-date.txt +---- + +Then, let's sort by author date and run it again. + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + rev->topo_order = 1; + rev->sort_order = REV_SORT_BY_AUTHOR_DATE; + + ... +} +---- + +---- +$ make +$ ./bin-wrappers/git walken > author-date.txt +---- + +Finally, compare the two. This is a little less helpful without object names or +dates, but hopefully we get the idea. + +---- +$ diff -u commit-date.txt author-date.txt +---- + +This display indicates that commits can be reordered after they're written, for +example with `git rebase`. + +Let's try one more reordering of commits. `rev_info` exposes a `reverse` flag. +Set that flag somewhere inside of `final_rev_info_setup()`: + +---- +static void final_rev_info_setup(int argc, const char **argv, const char *prefix, + struct rev_info *rev) +{ + ... + + rev->reverse = 1; + + ... +} +---- + +Run your walk again and note the difference in order. (If you remove the grep +pattern, you should see the last commit this call gives you as your current +HEAD.) + +== Basic Object Walk + +So far we've been walking only commits. But Git has more types of objects than +that! Let's see if we can walk _all_ objects, and find out some information +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 +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. + +- `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. +- `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`. +- `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. + +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 +tracking variables: + +---- +static int commit_count; +static int tag_count; +static int blob_count; +static int tree_count; +---- + +Commits are handled by a different callback than other objects; let's do that +one first: + +---- +static void walken_show_commit(struct commit *cmt, void *buf) +{ + commit_count++; +} +---- + +The `cmt` argument is fairly self-explanatory. But it's worth mentioning that +the `buf` argument is actually the context buffer that we can provide to the +traversal calls - `show_data`, which we mentioned a moment ago. + +Since we have the `struct commit` object, we can look at all the same parts that +we looked at in our earlier commit-only walk. For the sake of this tutorial, +though, we'll just increment the commit counter and move on. + +The callback for non-commits is a little different, as we'll need to check +which kind of object we're dealing with: + +---- +static void walken_show_object(struct object *obj, const char *str, void *buf) +{ + switch (obj->type) { + case OBJ_TREE: + tree_count++; + break; + case OBJ_BLOB: + blob_count++; + break; + case OBJ_TAG: + tag_count++; + break; + case OBJ_COMMIT: + BUG("unexpected commit object in walken_show_object\n"); + default: + BUG("unexpected object type %s in walken_show_object\n", + type_name(obj->type)); + } +} +---- + +Again, `obj` is fairly self-explanatory, and we can guess that `buf` is the same +context pointer that `walken_show_commit()` receives: the `show_data` argument +to `traverse_commit_list()` and `traverse_commit_list_filtered()`. Finally, +`str` contains the name of the object, which ends up being something like +`foo.txt` (blob), `bar/baz` (tree), or `v1.2.3` (tag). + +To help assure us that we aren't double-counting commits, we'll include some +complaining if a commit object is routed through our non-commit callback; we'll +also complain if we see an invalid object type. Since those two cases should be +unreachable, and would only change in the event of a semantic change to the Git +codebase, we complain by using `BUG()` - which is a signal to a developer that +the change they made caused unintended consequences, and the rest of the +codebase needs to be updated to understand that change. `BUG()` is not intended +to be seen by the public, so it is not localized. + +Our main object walk implementation is substantially different from our commit +walk implementation, so let's make a new function to perform the object walk. We +can perform setup which is applicable to all objects here, too, to keep separate +from setup which is applicable to commit-only walks. + +We'll start by enabling all types of objects in the `struct rev_info`. We'll +also turn on `tree_blobs_in_commit_order`, which means that we will walk a +commit's tree and everything it points to immediately after we find each commit, +as opposed to waiting for the end and walking through all trees after the commit +history has been discovered. With the appropriate settings configured, we are +ready to call `prepare_revision_walk()`. + +---- +static void walken_object_walk(struct rev_info *rev) +{ + rev->tree_objects = 1; + rev->blob_objects = 1; + rev->tag_objects = 1; + rev->tree_blobs_in_commit_order = 1; + + if (prepare_revision_walk(rev)) + die(_("revision walk setup failed")); + + commit_count = 0; + tag_count = 0; + blob_count = 0; + tree_count = 0; +---- + +Let's start by calling just the unfiltered walk and reporting our counts. +Complete your implementation of `walken_object_walk()`: + +---- + traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL); + + printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count, + blob_count, tag_count, tree_count); +} +---- + +NOTE: This output is intended to be machine-parsed. Therefore, we are not +sending it to `trace_printf()`, and we are not localizing it - we need scripts +to be able to count on the formatting to be exactly the way it is shown here. +If we were intending this output to be read by humans, we would need to localize +it with `_()`. + +Finally, we'll ask `cmd_walken()` to use the object walk instead. Discussing +command line options is out of scope for this tutorial, so we'll just hardcode +a branch we can change at compile time. Where you call `final_rev_info_setup()` +and `walken_commit_walk()`, instead branch like so: + +---- + if (1) { + add_head_to_pending(&rev); + walken_object_walk(&rev); + } else { + final_rev_info_setup(argc, argv, prefix, &rev); + walken_commit_walk(&rev); + } +---- + +NOTE: For simplicity, we've avoided all the filters and sorts we applied in +`final_rev_info_setup()` and simply added `HEAD` to our pending queue. If you +want, you can certainly use the filters we added before by moving +`final_rev_info_setup()` out of the conditional and removing the call to +`add_head_to_pending()`. + +Now we can try to run our command! It should take noticeably longer than the +commit walk, but an examination of the output will give you an idea why. Your +output should look similar to this example, but with different counts: + +---- +Object walk completed. Found 55733 commits, 100274 blobs, 0 tags, and 104210 trees. +---- + +This makes sense. We have more trees than commits because the Git project has +lots of subdirectories which can change, plus at least one tree per commit. We +have no tags because we started on a commit (`HEAD`) and while tags can point to +commits, commits can't point to tags. + +NOTE: You will have different counts when you run this yourself! The number of +objects grows along with the Git project. + +=== Adding a Filter + +There are a handful of filters that we can apply to the object walk laid out in +`Documentation/rev-list-options.txt`. These filters are typically useful for +operations such as creating packfiles or performing a partial clone. They are +defined in `list-objects-filter-options.h`. For the purposes of this tutorial we +will use the "tree:1" filter, which causes the walk to omit all trees and blobs +which are not directly referenced by commits reachable from the commit in +`pending` when the walk begins. (`pending` is the list of objects which need to +be traversed during a walk; you can imagine a breadth-first tree traversal to +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 +`traverse_commit_list()` with the following, which will remind us which kind of +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); + } +---- + +`struct list_objects_filter_options` 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()`. + +With the filter spec "tree:1", we are expecting to see _only_ the root tree for +each commit; therefore, the tree object count should be less than or equal to +the number of commits. (For an example of why that's true: `git commit --revert` +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. + +First, add the `struct oidset` and related items we will use to iterate it: + +---- +static void walken_object_walk( + ... + + struct oidset omitted; + struct oidset_iter oit; + struct object_id *oid = NULL; + int omitted_count = 0; + oidset_init(&omitted, 0); + + ... +---- + +Modify the call to `traverse_commit_list_filtered()` to include your `omitted` +object: + +---- + ... + + traverse_commit_list_filtered(&filter_options, rev, + walken_show_commit, walken_show_object, NULL, &omitted); + + ... +---- + +Then, after your traversal, the `oidset` traversal is pretty straightforward. +Count all the objects within and modify the print statement: + +---- + /* Count the omitted objects. */ + oidset_iter_init(&omitted, &oit); + + while ((oid = oidset_iter_next(&oit))) + omitted_count++; + + printf("commits %d\nblobs %d\ntags %d\ntrees%d\nomitted %d\n", + commit_count, blob_count, tag_count, tree_count, omitted_count); +---- + +By running your walk with and without the filter, you should find that the total +object count in each case is identical. You can also time each invocation of +the `walken` subcommand, with and without `omitted` being passed in, to confirm +to yourself the runtime impact of tracking all omitted objects. + +=== Changing the Order + +Finally, let's demonstrate that you can also reorder walks of all objects, not +just walks of commits. First, we'll make our handlers chattier - modify +`walken_show_commit()` and `walken_show_object()` to print the object as they +go: + +---- +static void walken_show_commit(struct commit *cmt, void *buf) +{ + trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid)); + commit_count++; +} + +static void walken_show_object(struct object *obj, const char *str, void *buf) +{ + trace_printf("%s: %s\n", type_name(obj->type), oid_to_hex(&obj->oid)); + + ... +} +---- + +NOTE: Since we will be examining this output directly as humans, we'll use +`trace_printf()` here. Additionally, since this change introduces a significant +number of printed lines, using `trace_printf()` will allow us to easily silence +those lines without having to recompile. + +(Leave the counter increment logic in place.) + +With only that change, run again (but save yourself some scrollback): + +---- +$ GIT_TRACE=1 ./bin-wrappers/git walken | head -n 10 +---- + +Take a look at the top commit with `git show` and the object ID you printed; it +should be the same as the output of `git show HEAD`. + +Next, let's change a setting on our `struct rev_info` within +`walken_object_walk()`. Find where you're changing the other settings on `rev`, +such as `rev->tree_objects` and `rev->tree_blobs_in_commit_order`, and add the +`reverse` setting at the bottom: + +---- + ... + + rev->tree_objects = 1; + rev->blob_objects = 1; + rev->tag_objects = 1; + rev->tree_blobs_in_commit_order = 1; + rev->reverse = 1; + + ... +---- + +Now, run again, but this time, let's grab the last handful of objects instead +of the first handful: + +---- +$ make +$ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10 +---- + +The last commit object given should have the same OID as the one we saw at the +top before, and running `git show <oid>` with that OID should give you again +the same results as `git show HEAD`. Furthermore, if you run and examine the +first ten lines again (with `head` instead of `tail` like we did before applying +the `reverse` setting), you should see that now the first commit printed is the +initial commit, `e83c5163`. + +== Wrapping Up + +Let's review. In this tutorial, we: + +- Built a commit walk from the ground up +- Enabled a grep filter for that commit walk +- Changed the sort order of that filtered commit walk +- Built an object walk (tags, commits, trees, and blobs) from the ground up +- Learned how to add a filter-spec to an object walk +- Changed the display order of the filtered object walk diff --git a/Documentation/RelNotes/1.5.0.txt b/Documentation/RelNotes/1.5.0.txt index daf4bdb0d7..d6d42f3183 100644 --- a/Documentation/RelNotes/1.5.0.txt +++ b/Documentation/RelNotes/1.5.0.txt @@ -251,7 +251,7 @@ Updates in v1.5.0 since v1.4.4 series the repository when that happens. -* Crufts removal +* Cruft removal - We used to say "old commits are retrievable using reflog and 'master@{yesterday}' syntax as long as you haven't run @@ -379,7 +379,7 @@ Updates in v1.5.0 since v1.4.4 series - The value of i18n.commitencoding in the originating repository is recorded in the commit object on the "encoding" header, if it is not UTF-8. git-log and friends notice this, - and reencodes the message to the log output encoding when + and re-encodes the message to the log output encoding when displaying, if they are different. The log output encoding is determined by "git log --encoding=<encoding>", i18n.logoutputencoding configuration, or i18n.commitencoding diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.txt index ad060f4f89..980adfb315 100644 --- a/Documentation/RelNotes/1.6.2.txt +++ b/Documentation/RelNotes/1.6.2.txt @@ -11,7 +11,7 @@ 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 - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.txt index 418c685cf8..4bcff945e0 100644 --- a/Documentation/RelNotes/1.6.3.txt +++ b/Documentation/RelNotes/1.6.3.txt @@ -11,7 +11,7 @@ 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 - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.4.txt b/Documentation/RelNotes/1.6.4.txt index 7a904419f7..a2a34b43a7 100644 --- a/Documentation/RelNotes/1.6.4.txt +++ b/Documentation/RelNotes/1.6.4.txt @@ -11,7 +11,7 @@ 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 - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.5.4.txt b/Documentation/RelNotes/1.6.5.4.txt index d3a2a3e712..344333de66 100644 --- a/Documentation/RelNotes/1.6.5.4.txt +++ b/Documentation/RelNotes/1.6.5.4.txt @@ -10,7 +10,7 @@ Fixes since v1.6.5.3 * "git prune-packed" gave progress output even when its standard error is not connected to a terminal; this caused cron jobs that run it to - produce crufts. + produce cruft. * "git pack-objects --all-progress" is an option to ask progress output from write-object phase _if_ progress output were to be produced, and diff --git a/Documentation/RelNotes/1.6.5.txt b/Documentation/RelNotes/1.6.5.txt index ee141c19ad..6c7f7da7eb 100644 --- a/Documentation/RelNotes/1.6.5.txt +++ b/Documentation/RelNotes/1.6.5.txt @@ -22,7 +22,7 @@ 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 - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.6.txt b/Documentation/RelNotes/1.6.6.txt index c50b59c495..3ed1e01433 100644 --- a/Documentation/RelNotes/1.6.6.txt +++ b/Documentation/RelNotes/1.6.6.txt @@ -64,7 +64,7 @@ users will fare this time. Please refer to: http://git.or.cz/gitwiki/GitFaq#non-bare - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition process that already took place so far. diff --git a/Documentation/RelNotes/1.7.0.2.txt b/Documentation/RelNotes/1.7.0.2.txt index fcb46ca6a4..73ed2b5278 100644 --- a/Documentation/RelNotes/1.7.0.2.txt +++ b/Documentation/RelNotes/1.7.0.2.txt @@ -34,7 +34,7 @@ Fixes since v1.7.0.1 * "git status" in 1.7.0 lacked the optimization we used to have in 1.6.X series to speed up scanning of large working tree. - * "gitweb" did not diagnose parsing errors properly while reading tis configuration + * "gitweb" did not diagnose parsing errors properly while reading its configuration file. And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.4.txt b/Documentation/RelNotes/1.7.10.4.txt index 326670df6e..57597f2bf3 100644 --- a/Documentation/RelNotes/1.7.10.4.txt +++ b/Documentation/RelNotes/1.7.10.4.txt @@ -7,7 +7,7 @@ Fixes since v1.7.10.3 * The message file for Swedish translation has been updated a bit. * A name taken from mailmap was copied into an internal buffer - incorrectly and could overun the buffer if it is too long. + incorrectly and could overrun the buffer if it is too long. * A malformed commit object that has a header line chomped in the middle could kill git with a NULL pointer dereference. diff --git a/Documentation/RelNotes/1.7.12.3.txt b/Documentation/RelNotes/1.7.12.3.txt index ecda427a35..4b822976b8 100644 --- a/Documentation/RelNotes/1.7.12.3.txt +++ b/Documentation/RelNotes/1.7.12.3.txt @@ -25,7 +25,7 @@ Fixes since v1.7.12.2 its Accept-Encoding header. * "git receive-pack" (the counterpart to "git push") did not give - progress output while processing objects it received to the puser + progress output while processing objects it received to the user when run over the smart-http protocol. * "git status" honored the ignore=dirty settings in .gitmodules but diff --git a/Documentation/RelNotes/1.7.5.3.txt b/Documentation/RelNotes/1.7.5.3.txt index 9c03353af2..1d24edcf2f 100644 --- a/Documentation/RelNotes/1.7.5.3.txt +++ b/Documentation/RelNotes/1.7.5.3.txt @@ -22,7 +22,7 @@ Fixes since v1.7.5.2 * "git log --stdin path" with an input that has additional pathspec used to corrupt memory. - * "git send-pack" (hence "git push") over smalt-HTTP protocol could + * "git send-pack" (hence "git push") over smart-HTTP protocol could deadlock when the client side pack-object died early. * Compressed tarball gitweb generates used to be made with the timestamp diff --git a/Documentation/RelNotes/1.8.0.txt b/Documentation/RelNotes/1.8.0.txt index 43883c14f0..63d6e4afa4 100644 --- a/Documentation/RelNotes/1.8.0.txt +++ b/Documentation/RelNotes/1.8.0.txt @@ -233,7 +233,7 @@ to them for details). together, misdetected branches. * "git receive-pack" (the counterpart to "git push") did not give - progress output while processing objects it received to the puser + progress output while processing objects it received to the user when run over the smart-http protocol. * When you misspell the command name you give to the "exec" action in diff --git a/Documentation/RelNotes/1.8.4.1.txt b/Documentation/RelNotes/1.8.4.1.txt index 96090ef599..c257beb114 100644 --- a/Documentation/RelNotes/1.8.4.1.txt +++ b/Documentation/RelNotes/1.8.4.1.txt @@ -15,7 +15,7 @@ Fixes since v1.8.4 in 1.8.4-rc1). * "git rebase -i" and other scripted commands were feeding a - random, data dependant error message to 'echo' and expecting it + random, data dependent error message to 'echo' and expecting it to come out literally. * Setting the "submodule.<name>.path" variable to the empty diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt index 02f681b710..255e185af6 100644 --- a/Documentation/RelNotes/1.8.4.txt +++ b/Documentation/RelNotes/1.8.4.txt @@ -58,7 +58,7 @@ Foreign interfaces, subsystems and ports. credential helper interface from Git.pm. * Update build for Cygwin 1.[57]. Torsten Bögershausen reports that - this is fine with Cygwin 1.7 ($gmane/225824) so let's try moving it + this is fine with Cygwin 1.7 (cf. <51A606A0.5060101@web.de>) so let's try moving it ahead. * The credential helper to talk to keychain on OS X (in contrib/) has diff --git a/Documentation/RelNotes/2.1.3.txt b/Documentation/RelNotes/2.1.3.txt index acc9ebb886..0dfb17c4fc 100644 --- a/Documentation/RelNotes/2.1.3.txt +++ b/Documentation/RelNotes/2.1.3.txt @@ -13,7 +13,7 @@ Git v2.1.3 Release Notes they are new enough to support the `--output` option. * "git pack-objects" forgot to disable the codepath to generate - object recheability bitmap when it needs to split the resulting + object reachability bitmap when it needs to split the resulting pack. * "gitweb" used deprecated CGI::startfrom, which was removed from diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.txt index f4da28ab66..3792b7d03d 100644 --- a/Documentation/RelNotes/2.10.0.txt +++ b/Documentation/RelNotes/2.10.0.txt @@ -478,7 +478,7 @@ notes for details). * One part of "git am" had an oddball helper function that called stuff from outside "his" as opposed to calling what we have "ours", which was not gender-neutral and also inconsistent with the rest of - the system where outside stuff is usuall called "theirs" in + the system where outside stuff is usually called "theirs" in contrast to "ours". * "git blame file" allowed the lineage of lines in the uncommitted, diff --git a/Documentation/RelNotes/2.10.2.txt b/Documentation/RelNotes/2.10.2.txt index c4d4397023..abbd331508 100644 --- a/Documentation/RelNotes/2.10.2.txt +++ b/Documentation/RelNotes/2.10.2.txt @@ -86,7 +86,7 @@ Fixes since v2.10.1 by refusing to check out a branch that is already checked out in another worktree. However, this also prevented checking out a branch, which is designated as the primary branch of a bare - reopsitory, in a worktree that is connected to the bare + repository, in a worktree that is connected to the bare repository. The check has been corrected to allow it. * "git rebase" immediately after "git clone" failed to find the fork diff --git a/Documentation/RelNotes/2.11.1.txt b/Documentation/RelNotes/2.11.1.txt index 9cd14c8197..7d35cf186d 100644 --- a/Documentation/RelNotes/2.11.1.txt +++ b/Documentation/RelNotes/2.11.1.txt @@ -104,7 +104,7 @@ Fixes since v2.11 "git difftool --dir-diff" from a subdirectory never worked. This has been fixed. - * "git p4" that tracks multile p4 paths imported a single changelist + * "git p4" that tracks multiple p4 paths imported a single changelist that touches files in these multiple paths as one commit, followed by many empty commits. This has been fixed. diff --git a/Documentation/RelNotes/2.12.0.txt b/Documentation/RelNotes/2.12.0.txt index ef8b97da9b..d2f6a83614 100644 --- a/Documentation/RelNotes/2.12.0.txt +++ b/Documentation/RelNotes/2.12.0.txt @@ -315,7 +315,7 @@ notes for details). "git difftool --dir-diff" from a subdirectory never worked. This has been fixed. - * "git p4" that tracks multile p4 paths imported a single changelist + * "git p4" that tracks multiple p4 paths imported a single changelist that touches files in these multiple paths as one commit, followed by many empty commits. This has been fixed. diff --git a/Documentation/RelNotes/2.13.0.txt b/Documentation/RelNotes/2.13.0.txt index aa99d4b3ce..2a47b4cb0c 100644 --- a/Documentation/RelNotes/2.13.0.txt +++ b/Documentation/RelNotes/2.13.0.txt @@ -177,7 +177,7 @@ UI, Workflows & Features been changed to enable "--decorate". * The output from "git status --short" has been extended to show - various kinds of dirtyness in submodules differently; instead of to + various kinds of dirtiness in submodules differently; instead of to "M" for modified, 'm' and '?' can be shown to signal changes only to the working tree of the submodule but not the commit that is checked out. diff --git a/Documentation/RelNotes/2.13.3.txt b/Documentation/RelNotes/2.13.3.txt index 5d76ad5310..384e4de265 100644 --- a/Documentation/RelNotes/2.13.3.txt +++ b/Documentation/RelNotes/2.13.3.txt @@ -25,7 +25,7 @@ Fixes since v2.13.2 * The code to pick up and execute command alias definition from the configuration used to switch to the top of the working tree and then come back when the expanded alias was executed, which was - unnecessarilyl complex. Attempt to simplify the logic by using the + unnecessarily complex. Attempt to simplify the logic by using the early-config mechanism that does not chdir around. * "git add -p" were updated in 2.12 timeframe to cope with custom @@ -35,7 +35,7 @@ Fixes since v2.13.2 * Fix a recent regression to "git rebase -i" and add tests that would have caught it and others. - * An unaligned 32-bit access in pack-bitmap code ahs been corrected. + * An unaligned 32-bit access in pack-bitmap code has been corrected. * Tighten error checks for invalid "git apply" input. diff --git a/Documentation/RelNotes/2.14.0.txt b/Documentation/RelNotes/2.14.0.txt index 4246c68ff5..2711a2529d 100644 --- a/Documentation/RelNotes/2.14.0.txt +++ b/Documentation/RelNotes/2.14.0.txt @@ -141,7 +141,7 @@ Performance, Internal Implementation, Development Support etc. * Some platforms have ulong that is smaller than time_t, and our historical use of ulong for timestamp would mean they cannot represent some timestamp that the platform allows. Invent a - separate and dedicated timestamp_t (so that we can distingiuish + separate and dedicated timestamp_t (so that we can distinguish timestamps and a vanilla ulongs, which along is already a good move), and then declare uintmax_t is the type to be used as the timestamp_t. @@ -442,7 +442,7 @@ notes for details). * The code to pick up and execute command alias definition from the configuration used to switch to the top of the working tree and then come back when the expanded alias was executed, which was - unnecessarilyl complex. Attempt to simplify the logic by using the + unnecessarily complex. Attempt to simplify the logic by using the early-config mechanism that does not chdir around. * Fix configuration codepath to pay proper attention to commondir diff --git a/Documentation/RelNotes/2.14.5.txt b/Documentation/RelNotes/2.14.5.txt new file mode 100644 index 0000000000..130645fb29 --- /dev/null +++ b/Documentation/RelNotes/2.14.5.txt @@ -0,0 +1,16 @@ +Git v2.14.5 Release Notes +========================= + +This release is to address the recently reported CVE-2018-17456. + +Fixes since v2.14.4 +------------------- + + * Submodules' "URL"s come from the untrusted .gitmodules file, but + we blindly gave it to "git clone" to clone submodules when "git + clone --recurse-submodules" was used to clone a project that has + such a submodule. The code has been hardened to reject such + malformed URLs (e.g. one that begins with a dash). + +Credit for finding and fixing this vulnerability goes to joernchen +and Jeff King, respectively. diff --git a/Documentation/RelNotes/2.14.6.txt b/Documentation/RelNotes/2.14.6.txt new file mode 100644 index 0000000000..72b7af6799 --- /dev/null +++ b/Documentation/RelNotes/2.14.6.txt @@ -0,0 +1,54 @@ +Git v2.14.6 Release Notes +========================= + +This release addresses the security issues CVE-2019-1348, +CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, +CVE-2019-1353, CVE-2019-1354, and CVE-2019-1387. + +Fixes since v2.14.5 +------------------- + + * CVE-2019-1348: + The --export-marks option of git fast-import is exposed also via + the in-stream command feature export-marks=... and it allows + overwriting arbitrary paths. + + * CVE-2019-1349: + When submodules are cloned recursively, under certain circumstances + Git could be fooled into using the same Git directory twice. We now + require the directory to be empty. + + * CVE-2019-1350: + Incorrect quoting of command-line arguments allowed remote code + execution during a recursive clone in conjunction with SSH URLs. + + * CVE-2019-1351: + While the only permitted drive letters for physical drives on + Windows are letters of the US-English alphabet, this restriction + does not apply to virtual drives assigned via subst <letter>: + <path>. Git mistook such paths for relative paths, allowing writing + outside of the worktree while cloning. + + * CVE-2019-1352: + Git was unaware of NTFS Alternate Data Streams, allowing files + inside the .git/ directory to be overwritten during a clone. + + * CVE-2019-1353: + When running Git in the Windows Subsystem for Linux (also known as + "WSL") while accessing a working directory on a regular Windows + drive, none of the NTFS protections were active. + + * CVE-2019-1354: + Filenames on Linux/Unix can contain backslashes. On Windows, + backslashes are directory separators. Git did not use to refuse to + write out tracked files with such filenames. + + * CVE-2019-1387: + Recursive clones are currently affected by a vulnerability that is + caused by too-lax validation of submodule names, allowing very + targeted attacks via remote code execution in recursive clones. + +Credit for finding these vulnerabilities goes to Microsoft Security +Response Center, in particular to Nicolas Joly. The `fast-import` +fixes were provided by Jeff King, the other fixes by Johannes +Schindelin with help from Garima Singh. diff --git a/Documentation/RelNotes/2.15.3.txt b/Documentation/RelNotes/2.15.3.txt new file mode 100644 index 0000000000..fd2e6f8df7 --- /dev/null +++ b/Documentation/RelNotes/2.15.3.txt @@ -0,0 +1,6 @@ +Git v2.15.3 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.5 to address +the recently reported CVE-2018-17456; see the release notes for that +version for details. diff --git a/Documentation/RelNotes/2.15.4.txt b/Documentation/RelNotes/2.15.4.txt new file mode 100644 index 0000000000..dc241cba34 --- /dev/null +++ b/Documentation/RelNotes/2.15.4.txt @@ -0,0 +1,11 @@ +Git v2.15.4 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6 to address +the security issues CVE-2019-1348, CVE-2019-1349, CVE-2019-1350, +CVE-2019-1351, CVE-2019-1352, CVE-2019-1353, CVE-2019-1354, and +CVE-2019-1387; see the release notes for that version for details. + +In conjunction with a vulnerability that was fixed in v2.20.2, +`.gitmodules` is no longer allowed to contain entries of the form +`submodule.<name>.update=!command`. diff --git a/Documentation/RelNotes/2.16.0.txt b/Documentation/RelNotes/2.16.0.txt index 0c81c5915f..b474781ed8 100644 --- a/Documentation/RelNotes/2.16.0.txt +++ b/Documentation/RelNotes/2.16.0.txt @@ -407,7 +407,7 @@ Fixes since v2.15 (merge eef3df5a93 bw/pathspec-match-submodule-boundary later to maint). * Amending commits in git-gui broke the author name that is non-ascii - due to incorrect enconding conversion. + due to incorrect encoding conversion. * Recent update to the submodule configuration code broke "diff-tree" by accidentally stopping to read from the index upfront. diff --git a/Documentation/RelNotes/2.16.3.txt b/Documentation/RelNotes/2.16.3.txt index 64a0bcb0d2..f0121a8f2d 100644 --- a/Documentation/RelNotes/2.16.3.txt +++ b/Documentation/RelNotes/2.16.3.txt @@ -24,7 +24,7 @@ Fixes since v2.16.2 * The http tracing code, often used to debug connection issues, learned to redact potentially sensitive information from its output - so that it can be more safely sharable. + so that it can be more safely shareable. * Crash fix for a corner case where an error codepath tried to unlock what it did not acquire lock on. diff --git a/Documentation/RelNotes/2.16.5.txt b/Documentation/RelNotes/2.16.5.txt new file mode 100644 index 0000000000..cb8ee02a9a --- /dev/null +++ b/Documentation/RelNotes/2.16.5.txt @@ -0,0 +1,6 @@ +Git v2.16.5 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.5 to address +the recently reported CVE-2018-17456; see the release notes for that +version for details. diff --git a/Documentation/RelNotes/2.16.6.txt b/Documentation/RelNotes/2.16.6.txt new file mode 100644 index 0000000000..438306e60b --- /dev/null +++ b/Documentation/RelNotes/2.16.6.txt @@ -0,0 +1,8 @@ +Git v2.16.6 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6 and in +v2.15.4 addressing the security issues CVE-2019-1348, CVE-2019-1349, +CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, CVE-2019-1353, +CVE-2019-1354, and CVE-2019-1387; see the release notes for those +versions for details. diff --git a/Documentation/RelNotes/2.17.0.txt b/Documentation/RelNotes/2.17.0.txt index c2cf891f71..8b17c26033 100644 --- a/Documentation/RelNotes/2.17.0.txt +++ b/Documentation/RelNotes/2.17.0.txt @@ -216,7 +216,7 @@ Fixes since v2.16 * The http tracing code, often used to debug connection issues, learned to redact potentially sensitive information from its output - so that it can be more safely sharable. + so that it can be more safely shareable. (merge 8ba18e6fa4 jt/http-redact-cookies later to maint). * Crash fix for a corner case where an error codepath tried to unlock diff --git a/Documentation/RelNotes/2.17.2.txt b/Documentation/RelNotes/2.17.2.txt new file mode 100644 index 0000000000..ef021be870 --- /dev/null +++ b/Documentation/RelNotes/2.17.2.txt @@ -0,0 +1,12 @@ +Git v2.17.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.5 to address +the recently reported CVE-2018-17456; see the release notes for that +version for details. + +In addition, this release also teaches "fsck" and the server side +logic to reject pushes to repositories that attempt to create such a +problematic ".gitmodules" file as tracked contents, to help hosting +sites protect their customers by preventing malicious contents from +spreading. diff --git a/Documentation/RelNotes/2.17.3.txt b/Documentation/RelNotes/2.17.3.txt new file mode 100644 index 0000000000..5a46c94271 --- /dev/null +++ b/Documentation/RelNotes/2.17.3.txt @@ -0,0 +1,12 @@ +Git v2.17.3 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6 and in +v2.15.4 addressing the security issues CVE-2019-1348, CVE-2019-1349, +CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, CVE-2019-1353, +CVE-2019-1354, and CVE-2019-1387; see the release notes for those +versions for details. + +In addition, `git fsck` was taught to identify `.gitmodules` entries +of the form `submodule.<name>.update=!command`, which have been +disallowed in v2.15.4. diff --git a/Documentation/RelNotes/2.17.4.txt b/Documentation/RelNotes/2.17.4.txt new file mode 100644 index 0000000000..7d794ca01a --- /dev/null +++ b/Documentation/RelNotes/2.17.4.txt @@ -0,0 +1,16 @@ +Git v2.17.4 Release Notes +========================= + +This release is to address the security issue: CVE-2020-5260 + +Fixes since v2.17.3 +------------------- + + * With a crafted URL that contains a newline in it, the credential + helper machinery can be fooled to give credential information for + a wrong host. The attack has been made impossible by forbidding + a newline character in any value passed via the credential + protocol. + +Credit for finding the vulnerability goes to Felix Wilhelm of Google +Project Zero. diff --git a/Documentation/RelNotes/2.17.5.txt b/Documentation/RelNotes/2.17.5.txt new file mode 100644 index 0000000000..2abb821a73 --- /dev/null +++ b/Documentation/RelNotes/2.17.5.txt @@ -0,0 +1,22 @@ +Git v2.17.5 Release Notes +========================= + +This release is to address a security issue: CVE-2020-11008 + +Fixes since v2.17.4 +------------------- + + * With a crafted URL that contains a newline or empty host, or lacks + a scheme, the credential helper machinery can be fooled into + providing credential information that is not appropriate for the + protocol in use and host being contacted. + + Unlike the vulnerability CVE-2020-5260 fixed in v2.17.4, the + credentials are not for a host of the attacker's choosing; instead, + they are for some unspecified host (based on how the configured + credential helper handles an absent "host" parameter). + + The attack has been made impossible by refusing to work with + under-specified credential patterns. + +Credit for finding the vulnerability goes to Carlo Arenas. diff --git a/Documentation/RelNotes/2.18.0.txt b/Documentation/RelNotes/2.18.0.txt index 3ea280cf68..6c8a0e97c1 100644 --- a/Documentation/RelNotes/2.18.0.txt +++ b/Documentation/RelNotes/2.18.0.txt @@ -179,7 +179,7 @@ Performance, Internal Implementation, Development Support etc. (merge 00a3da2a13 nd/remove-ignore-env-field later to maint). * Code to find the length to uniquely abbreviate object names based - on packfile content, which is a relatively recent addtion, has been + on packfile content, which is a relatively recent addition, has been optimized to use the same fan-out table. * The mechanism to use parse-options API to automate the command line diff --git a/Documentation/RelNotes/2.18.1.txt b/Documentation/RelNotes/2.18.1.txt new file mode 100644 index 0000000000..2098cdd776 --- /dev/null +++ b/Documentation/RelNotes/2.18.1.txt @@ -0,0 +1,6 @@ +Git v2.18.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.5 and in +v2.17.2 to address the recently reported CVE-2018-17456; see the +release notes for those versions for details. diff --git a/Documentation/RelNotes/2.18.2.txt b/Documentation/RelNotes/2.18.2.txt new file mode 100644 index 0000000000..98b168aade --- /dev/null +++ b/Documentation/RelNotes/2.18.2.txt @@ -0,0 +1,8 @@ +Git v2.18.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4 +and in v2.17.3, addressing the security issues CVE-2019-1348, +CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, +CVE-2019-1353, CVE-2019-1354, and CVE-2019-1387; see the release notes +for those versions for details. diff --git a/Documentation/RelNotes/2.18.3.txt b/Documentation/RelNotes/2.18.3.txt new file mode 100644 index 0000000000..25143f0cec --- /dev/null +++ b/Documentation/RelNotes/2.18.3.txt @@ -0,0 +1,5 @@ +Git v2.18.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.18.4.txt b/Documentation/RelNotes/2.18.4.txt new file mode 100644 index 0000000000..e8ef858a00 --- /dev/null +++ b/Documentation/RelNotes/2.18.4.txt @@ -0,0 +1,5 @@ +Git v2.18.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.19.0.txt b/Documentation/RelNotes/2.19.0.txt index bcbfbc2041..891c79b9cb 100644 --- a/Documentation/RelNotes/2.19.0.txt +++ b/Documentation/RelNotes/2.19.0.txt @@ -83,6 +83,13 @@ UI, Workflows & Features * The sideband code learned to optionally paint selected keywords at the beginning of incoming lines on the receiving end. + * "git branch --list" learned to take the default sort order from the + 'branch.sort' configuration variable, just like "git tag --list" + pays attention to 'tag.sort'. + + * "git worktree" command learned "--quiet" option to make it less + verbose. + Performance, Internal Implementation, Development Support etc. @@ -99,7 +106,7 @@ Performance, Internal Implementation, Development Support etc. * The conversion to pass "the_repository" and then "a_repository" throughout the object access API continues. - * Continuing with the idea to programatically enumerate various + * Continuing with the idea to programmatically enumerate various pieces of data required for command line completion, teach the codebase to report the list of configuration variables subcommands care about to help complete them. @@ -119,9 +126,6 @@ Performance, Internal Implementation, Development Support etc. * Build and test procedure for netrc credential helper (in contrib/) has been updated. - * The conversion to pass "the_repository" and then "a_repository" - throughout the object access API continues. - * Remove unused function definitions and declarations from ewah bitmap subsystem. @@ -251,6 +255,19 @@ Performance, Internal Implementation, Development Support etc. getting them coalesced into fewer packfiles, hurting performance. "git repack" now learned to repack them. + * Partially revert the support for multiple hash functions to regain + hash comparison performance; we'd think of a way to do this better + in the next cycle. + + * "git help --config" (which is used in command line completion) + missed the configuration variables not described in the main + config.txt file but are described in another file that is included + by it, which has been corrected. + + * The test linter code has learned that the end of here-doc mark + "EOF" can be quoted in a double-quote pair, not just in a + single-quote pair. + Fixes since v2.18 ----------------- @@ -296,12 +313,6 @@ Fixes since v2.18 to the submodule was changed in the range of commits in the superproject, sometimes showing "(null)". This has been corrected. - * "git submodule" did not correctly adjust core.worktree setting that - indicates whether/where a submodule repository has its associated - working tree across various state transitions, which has been - corrected. - (merge 984cd77ddb sb/submodule-core-worktree later to maint). - * Bugfix for "rebase -i" corner case regression. (merge a9279c6785 pw/rebase-i-keep-reword-after-conflict later to maint). @@ -533,6 +544,32 @@ Fixes since v2.18 has been corrected. (merge 3e7dd99208 nd/cherry-pick-quit-fix later to maint). + * In a recent update in 2.18 era, "git pack-objects" started + producing a larger than necessary packfiles by missing + opportunities to use large deltas. This has been corrected. + + * The meaning of the possible values the "core.checkStat" + configuration variable can take were not adequately documented, + which has been fixed. + (merge 9bf5d4c4e2 nd/config-core-checkstat-doc later to maint). + + * Recent "git rebase -i" update started to write bogusly formatted + author-script, with a matching broken reading code. These are + fixed. + + * Recent addition of "directory rename" heuristics to the + merge-recursive backend makes the command susceptible to false + positives and false negatives. In the context of "git am -3", + which does not know about surrounding unmodified paths and thus + cannot inform the merge machinery about the full trees involved, + this risk is particularly severe. As such, the heuristic is + disabled for "git am -3" to keep the machinery "more stupid but + predictable". + + * "git merge-base" in 2.19-rc1 has performance regression when the + (experimental) commit-graph feature is in use, which has been + mitigated. + * Code cleanup, docfix, build fix, etc. (merge aee9be2ebe sg/update-ref-stdin-cleanup later to maint). (merge 037714252f jc/clean-after-sanity-tests later to maint). @@ -565,3 +602,14 @@ Fixes since v2.18 (merge 10c600172c sg/t5310-empty-input-fix later to maint). (merge 5641eb9465 jh/partial-clone-doc later to maint). (merge 2711b1ad5e ab/submodule-relative-url-tests later to maint). + (merge ce528de023 ab/unconditional-free-and-null later to maint). + (merge bbc072f5d8 rs/opt-updates later to maint). + (merge 69d846f053 jk/use-compat-util-in-test-tool later to maint). + (merge 1820703045 js/larger-timestamps later to maint). + (merge c8b35b95e1 sg/t4051-fix later to maint). + (merge 30612cb670 sg/t0020-conversion-fix later to maint). + (merge 15da753709 sg/t7501-thinkofix later to maint). + (merge 79b04f9b60 sg/t3903-missing-fix later to maint). + (merge 2745817028 sg/t3420-autostash-fix later to maint). + (merge 7afb0d6777 sg/test-rebase-editor-fix later to maint). + (merge 6c6ce21baa es/freebsd-iconv-portability later to maint). diff --git a/Documentation/RelNotes/2.19.1.txt b/Documentation/RelNotes/2.19.1.txt new file mode 100644 index 0000000000..da7672674e --- /dev/null +++ b/Documentation/RelNotes/2.19.1.txt @@ -0,0 +1,6 @@ +Git v2.19.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.5 and in +v2.17.2 to address the recently reported CVE-2018-17456; see the +release notes for those versions for details. diff --git a/Documentation/RelNotes/2.19.2.txt b/Documentation/RelNotes/2.19.2.txt new file mode 100644 index 0000000000..759e6ca957 --- /dev/null +++ b/Documentation/RelNotes/2.19.2.txt @@ -0,0 +1,108 @@ +Git v2.19.2 Release Notes +========================= + +Fixes since v2.19.1 +------------------- + + * "git interpret-trailers" and its underlying machinery had a buggy + code that attempted to ignore patch text after commit log message, + which triggered in various codepaths that will always get the log + message alone and never get such an input. + + * "git rebase -i" did not clear the state files correctly when a run + of "squash/fixup" is aborted and then the user manually amended the + commit instead, which has been corrected. + + * When fsmonitor is in use, after operation on submodules updates + .gitmodules, we lost track of the fact that we did so and relied on + stale fsmonitor data. + + * Fix for a long-standing bug that leaves the index file corrupt when + it shrinks during a partial commit. + + * Further fix for O_APPEND emulation on Windows + + * A corner case bugfix in "git rerere" code. + + * "git add ':(attr:foo)'" is not supported and is supposed to be + rejected while the command line arguments are parsed, but we fail + to reject such a command line upfront. + + * "git rebase" etc. in Git 2.19 fails to abort when given an empty + commit log message as result of editing, which has been corrected. + + * The code to backfill objects in lazily cloned repository did not + work correctly, which has been corrected. + + * Update error messages given by "git remote" and make them consistent. + + * "git update-ref" learned to make both "--no-deref" and "--stdin" + work at the same time. + + * Recently added "range-diff" had a corner-case bug to cause it + segfault, which has been corrected. + + * The recently introduced commit-graph auxiliary data is incompatible + with mechanisms such as replace & grafts that "breaks" immutable + nature of the object reference relationship. Disable optimizations + based on its use (and updating existing commit-graph) when these + incompatible features are in use in the repository. + + * The mailmap file update. + + * The code in "git status" sometimes hit an assertion failure. This + was caused by a structure that was reused without cleaning the data + used for the first run, which has been corrected. + + * A corner-case bugfix. + + * A partial clone that is configured to lazily fetch missing objects + will on-demand issue a "git fetch" request to the originating + repository to fill not-yet-obtained objects. The request has been + optimized for requesting a tree object (and not the leaf blob + objects contained in it) by telling the originating repository that + no blobs are needed. + + * The codepath to support the experimental split-index mode had + remaining "racily clean" issues fixed. + + * "git log --graph" showing an octopus merge sometimes miscounted the + number of display columns it is consuming to show the merge and its + parent commits, which has been corrected. + + * The implementation of run_command() API on the UNIX platforms had a + bug that caused a command not on $PATH to be found in the current + directory. + + * A mutex used in "git pack-objects" were not correctly initialized + and this caused "git repack" to dump core on Windows. + + * Under certain circumstances, "git diff D:/a/b/c D:/a/b/d" on + Windows would strip initial parts from the paths because they + were not recognized as absolute, which has been corrected. + + * The receive.denyCurrentBranch=updateInstead codepath kicked in even + when the push should have been rejected due to other reasons, such + as it does not fast-forward or the update-hook rejects it, which + has been corrected. + + * "git repack" in a shallow clone did not correctly update the + shallow points in the repository, leading to a repository that + does not pass fsck. + + * Operations on promisor objects make sense in the context of only a + small subset of the commands that internally use the revisions + machinery, but the "--exclude-promisor-objects" option were taken + and led to nonsense results by commands like "log", to which it + didn't make much sense. This has been corrected. + + * The "container" mode of TravisCI is going away. Our .travis.yml + file is getting prepared for the transition. + + * Our test scripts can now take the '-V' option as a synonym for the + '--verbose-log' option. + + * A regression in Git 2.12 era made "git fsck" fall into an infinite + loop while processing truncated loose objects. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.19.3.txt b/Documentation/RelNotes/2.19.3.txt new file mode 100644 index 0000000000..92d7f89de6 --- /dev/null +++ b/Documentation/RelNotes/2.19.3.txt @@ -0,0 +1,8 @@ +Git v2.19.3 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4 +and in v2.17.3, addressing the security issues CVE-2019-1348, +CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, +CVE-2019-1353, CVE-2019-1354, and CVE-2019-1387; see the release notes +for those versions for details. diff --git a/Documentation/RelNotes/2.19.4.txt b/Documentation/RelNotes/2.19.4.txt new file mode 100644 index 0000000000..35d0ae561b --- /dev/null +++ b/Documentation/RelNotes/2.19.4.txt @@ -0,0 +1,5 @@ +Git v2.19.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.19.5.txt b/Documentation/RelNotes/2.19.5.txt new file mode 100644 index 0000000000..18a4dcbfd6 --- /dev/null +++ b/Documentation/RelNotes/2.19.5.txt @@ -0,0 +1,5 @@ +Git v2.19.5 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.20.0.txt b/Documentation/RelNotes/2.20.0.txt new file mode 100644 index 0000000000..3dd7e6e1fc --- /dev/null +++ b/Documentation/RelNotes/2.20.0.txt @@ -0,0 +1,700 @@ +Git 2.20 Release Notes +====================== + +Backward Compatibility Notes +---------------------------- + + * "git branch -l <foo>" used to be a way to ask a reflog to be + created while creating a new branch, but that is no longer the + case. It is a short-hand for "git branch --list <foo>" now. + + * "git push" into refs/tags/* hierarchy is rejected without getting + forced, but "git fetch" (misguidedly) used the "fast forwarding" + rule used for the refs/heads/* hierarchy; this has been corrected, + which means some fetches of tags that did not fail with older + version of Git will fail without "--force" with this version. + + * "git help -a" now gives verbose output (same as "git help -av"). + Those who want the old output may say "git help --no-verbose -a".. + + * "git cpn --help", when "cpn" is an alias to, say, "cherry-pick -n", + reported only the alias expansion of "cpn" in earlier versions of + Git. It now runs "git cherry-pick --help" to show the manual page + of the command, while sending the alias expansion to the standard + error stream. + + * "git send-email" learned to grab address-looking string on any + trailer whose name ends with "-by". This is a backward-incompatible + change. Adding "--suppress-cc=misc-by" on the command line, or + setting sendemail.suppresscc configuration variable to "misc-by", + can be used to disable this behaviour. + + +Updates since v2.19 +------------------- + +UI, Workflows & Features + + * Running "git clone" against a project that contain two files with + pathnames that differ only in cases on a case insensitive + filesystem would result in one of the files lost because the + underlying filesystem is incapable of holding both at the same + time. An attempt is made to detect such a case and warn. + + * "git checkout -b newbranch [HEAD]" should not have to do as much as + checking out a commit different from HEAD. An attempt is made to + optimize this special case. + + * "git rev-list --stdin </dev/null" used to be an error; it now shows + no output without an error. "git rev-list --stdin --default HEAD" + still falls back to the given default when nothing is given on the + standard input. + + * Lift code from GitHub to restrict delta computation so that an + object that exists in one fork is not made into a delta against + another object that does not appear in the same forked repository. + + * "git format-patch" learned new "--interdiff" and "--range-diff" + options to explain the difference between this version and the + previous attempt in the cover letter (or after the three-dashes as + a comment). + + * "git mailinfo" used in "git am" learned to make a best-effort + recovery of a patch corrupted by MUA that sends text/plain with + format=flawed option. + (merge 3aa4d81f88 rs/mailinfo-format-flowed later to maint). + + * The rules used by "git push" and "git fetch" to determine if a ref + can or cannot be updated were inconsistent; specifically, fetching + to update existing tags were allowed even though tags are supposed + to be unmoving anchoring points. "git fetch" was taught to forbid + updates to existing tags without the "--force" option. + + * "git multi-pack-index" learned to detect corruption in the .midx + file it uses, and this feature has been integrated into "git fsck". + + * Generation of (experimental) commit-graph files have so far been + fairly silent, even though it takes noticeable amount of time in a + meaningfully large repository. The users will now see progress + output. + + * The minimum version of Windows supported by Windows port of Git is + now set to Vista. + + * The completion script (in contrib/) learned to complete a handful of + options "git stash list" command takes. + + * The completion script (in contrib/) learned that "git fetch + --multiple" only takes remote names as arguments and no refspecs. + + * "git status" learns to show progress bar when refreshing the index + takes a long time. + (merge ae9af12287 nd/status-refresh-progress later to maint). + + * "git help -a" and "git help -av" give different pieces of + information, and generally the "verbose" version is more friendly + to the new users. "git help -a" by default now uses the more + verbose output (with "--no-verbose", you can go back to the + original). Also "git help -av" now lists aliases and external + commands, which it did not used to. + + * Unlike "grep", "git grep" by default recurses to the whole tree. + The command learned "git grep --recursive" option, so that "git + grep --no-recursive" can serve as a synonym to setting the + max-depth to 0. + + * When pushing into a repository that borrows its objects from an + alternate object store, "git receive-pack" that responds to the + push request on the other side lists the tips of refs in the + alternate to reduce the amount of objects transferred. This + sometimes is detrimental when the number of refs in the alternate + is absurdly large, in which case the bandwidth saved in potentially + fewer objects transferred is wasted in excessively large ref + advertisement. The alternate refs that are advertised are now + configurable with a pair of configuration variables. + + * "git cmd --help" when "cmd" is aliased used to only say "cmd is + aliased to ...". Now it shows that to the standard error stream + and runs "git $cmd --help" where $cmd is the first word of the + alias expansion. + + * The documentation of "git gc" has been updated to mention that it + is no longer limited to "pruning away cruft" but also updates + ancillary files like commit-graph as a part of repository + optimization. + + * "git p4 unshelve" improvements. + + * The logic to select the default user name and e-mail on Windows has + been improved. + (merge 501afcb8b0 js/mingw-default-ident later to maint). + + * The "rev-list --filter" feature learned to exclude all trees via + "tree:0" filter. + + * "git send-email" learned to grab address-looking string on any + trailer whose name ends with "-by"; --suppress-cc=misc-by on the + command line, or setting sendemail.suppresscc configuration + variable to "misc-by", can be used to disable this behaviour. + + * "git mergetool" learned to take the "--[no-]gui" option, just like + "git difftool" does. + + * "git rebase -i" learned a new insn, 'break', that the user can + insert in the to-do list. Upon hitting it, the command returns + control back to the user. + + * New "--pretty=format:" placeholders %GF and %GP that show the GPG + key fingerprints have been invented. + + * On platforms with recent cURL library, http.sslBackend configuration + variable can be used to choose a different SSL backend at runtime. + The Windows port uses this mechanism to switch between OpenSSL and + Secure Channel while talking over the HTTPS protocol. + + * "git send-email" learned to disable SMTP authentication via the + "--smtp-auth=none" option, even when the smtp username is given + (which turns the authentication on by default). + + * A fourth class of configuration files (in addition to the + traditional "system wide", "per user in the $HOME directory" and + "per repository in the $GIT_DIR/config") has been introduced so + that different worktrees that share the same repository (hence the + same $GIT_DIR/config file) can use different customization. + + * A pattern with '**' that does not have a slash on either side used + to be an invalid one, but the code now treats such double-asterisks + the same way as two normal asterisks that happen to be adjacent to + each other. + (merge e5bbe09e88 nd/wildmatch-double-asterisk later to maint). + + * The "--no-patch" option, which can be used to get a high-level + overview without the actual line-by-line patch difference shown, of + the "range-diff" command was earlier broken, which has been + corrected. + + * The recently merged "rebase in C" has an escape hatch to use the + scripted version when necessary, but it hasn't been documented, + which has been corrected. + + +Performance, Internal Implementation, Development Support etc. + + * Developer builds now use -Wunused-function compilation option. + + * One of our CI tests to run with "unusual/experimental/random" + settings now also uses commit-graph and midx. + + * When there are too many packfiles in a repository (which is not + recommended), looking up an object in these would require + consulting many pack .idx files; a new mechanism to have a single + file that consolidates all of these .idx files is introduced. + + * "git submodule update" is getting rewritten piece-by-piece into C. + + * The code for computing history reachability has been shuffled, + obtained a bunch of new tests to cover them, and then being + improved. + + * The unpack_trees() API used in checking out a branch and merging + walks one or more trees along with the index. When the cache-tree + in the index tells us that we are walking a tree whose flattened + contents is known (i.e. matches a span in the index), as linearly + scanning a span in the index is much more efficient than having to + open tree objects recursively and listing their entries, the walk + can be optimized, which has been done. + + * When creating a thin pack, which allows objects to be made into a + delta against another object that is not in the resulting pack but + is known to be present on the receiving end, the code learned to + take advantage of the reachability bitmap; this allows the server + to send a delta against a base beyond the "boundary" commit. + + * spatch transformation to replace boolean uses of !hashcmp() to + newly introduced oideq() is added, and applied, to regain + performance lost due to support of multiple hash algorithms. + + * Fix a bug in which the same path could be registered under multiple + worktree entries if the path was missing (for instance, was removed + manually). Also, as a convenience, expand the number of cases in + which --force is applicable. + + * Split Documentation/config.txt for easier maintenance. + (merge 6014363f0b nd/config-split later to maint). + + * Test helper binaries clean-up. + (merge c9a1f4161f nd/test-tool later to maint). + + * Various tests have been updated to make it easier to swap the + hash function used for object identification. + (merge ae0c89d41b bc/hash-independent-tests later to maint). + + * Update fsck.skipList implementation and documentation. + (merge 371a655074 ab/fsck-skiplist later to maint). + + * An alias that expands to another alias has so far been forbidden, + but now it is allowed to create such an alias. + + * Various test scripts have been updated for style and also correct + handling of exit status of various commands. + + * "gc --auto" ended up calling exit(-1) upon error, which has been + corrected to use exit(1). Also the error reporting behaviour when + daemonized has been updated to exit with zero status when stopping + due to a previously discovered error (which implies there is no + point running gc to improve the situation); we used to exit with + failure in such a case. + + * Various codepaths in the core-ish part learned to work on an + arbitrary in-core index structure, not necessarily the default + instance "the_index". + (merge b3c7eef9b0 nd/the-index later to maint). + + * Code clean-up in the internal machinery used by "git status" and + "git commit --dry-run". + (merge 73ba5d78b4 ss/wt-status-committable later to maint). + + * Some environment variables that control the runtime options of Git + used during tests are getting renamed for consistency. + (merge 4231d1ba99 bp/rename-test-env-var later to maint). + + * A pair of new extensions to the index file have been introduced. + They allow the index file to be read in parallel for performance. + + * The oidset API was built on top of the oidmap API which in turn is + on the hashmap API. Replace the implementation to build on top of + the khash API and gain performance. + + * Over some transports, fetching objects with an exact commit object + name can be done without first seeing the ref advertisements. The + code has been optimized to exploit this. + + * In a partial clone that will lazily be hydrated from the + originating repository, we generally want to avoid "does this + object exist (locally)?" on objects that we deliberately omitted + when we created the clone. The cache-tree codepath (which is used + to write a tree object out of the index) however insisted that the + object exists, even for paths that are outside of the partial + checkout area. The code has been updated to avoid such a check. + + * To help developers, an EditorConfig file that attempts to follow + the project convention has been added. + (merge b548d698a0 bc/editorconfig later to maint). + + * The result of coverage test can be combined with "git blame" to + check the test coverage of code introduced recently with a new + 'coverage-diff' tool (in contrib/). + (merge 783faedd65 ds/coverage-diff later to maint). + + * An experiment to fuzz test a few areas, hopefully we can gain more + coverage to various areas. + + * More codepaths are moving away from hardcoded hash sizes. + + * The way the Windows port figures out the current directory has been + improved. + + * The way DLLs are loaded on the Windows port has been improved. + + * Some tests have been reorganized and renamed; "ls t/" now gives a + better overview of what is tested for these scripts than before. + + * "git rebase" and "git rebase -i" have been reimplemented in C. + + * Windows port learned to use nano-second resolution file timestamps. + + * The overly large Documentation/config.txt file have been split into + million little pieces. This potentially allows each individual piece + to be included into the manual page of the command it affects more easily. + + * Replace three string-list instances used as look-up tables in "git + fetch" with hashmaps. + + * Unify code to read the author-script used in "git am" and the + commands that use the sequencer machinery, e.g. "git rebase -i". + + * In preparation to the day when we can deprecate and remove the + "rebase -p", make sure we can skip and later remove tests for + it. + + * The history traversal used to implement the tag-following has been + optimized by introducing a new helper. + + * The helper function to refresh the cached stat information in the + in-core index has learned to perform the lstat() part of the + operation in parallel on multi-core platforms. + + * The code to traverse objects for reachability, used to decide what + objects are unreferenced and expendable, have been taught to also + consider per-worktree refs of other worktrees as starting points to + prevent data loss. + + * "git add" needs to internally run "diff-files" equivalent, and the + codepath learned the same optimization as "diff-files" has to run + lstat(2) in parallel to find which paths have been updated in the + working tree. + + * The procedure to install dependencies before testing at Travis CI + is getting revamped for both simplicity and flexibility, taking + advantage of the recent move to the vm-based environment. + + * The support for format-patch (and send-email) by the command-line + completion script (in contrib/) has been simplified a bit. + + * The revision walker machinery learned to take advantage of the + commit generation numbers stored in the commit-graph file. + + * The codebase has been cleaned up to reduce "#ifndef NO_PTHREADS". + + * The way -lcurl library gets linked has been simplified by taking + advantage of the fact that we can just ask curl-config command how. + + * Various functions have been audited for "-Wunused-parameter" warnings + and bugs in them got fixed. + + * A sanity check for start-up sequence has been added in the config + API codepath. + + * The build procedure to link for fuzzing test has been made + customizable with a new Makefile variable. + + * The way "git rebase" parses and forwards the command line options + meant for underlying "git am" has been revamped, which fixed for + options with parameters that were not passed correctly. + + * Our testing framework uses a special i18n "poisoned localization" + feature to find messages that ought to stay constant but are + incorrectly marked to be translated. This feature has been made + into a runtime option (it used to be a compile-time option). + + * "git push" used to check ambiguities between object-names and + refnames while processing the list of refs' old and new values, + which was unnecessary (as it knew that it is feeding raw object + names). This has been optimized out. + + * The xcurl_off_t() helper function is used to cast size_t to + curl_off_t, but some compilers gave warnings against the code to + ensure the casting is done without wraparound, when size_t is + narrower than curl_off_t. This warning has been squelched. + + * Code preparation to replace ulong vars with size_t vars where + appropriate continues. + + * The "test installed Git" mode of our test suite has been updated to + work better. + + * A coding convention around the Coccinelle semantic patches to have + two classes to ease code migration process has been proposed and + its support has been added to the Makefile. + + * The "container" mode of TravisCI is going away. Our .travis.yml + file is getting prepared for the transition. + (merge 32ee384be8 ss/travis-ci-force-vm-mode later to maint). + + * Our test scripts can now take the '-V' option as a synonym for the + '--verbose-log' option. + (merge a5f52c6dab sg/test-verbose-log later to maint). + + +Fixes since v2.19 +----------------- + + * "git interpret-trailers" and its underlying machinery had a buggy + code that attempted to ignore patch text after commit log message, + which triggered in various codepaths that will always get the log + message alone and never get such an input. + (merge 66e83d9b41 jk/trailer-fixes later to maint). + + * Malformed or crafted data in packstream can make our code attempt + to read or write past the allocated buffer and abort, instead of + reporting an error, which has been fixed. + + * "git rebase -i" did not clear the state files correctly when a run + of "squash/fixup" is aborted and then the user manually amended the + commit instead, which has been corrected. + (merge 10d2f35436 js/rebase-i-autosquash-fix later to maint). + + * When fsmonitor is in use, after operation on submodules updates + .gitmodules, we lost track of the fact that we did so and relied on + stale fsmonitor data. + (merge 43f1180814 bp/mv-submodules-with-fsmonitor later to maint). + + * Fix for a long-standing bug that leaves the index file corrupt when + it shrinks during a partial commit. + (merge 6c003d6ffb jk/reopen-tempfile-truncate later to maint). + + * Further fix for O_APPEND emulation on Windows + (merge eeaf7ddac7 js/mingw-o-append later to maint). + + * A corner case bugfix in "git rerere" code. + (merge ad2bf0d9b4 en/rerere-multi-stage-1-fix later to maint). + + * "git add ':(attr:foo)'" is not supported and is supposed to be + rejected while the command line arguments are parsed, but we fail + to reject such a command line upfront. + (merge 84d938b732 nd/attr-pathspec-fix later to maint). + + * Recent update broke the reachability algorithm when refs (e.g. + tags) that point at objects that are not commit were involved, + which has been fixed. + + * "git rebase" etc. in Git 2.19 fails to abort when given an empty + commit log message as result of editing, which has been corrected. + (merge a3ec9eaf38 en/sequencer-empty-edit-result-aborts later to maint). + + * The code to backfill objects in lazily cloned repository did not + work correctly, which has been corrected. + (merge e68302011c jt/lazy-object-fetch-fix later to maint). + + * Update error messages given by "git remote" and make them consistent. + (merge 5025425dff ms/remote-error-message-update later to maint). + + * "git update-ref" learned to make both "--no-deref" and "--stdin" + work at the same time. + (merge d345e9fbe7 en/update-ref-no-deref-stdin later to maint). + + * Recently added "range-diff" had a corner-case bug to cause it + segfault, which has been corrected. + (merge e467a90c7a tg/range-diff-corner-case-fix later to maint). + + * The recently introduced commit-graph auxiliary data is incompatible + with mechanisms such as replace & grafts that "breaks" immutable + nature of the object reference relationship. Disable optimizations + based on its use (and updating existing commit-graph) when these + incompatible features are in use in the repository. + (merge 829a321569 ds/commit-graph-with-grafts later to maint). + + * The mailmap file update. + (merge 255eb03edf jn/mailmap-update later to maint). + + * The code in "git status" sometimes hit an assertion failure. This + was caused by a structure that was reused without cleaning the data + used for the first run, which has been corrected. + (merge 3e73cc62c0 en/status-multiple-renames-to-the-same-target-fix later to maint). + + * "git fetch $repo $object" in a partial clone did not correctly + fetch the asked-for object that is referenced by an object in + promisor packfile, which has been fixed. + + * A corner-case bugfix. + (merge c5cbb27cb5 sm/show-superproject-while-conflicted later to maint). + + * Various fixes to "diff --color-moved-ws". + + * A partial clone that is configured to lazily fetch missing objects + will on-demand issue a "git fetch" request to the originating + repository to fill not-yet-obtained objects. The request has been + optimized for requesting a tree object (and not the leaf blob + objects contained in it) by telling the originating repository that + no blobs are needed. + (merge 4c7f9567ea jt/non-blob-lazy-fetch later to maint). + + * The codepath to support the experimental split-index mode had + remaining "racily clean" issues fixed. + (merge 4c490f3d32 sg/split-index-racefix later to maint). + + * "git log --graph" showing an octopus merge sometimes miscounted the + number of display columns it is consuming to show the merge and its + parent commits, which has been corrected. + (merge 04005834ed np/log-graph-octopus-fix later to maint). + + * "git range-diff" did not work well when the compared ranges had + changes in submodules and the "--submodule=log" was used. + + * The implementation of run_command() API on the UNIX platforms had a + bug that caused a command not on $PATH to be found in the current + directory. + (merge f67b980771 jk/run-command-notdot later to maint). + + * A mutex used in "git pack-objects" were not correctly initialized + and this caused "git repack" to dump core on Windows. + (merge 34204c8166 js/pack-objects-mutex-init-fix later to maint). + + * Under certain circumstances, "git diff D:/a/b/c D:/a/b/d" on + Windows would strip initial parts from the paths because they + were not recognized as absolute, which has been corrected. + (merge ffd04e92e2 js/diff-notice-has-drive-prefix later to maint). + + * The receive.denyCurrentBranch=updateInstead codepath kicked in even + when the push should have been rejected due to other reasons, such + as it does not fast-forward or the update-hook rejects it, which + has been corrected. + (merge b072a25fad jc/receive-deny-current-branch-fix later to maint). + + * The logic to determine the archive type "git archive" uses did not + correctly kick in for "git archive --remote", which has been + corrected. + + * "git repack" in a shallow clone did not correctly update the + shallow points in the repository, leading to a repository that + does not pass fsck. + (merge 5dcfbf564c js/shallow-and-fetch-prune later to maint). + + * Some codepaths failed to form a proper URL when .gitmodules record + the URL to a submodule repository as relative to the repository of + superproject, which has been corrected. + (merge e0a862fdaf sb/submodule-url-to-absolute later to maint). + + * "git fetch" over protocol v2 into a shallow repository failed to + fetch full history behind a new tip of history that was diverged + before the cut-off point of the history that was previously fetched + shallowly. + + * The command line completion machinery (in contrib/) has been + updated to allow the completion script to tweak the list of options + that are reported by the parse-options machinery correctly. + (merge 276b49ff34 nd/completion-negation later to maint). + + * Operations on promisor objects make sense in the context of only a + small subset of the commands that internally use the revisions + machinery, but the "--exclude-promisor-objects" option were taken + and led to nonsense results by commands like "log", to which it + didn't make much sense. This has been corrected. + (merge 669b1d2aae md/exclude-promisor-objects-fix later to maint). + + * A regression in Git 2.12 era made "git fsck" fall into an infinite + loop while processing truncated loose objects. + (merge 18ad13e5b2 jk/detect-truncated-zlib-input later to maint). + + * "git ls-remote $there foo" was broken by recent update for the + protocol v2 and stopped showing refs that match 'foo' that are not + refs/{heads,tags}/foo, which has been fixed. + (merge 6a139cdd74 jk/proto-v2-ref-prefix-fix later to maint). + + * Additional comment on a tricky piece of code to help developers. + (merge 0afbe3e806 jk/stream-pack-non-delta-clarification later to maint). + + * A couple of tests used to leave the repository in a state that is + deliberately corrupt, which have been corrected. + (merge aa984dbe5e ab/pack-tests-cleanup later to maint). + + * The submodule support has been updated to read from the blob at + HEAD:.gitmodules when the .gitmodules file is missing from the + working tree. + (merge 2b1257e463 ao/submodule-wo-gitmodules-checked-out later to maint). + + * "git fetch" was a bit loose in parsing responses from the other side + when talking over the protocol v2. + + * "git rev-parse --exclude=* --branches --branches" (i.e. first + saying "add only things that do not match '*' out of all branches" + and then adding all branches, without any exclusion this time) + worked as expected, but "--exclude=* --all --all" did not work the + same way, which has been fixed. + (merge 5221048092 ag/rev-parse-all-exclude-fix later to maint). + + * "git send-email --transfer-encoding=..." in recent versions of Git + sometimes produced an empty "Content-Transfer-Encoding:" header, + which has been corrected. + (merge 3c88e46f1a al/send-email-auto-cte-fixup later to maint). + + * The interface into "xdiff" library used to discover the offset and + size of a generated patch hunk by first formatting it into the + textual hunk header "@@ -n,m +k,l @@" and then parsing the numbers + out. A new interface has been introduced to allow callers a more + direct access to them. + (merge 5eade0746e jk/xdiff-interface later to maint). + + * Pathspec matching against a tree object were buggy when negative + pathspec elements were involved, which has been fixed. + (merge b7845cebc0 nd/tree-walk-path-exclusion later to maint). + + * "git merge" and "git pull" that merges into an unborn branch used + to completely ignore "--verify-signatures", which has been + corrected. + (merge 01a31f3bca jk/verify-sig-merge-into-void later to maint). + + * "git rebase --autostash" did not correctly re-attach the HEAD at times. + + * "rev-parse --exclude=<pattern> --branches=<pattern>" etc. did not + quite work, which has been corrected. + (merge 9ab9b5df0e ra/rev-parse-exclude-glob later to maint). + + * When editing a patch in a "git add -i" session, a hunk could be + made to no-op. The "git apply" program used to reject a patch with + such a no-op hunk to catch user mistakes, but it is now updated to + explicitly allow a no-op hunk in an edited patch. + (merge 22cb3835b9 js/apply-recount-allow-noop later to maint). + + * The URL to an MSDN page in a comment has been updated. + (merge 2ef2ae2917 js/mingw-msdn-url later to maint). + + * "git ls-remote --sort=<thing>" can feed an object that is not yet + available into the comparison machinery and segfault, which has + been corrected to check such a request upfront and reject it. + + * When "git bundle" aborts due to an empty commit ranges + (i.e. resulting in an empty pack), it left a file descriptor to an + lockfile open, which resulted in leftover lockfile on Windows where + you cannot remove a file with an open file descriptor. This has + been corrected. + (merge 2c8ee1f53c jk/close-duped-fd-before-unlock-for-bundle later to maint). + + * "git format-patch --stat=<width>" can be used to specify the width + used by the diffstat (shown in the cover letter). + (merge 284aeb7e60 nd/format-patch-cover-letter-stat-width later to maint). + + * The way .git/index and .git/sharedindex* files were initially + created gave these files different perm bits until they were + adjusted for shared repository settings. This was made consistent. + (merge c9d6c78870 cc/shared-index-permbits later to maint). + + * "git rebase --stat" to transplant a piece of history onto a totally + unrelated history were not working before and silently showed wrong + result. With the recent reimplementation in C, it started to instead + die with an error message, as the original logic was not prepared + to cope with this case. This has now been fixed. + + * The advice message to tell the user to migrate an existing graft + file to the replace system when a graft file was read was shown + even when "git replace --convert-graft-file" command, which is the + way the message suggests to use, was running, which made little + sense. + (merge 8821e90a09 ab/replace-graft-with-replace-advice later to maint). + + * "git diff --raw" lost ellipses to adjust the output columns for + some time now, but the documentation still showed them. + + * Code cleanup, docfix, build fix, etc. + (merge 96a7501aad ts/doc-build-manpage-xsl-quietly later to maint). + (merge b9b07efdb2 tg/conflict-marker-size later to maint). + (merge fa0aeea770 sg/doc-trace-appends later to maint). + (merge d64324cb60 tb/void-check-attr later to maint). + (merge c3b9bc94b9 en/double-semicolon-fix later to maint). + (merge 79336116f5 sg/t3701-tighten-trace later to maint). + (merge 801fa63a90 jk/dev-build-format-security later to maint). + (merge 0597dd62ba sb/string-list-remove-unused later to maint). + (merge db2d36fad8 bw/protocol-v2 later to maint). + (merge 456d7cd3a9 sg/split-index-test later to maint). + (merge 7b6057c852 tq/refs-internal-comment-fix later to maint). + (merge 29e8dc50ad tg/t5551-with-curl-7.61.1 later to maint). + (merge 55f6bce2c9 fe/doc-updates later to maint). + (merge 7987d2232d jk/check-everything-connected-is-long-gone later to maint). + (merge 4ba3c9be47 dz/credential-doc-url-matching-rules later to maint). + (merge 4c399442f7 ma/commit-graph-docs later to maint). + (merge fc0503b04e ma/t1400-undebug-test later to maint). + (merge e56b53553a nd/packobjectshook-doc-fix later to maint). + (merge c56170a0c4 ma/mailing-list-address-in-git-help later to maint). + (merge 6e8fc70fce rs/sequencer-oidset-insert-avoids-dups later to maint). + (merge ad0b8f9575 mw/doc-typofixes later to maint). + (merge d9f079ad1a jc/how-to-document-api later to maint). + (merge b1492bf315 ma/t7005-bash-workaround later to maint). + (merge ac1f98a0df du/rev-parse-is-plumbing later to maint). + (merge ca8ed443a5 mm/doc-no-dashed-git later to maint). + (merge ce366a8144 du/get-tar-commit-id-is-plumbing later to maint). + (merge 61018fe9e0 du/cherry-is-plumbing later to maint). + (merge c7e5fe79b9 sb/strbuf-h-update later to maint). + (merge 8d2008196b tq/branch-create-wo-branch-get later to maint). + (merge 2e3c894f4b tq/branch-style-fix later to maint). + (merge c5d844af9c sg/doc-show-branch-typofix later to maint). + (merge 081d91618b ah/doc-updates later to maint). + (merge b84c783882 jc/cocci-preincr later to maint). + (merge 5e495f8122 uk/merge-subtree-doc-update later to maint). + (merge aaaa881822 jk/uploadpack-packobjectshook-fix later to maint). + (merge 3063477445 tb/char-may-be-unsigned later to maint). + (merge 8c64bc9420 sg/test-rebase-editor-fix later to maint). + (merge 71571cd7d6 ma/sequencer-do-reset-saner-loop-termination later to maint). + (merge 9a4cb8781e cb/notes-freeing-always-null-fix later to maint). + (merge 3006f5ee16 ma/reset-doc-rendering-fix later to maint). + (merge 4c2eb06419 sg/daemon-test-signal-fix later to maint). + (merge d27525e519 ss/msvc-strcasecmp later to maint). diff --git a/Documentation/RelNotes/2.20.1.txt b/Documentation/RelNotes/2.20.1.txt new file mode 100644 index 0000000000..dcba888dba --- /dev/null +++ b/Documentation/RelNotes/2.20.1.txt @@ -0,0 +1,20 @@ +Git v2.20.1 Release Notes +========================= + +This release is primarily to fix brown-paper-bag breakages in the +2.20.0 release. + +Fixes since v2.20 +----------------- + + * A few newly added tests were not portable and caused minority + platforms to report false breakages, which have been fixed. + + * Portability fix for a recent update to parse-options API. + + * "git help -a" did not work well when an overly long alias is + defined, which has been corrected. + + * A recent update accidentally squelched an error message when the + run_command API failed to run a missing command, which has been + corrected. diff --git a/Documentation/RelNotes/2.20.2.txt b/Documentation/RelNotes/2.20.2.txt new file mode 100644 index 0000000000..8e680cb9fb --- /dev/null +++ b/Documentation/RelNotes/2.20.2.txt @@ -0,0 +1,18 @@ +Git v2.20.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4 +and in v2.17.3, addressing the security issues CVE-2019-1348, +CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, +CVE-2019-1353, CVE-2019-1354, and CVE-2019-1387; see the release notes +for those versions for details. + +The change to disallow `submodule.<name>.update=!command` entries in +`.gitmodules` which was introduced v2.15.4 (and for which v2.17.3 +added explicit fsck checks) fixes the vulnerability in v2.20.x where a +recursive clone followed by a submodule update could execute code +contained within the repository without the user explicitly having +asked for that (CVE-2019-19604). + +Credit for finding this vulnerability goes to Joern Schneeweisz, +credit for the fixes goes to Jonathan Nieder. diff --git a/Documentation/RelNotes/2.20.3.txt b/Documentation/RelNotes/2.20.3.txt new file mode 100644 index 0000000000..f6eccd103b --- /dev/null +++ b/Documentation/RelNotes/2.20.3.txt @@ -0,0 +1,5 @@ +Git v2.20.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.20.4.txt b/Documentation/RelNotes/2.20.4.txt new file mode 100644 index 0000000000..5a9e24e470 --- /dev/null +++ b/Documentation/RelNotes/2.20.4.txt @@ -0,0 +1,5 @@ +Git v2.20.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.21.0.txt b/Documentation/RelNotes/2.21.0.txt new file mode 100644 index 0000000000..7a49deddf3 --- /dev/null +++ b/Documentation/RelNotes/2.21.0.txt @@ -0,0 +1,451 @@ +Git 2.21 Release Notes +====================== + +Backward Compatibility Notes +---------------------------- + + * Historically, the "-m" (mainline) option can only be used for "git + cherry-pick" and "git revert" when working with a merge commit. + This version of Git no longer warns or errors out when working with + a single-parent commit, as long as the argument to the "-m" option + is 1 (i.e. it has only one parent, and the request is to pick or + revert relative to that first parent). Scripts that relied on the + behaviour may get broken with this change. + + +Updates since v2.20 +------------------- + +UI, Workflows & Features + + * The "http.version" configuration variable can be used with recent + enough versions of cURL library to force the version of HTTP used + to talk when fetching and pushing. + + * Small fixes and features for fast-export and fast-import, mostly on + the fast-export side has been made. + + * "git push $there $src:$dst" rejects when $dst is not a fully + qualified refname and it is not clear what the end user meant. The + codepath has been taught to give a clearer error message, and also + guess where the push should go by taking the type of the pushed + object into account (e.g. a tag object would want to go under + refs/tags/). + + * "git checkout [<tree-ish>] path..." learned to report the number of + paths that have been checked out of the index or the tree-ish, + which gives it the same degree of noisy-ness as the case in which + the command checks out a branch. "git checkout -m <pathspec>" to + undo conflict resolution gives a similar message. + + * "git quiltimport" learned "--keep-non-patch" option. + + * "git worktree remove" and "git worktree move" refused to work when + there is a submodule involved. This has been loosened to ignore + uninitialized submodules. + + * "git cherry-pick -m1" was forbidden when picking a non-merge + commit, even though there _is_ parent number 1 for such a commit. + This was done to avoid mistakes back when "cherry-pick" was about + picking a single commit, but is no longer useful with "cherry-pick" + that can pick a range of commits. Now the "-m$num" option is + allowed when picking any commit, as long as $num names an existing + parent of the commit. + + * Update "git multimail" from the upstream. + + * "git p4" update. + + * The "--format=<placeholder>" option of for-each-ref, branch and tag + learned to show a few more traits of objects that can be learned by + the object_info API. + + * "git rebase -i" learned to re-execute a command given with 'exec' + to run after it failed the last time. + + * "git diff --color-moved-ws" updates. + + * Custom userformat "log --format" learned %S atom that stands for + the tip the traversal reached the commit from, i.e. --source. + + * "git instaweb" learned to drive http.server that comes with + "batteries included" Python installation (both Python2 & 3). + + * A new encoding UTF-16LE-BOM has been invented to force encoding to + UTF-16 with BOM in little endian byte order, which cannot be directly + generated by using iconv. + + * A new date format "--date=human" that morphs its output depending + on how far the time is from the current time has been introduced. + "--date=auto:human" can be used to use this new format (or any + existing format) when the output is going to the pager or to the + terminal, and otherwise the default format. + + +Performance, Internal Implementation, Development Support etc. + + * Code clean-up with optimization for the codepath that checks + (non-)existence of loose objects. + + * More codepaths have become aware of working with in-core repository + instances other than the default "the_repository". + + * The "strncat()" function is now among the banned functions. + + * Portability updates for the HPE NonStop platform. + + * Earlier we added "-Wformat-security" to developer builds, assuming + that "-Wall" (which includes "-Wformat" which in turn is required + to use "-Wformat-security") is always in effect. This is not true + when config.mak.autogen is in use, unfortunately. This has been + fixed by unconditionally adding "-Wall" to developer builds. + + * The loose object cache used to optimize existence look-up has been + updated. + + * Flaky tests can now be repeatedly run under load with the + "--stress" option. + + * Documentation/Makefile is getting prepared for manpage + localization. + + * "git fetch-pack" now can talk the version 2 protocol. + + * sha-256 hash has been added and plumbed through the code to allow + building Git with the "NewHash". + + * Debugging help for http transport. + + * "git fetch --deepen=<more>" has been corrected to work over v2 + protocol. + + * The code to walk tree objects has been taught that we may be + working with object names that are not computed with SHA-1. + + * The in-core repository instances are passed through more codepaths. + + * Update the protocol message specification to allow only the limited + use of scaled quantities. This is to ensure potential compatibility + issues will not get out of hand. + + * Micro-optimize the code that prepares commit objects to be walked + by "git rev-list" when the commit-graph is available. + + * "git fetch" and "git upload-pack" learned to send all exchanges over + the sideband channel while talking the v2 protocol. + + * The codepath to write out commit-graph has been optimized by + following the usual pattern of visiting objects in in-pack order. + + * The codepath to show progress meter while writing out commit-graph + file has been improved. + + * Cocci rules have been updated to encourage use of strbuf_addbuf(). + + * "git rebase --merge" has been reimplemented by reusing the internal + machinery used for "git rebase -i". + + * More code in "git bisect" has been rewritten in C. + + * Instead of going through "git-rebase--am" scriptlet to use the "am" + backend, the built-in version of "git rebase" learned to drive the + "am" backend directly. + + * The assumption to work on the single "in-core index" instance has + been reduced from the library-ish part of the codebase. + + * The test lint learned to catch non-portable "sed" options. + + * "git pack-objects" learned another algorithm to compute the set of + objects to send, that trades the resulting packfile off to save + traversal cost to favor small pushes. + + * The travis CI scripts have been corrected to build Git with the + compiler(s) of our choice. + + * "git submodule update" learned to abort early when core.worktree + for the submodule is not set correctly to prevent spreading damage. + + * Test suite has been adjusted to run on Azure Pipeline. + + * Running "Documentation/doc-diff x" from anywhere other than the + top-level of the working tree did not show the usage string + correctly, which has been fixed. + + * Use of the sparse tool got easier to customize from the command + line to help developers. + + * A new target "coverage-prove" to run the coverage test under + "prove" has been added. + + * A flakey "p4" test has been removed. + + * The code and tests assume that the system supplied iconv() would + always use BOM in its output when asked to encode to UTF-16 (or + UTF-32), but apparently some implementations output big-endian + without BOM. A compile-time knob has been added to help such + systems (e.g. NonStop) to add BOM to the output to increase + portability. + + +Fixes since v2.20 +----------------- + + * Updates for corner cases in merge-recursive. + (merge cc4cb0902c en/merge-path-collision later to maint). + + * "git checkout frotz" (without any double-dash) avoids ambiguity by + making sure 'frotz' cannot be interpreted as a revision and as a + path at the same time. This safety has been updated to check also + a unique remote-tracking branch 'frotz' in a remote, when dwimming + to create a local branch 'frotz' out of a remote-tracking branch + 'frotz' from a remote. + (merge be4908f103 nd/checkout-dwim-fix later to maint). + + * Refspecs configured with "git -c var=val clone" did not propagate + to the resulting repository, which has been corrected. + (merge 7eae4a3ac4 sg/clone-initial-fetch-configuration later to maint). + + * A properly configured username/email is required under + user.useConfigOnly in order to create commits; now "git stash" + (even though it creates commit objects to represent stash entries) + command is exempt from the requirement. + (merge 3bc2111fc2 sd/stash-wo-user-name later to maint). + + * The http-backend CGI process did not correctly clean up the child + processes it spawns to run upload-pack etc. when it dies itself, + which has been corrected. + (merge 02818a98d7 mk/http-backend-kill-children-before-exit later to maint). + + * "git rev-list --exclude-promisor-objects" had to take an object + that does not exist locally (and is lazily available) from the + command line without barfing, but the code dereferenced NULL. + (merge 4cf67869b2 md/list-lazy-objects-fix later to maint). + + * The traversal over tree objects has learned to honor + ":(attr:label)" pathspec match, which has been implemented only for + enumerating paths on the filesystem. + (merge 5a0b97b34c nd/attr-pathspec-in-tree-walk later to maint). + + * BSD port updates. + (merge 4e3ecbd439 cb/openbsd-allows-reading-directory later to maint). + (merge b6bdc2a0f5 cb/t5004-empty-tar-archive-fix later to maint). + (merge 82cbc8cde2 cb/test-lint-cp-a later to maint). + + * Lines that begin with a certain keyword that come over the wire, as + well as lines that consist only of one of these keywords, ought to + be painted in color for easier eyeballing, but the latter was + broken ever since the feature was introduced in 2.19, which has + been corrected. + (merge 1f67290450 hn/highlight-sideband-keywords later to maint). + + * "git log -G<regex>" looked for a hunk in the "git log -p" patch + output that contained a string that matches the given pattern. + Optimize this code to ignore binary files, which by default will + not show any hunk that would match any pattern (unless textconv or + the --text option is in effect, that is). + (merge e0e7cb8080 tb/log-G-binary later to maint). + + * "git submodule update" ought to use a single job unless asked, but + by mistake used multiple jobs, which has been fixed. + (merge e3a9d1aca9 sb/submodule-fetchjobs-default-to-one later to maint). + + * "git stripspace" should be usable outside a git repository, but + under the "-s" or "-c" mode, it didn't. + (merge 957da75802 jn/stripspace-wo-repository later to maint). + + * Some of the documentation pages formatted incorrectly with + Asciidoctor, which have been fixed. + (merge b62eb1d2f4 ma/asciidoctor later to maint). + + * The core.worktree setting in a submodule repository should not be + pointing at a directory when the submodule loses its working tree + (e.g. getting deinit'ed), but the code did not properly maintain + this invariant. + + * With zsh, "git cmd path<TAB>" was completed to "git cmd path name" + when the completed path has a special character like SP in it, + without any attempt to keep "path name" a single filename. This + has been fixed to complete it to "git cmd path\ name" just like + Bash completion does. + + * The test suite tried to see if it is run under bash, but the check + itself failed under some other implementations of shell (notably + under NetBSD). This has been corrected. + (merge 54ea72f09c sg/test-bash-version-fix later to maint). + + * "git gc" and "git repack" did not close the open packfiles that + they found unneeded before removing them, which didn't work on a + platform incapable of removing an open file. This has been + corrected. + (merge 5bdece0d70 js/gc-repack-close-before-remove later to maint). + + * The code to drive GIT_EXTERNAL_DIFF command relied on the string + returned from getenv() to be non-volatile, which is not true, that + has been corrected. + (merge 6776a84dae kg/external-diff-save-env later to maint). + + * There were many places the code relied on the string returned from + getenv() to be non-volatile, which is not true, that have been + corrected. + (merge 0da0e9268b jk/save-getenv-result later to maint). + + * The v2 upload-pack protocol implementation failed to honor + hidden-ref configuration, which has been corrected. + (merge e20b4192a3 jk/proto-v2-hidden-refs-fix later to maint). + + * "git fetch --recurse-submodules" may not fetch the necessary commit + that is bound to the superproject, which is getting corrected. + (merge be76c21282 sb/submodule-recursive-fetch-gets-the-tip later to maint). + + * "git rebase" internally runs "checkout" to switch between branches, + and the command used to call the post-checkout hook, but the + reimplementation stopped doing so, which is getting fixed. + + * "git add -e" got confused when the change it wants to let the user + edit is smaller than the previous change that was left over in a + temporary file. + (merge fa6f225e01 js/add-e-clear-patch-before-stating later to maint). + + * "git p4" failed to update a shelved change when there were moved + files, which has been corrected. + (merge 7a10946ab9 ld/git-p4-shelve-update-fix later to maint). + + * The codepath to read from the commit-graph file attempted to read + past the end of it when the file's table-of-contents was corrupt. + + * The compat/obstack code had casts that -Wcast-function-type + compilation option found questionable. + (merge 764473d257 sg/obstack-cast-function-type-fix later to maint). + + * An obvious typo in an assertion error message has been fixed. + (merge 3c27e2e059 cc/test-ref-store-typofix later to maint). + + * In Git for Windows, "git clone \\server\share\path" etc. that uses + UNC paths from command line had bad interaction with its shell + emulation. + + * "git add --ignore-errors" did not work as advertised and instead + worked as an unintended synonym for "git add --renormalize", which + has been fixed. + (merge e2c2a37545 jk/add-ignore-errors-bit-assignment-fix later to maint). + + * On a case-insensitive filesystem, we failed to compare the part of + the path that is above the worktree directory in an absolute + pathname, which has been corrected. + + * Asking "git check-attr" about a macro (e.g. "binary") on a specific + path did not work correctly, even though "git check-attr -a" listed + such a macro correctly. This has been corrected. + (merge 7b95849be4 jk/attr-macro-fix later to maint). + + * "git pack-objects" incorrectly used uninitialized mutex, which has + been corrected. + (merge edb673cf10 ph/pack-objects-mutex-fix later to maint). + + * "git checkout -b <new> [HEAD]" to create a new branch from the + current commit and check it out ought to be a no-op in the index + and the working tree in normal cases, but there are corner cases + that do require updates to the index and the working tree. Running + it immediately after "git clone --no-checkout" is one of these + cases that an earlier optimization kicked in incorrectly, which has + been fixed. + (merge 8424bfd45b bp/checkout-new-branch-optim later to maint). + + * "git diff --color-moved --cc --stat -p" did not work well due to + funny interaction between a bug in color-moved and the rest, which + has been fixed. + (merge dac03b5518 jk/diff-cc-stat-fixes later to maint). + + * When GIT_SEQUENCE_EDITOR is set, the command was incorrectly + started when modes of "git rebase" that implicitly uses the + machinery for the interactive rebase are run, which has been + corrected. + (merge 891d4a0313 pw/no-editor-in-rebase-i-implicit later to maint). + + * The commit-graph facility did not work when in-core objects that + are promoted from unknown type to commit (e.g. a commit that is + accessed via a tag that refers to it) were involved, which has been + corrected. + (merge 4468d4435c sg/object-as-type-commit-graph-fix later to maint). + + * "git fetch" output cleanup. + (merge dc40b24df4 nd/fetch-compact-update later to maint). + + * "git cat-file --batch" reported a dangling symbolic link by + mistake, when it wanted to report that a given name is ambiguous. + + * Documentation around core.crlf has been updated. + (merge c9446f0504 jk/autocrlf-overrides-eol-doc later to maint). + + * The documentation of "git commit-tree" said that the command + understands "--gpg-sign" in addition to "-S", but the command line + parser did not know about the longhand, which has been corrected. + + * "git rebase -x $cmd" did not reject multi-line command, even though + the command is incapable of handling such a command. It now is + rejected upfront. + (merge c762aada1a pw/rebase-x-sanity-check later to maint). + + * Output from "git help" was not correctly aligned, which has been + fixed. + (merge 6195a76da4 nd/help-align-command-desc later to maint). + + * The "git submodule summary" subcommand showed shortened commit + object names by mechanically truncating them at 7-hexdigit, which + has been improved to let "rev-parse --short" scale the length of + the abbreviation with the size of the repository. + (merge 0586a438f6 sh/submodule-summary-abbrev-fix later to maint). + + * The way the OSX build jobs updates its build environment used the + "--quiet" option to "brew update" command, but it wasn't all that + quiet to be useful. The use of the option has been replaced with + an explicit redirection to the /dev/null (which incidentally would + have worked around a breakage by recent updates to homebrew, which + has fixed itself already). + (merge a1ccaedd62 sg/travis-osx-brew-breakage-workaround later to maint). + + * "git --work-tree=$there --git-dir=$here describe --dirty" did not + work correctly as it did not pay attention to the location of the + worktree specified by the user by mistake, which has been + corrected. + (merge c801170b0c ss/describe-dirty-in-the-right-directory later to maint). + + * "git fetch" over protocol v2 that needs to make a second connection + to backfill tags did not clear a variable that holds shallow + repository information correctly, leading to an access of freed + piece of memory. + + * Some errors from the other side coming over smart HTTP transport + were not noticed, which has been corrected. + + * Code cleanup, docfix, build fix, etc. + (merge 89ba9a79ae hb/t0061-dot-in-path-fix later to maint). + (merge d173e799ea sb/diff-color-moved-config-option-fixup later to maint). + (merge a8f5a59067 en/directory-renames-nothanks-doc-update later to maint). + (merge ec36c42a63 nd/indentation-fix later to maint). + (merge f116ee21cd do/gitweb-strict-export-conf-doc later to maint). + (merge 112ea42663 fd/gitweb-snapshot-conf-doc-fix later to maint). + (merge 1cadad6f65 tb/use-common-win32-pathfuncs-on-cygwin later to maint). + (merge 57e9dcaa65 km/rebase-doc-typofix later to maint). + (merge b8b4cb27e6 ds/gc-doc-typofix later to maint). + (merge 3b3357626e nd/style-opening-brace later to maint). + (merge b4583d5595 es/doc-worktree-guessremote-config later to maint). + (merge cce99cd8c6 ds/commit-graph-assert-missing-parents later to maint). + (merge 0650614982 cy/completion-typofix later to maint). + (merge 6881925ef5 rs/sha1-file-close-mapped-file-on-error later to maint). + (merge bd8d6f0def en/show-ref-doc-fix later to maint). + (merge 1747125e2c cc/partial-clone-doc-typofix later to maint). + (merge e01378753d cc/fetch-error-message-fix later to maint). + (merge 54e8c11215 jk/remote-insteadof-cleanup later to maint). + (merge d609615f48 js/test-git-installed later to maint). + (merge ba170517be ja/doc-style-fix later to maint). + (merge 86fb1c4e77 km/init-doc-typofix later to maint). + (merge 5cfd4a9d10 nd/commit-doc later to maint). + (merge 9fce19a431 ab/diff-tree-doc-fix later to maint). + (merge 2e285e7803 tz/gpg-test-fix later to maint). + (merge 5427de960b kl/pretty-doc-markup-fix later to maint). + (merge 3815f64b0d js/mingw-host-cpu later to maint). + (merge 5fe81438b5 rj/sequencer-sign-off-header-static later to maint). + (merge 18a4f6be6b nd/fileno-may-be-macro later to maint). + (merge 99e9ab54ab kd/t0028-octal-del-is-377-not-777 later to maint). diff --git a/Documentation/RelNotes/2.21.1.txt b/Documentation/RelNotes/2.21.1.txt new file mode 100644 index 0000000000..b7594151e4 --- /dev/null +++ b/Documentation/RelNotes/2.21.1.txt @@ -0,0 +1,12 @@ +Git v2.21.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4, +v2.17.3 and in v2.20.2, addressing the security issues CVE-2019-1348, +CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, CVE-2019-1352, +CVE-2019-1353, CVE-2019-1354, CVE-2019-1387, and CVE-2019-19604; +see the release notes for those versions for details. + +Additionally, this version also includes a couple of fixes for the +Windows-specific quoting of command-line arguments when Git executes +a Unix shell on Windows. diff --git a/Documentation/RelNotes/2.21.2.txt b/Documentation/RelNotes/2.21.2.txt new file mode 100644 index 0000000000..a0fb83bb53 --- /dev/null +++ b/Documentation/RelNotes/2.21.2.txt @@ -0,0 +1,5 @@ +Git v2.21.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.21.3.txt b/Documentation/RelNotes/2.21.3.txt new file mode 100644 index 0000000000..2ca0aa5c62 --- /dev/null +++ b/Documentation/RelNotes/2.21.3.txt @@ -0,0 +1,5 @@ +Git v2.21.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.22.0.txt b/Documentation/RelNotes/2.22.0.txt new file mode 100644 index 0000000000..91e6ae9887 --- /dev/null +++ b/Documentation/RelNotes/2.22.0.txt @@ -0,0 +1,597 @@ +Git 2.22 Release Notes +====================== + +Updates since v2.21 +------------------- + +Backward compatibility note + + * The filter specification "--filter=sparse:path=<path>" used to + create a lazy/partial clone has been removed. Using a blob that is + part of the project as sparse specification is still supported with + the "--filter=sparse:oid=<blob>" option. + +UI, Workflows & Features + + * "git checkout --no-overlay" can be used to trigger a new mode of + checking out paths out of the tree-ish, that allows paths that + match the pathspec that are in the current index and working tree + and are not in the tree-ish. + + * The %(trailers) formatter in "git log --format=..." now allows to + optionally pick trailers selectively by keyword, show only values, + etc. + + * Four new configuration variables {author,committer}.{name,email} + have been introduced to override user.{name,email} in more specific + cases. + + * Command-line completion (in contrib/) learned to tab-complete the + "git submodule absorbgitdirs" subcommand. + + * "git branch" learned a new subcommand "--show-current". + + * Output from "diff --cc" did not show the original paths when the + merge involved renames. A new option adds the paths in the + original trees to the output. + + * The command line completion (in contrib/) has been taught to + complete more subcommand parameters. + + * The final report from "git bisect" used to show the suspected + culprit using a raw "diff-tree", with which there is no output for + a merge commit. This has been updated to use a more modern and + human readable output that still is concise enough. + + * "git rebase --rebase-merges" replaces its old "--preserve-merges" + option; the latter is now marked as deprecated. + + * Error message given while cloning with --recurse-submodules has + been updated. + + * The completion helper code now pays attention to repository-local + configuration (when available), which allows --list-cmds to honour + a repository specific setting of completion.commands, for example. + + * "git mergetool" learned to offer Sublime Merge (smerge) as one of + its backends. + + * A new hook "post-index-change" is called when the on-disk index + file changes, which can help e.g. a virtualized working tree + implementation. + + * "git difftool" can now run outside a repository. + + * "git checkout -m <other>" was about carrying the differences + between HEAD and the working-tree files forward while checking out + another branch, and ignored the differences between HEAD and the + index. The command has been taught to abort when the index and the + HEAD are different. + + * A progress indicator has been added to the "index-pack" step, which + often makes users wait for completion during "git clone". + + * "git submodule" learns "set-branch" subcommand that allows the + submodule.*.branch settings to be modified. + + * "git merge-recursive" backend recently learned a new heuristics to + infer file movement based on how other files in the same directory + moved. As this is inherently less robust heuristics than the one + based on the content similarity of the file itself (rather than + based on what its neighbours are doing), it sometimes gives an + outcome unexpected by the end users. This has been toned down to + leave the renamed paths in higher/conflicted stages in the index so + that the user can examine and confirm the result. + + * "git tag" learned to give an advice suggesting it might be a + mistake when creating an annotated or signed tag that points at + another tag. + + * The "git pack-objects" command learned to report the number of + objects it packed via the trace2 mechanism. + + * The list of conflicted paths shown in the editor while concluding a + conflicted merge was shown above the scissors line when the + clean-up mode is set to "scissors", even though it was commented + out just like the list of updated paths and other information to + help the user explain the merge better. + + * The trace2 tracing facility learned to auto-generate a filename + when told to log to a directory. + + * "git clone" learned a new --server-option option when talking over + the protocol version 2. + + * The connectivity bitmaps are created by default in bare + repositories now; also the pathname hash-cache is created by + default to avoid making crappy deltas when repacking. + + * "git branch new A...B" and "git checkout -b new A...B" have been + taught that in their contexts, the notation A...B means "the merge + base between these two commits", just like "git checkout A...B" + detaches HEAD at that commit. + + * Update "git difftool" and "git mergetool" so that the combinations + of {diff,merge}.{tool,guitool} configuration variables serve as + fallback settings of each other in a sensible order. + + * The "--dir-diff" mode of "git difftool" is not useful in "--no-index" + mode; they are now explicitly marked as mutually incompatible. + + +Performance, Internal Implementation, Development Support etc. + + * The diff machinery, one of the oldest parts of the system, which + long predates the parse-options API, uses fairly long and complex + handcrafted option parser. This is being rewritten to use the + parse-options API. + + * The implementation of pack-redundant has been updated for + performance in a repository with many packfiles. + + * A more structured way to obtain execution trace has been added. + + * "git prune" has been taught to take advantage of reachability + bitmap when able. + + * The command line parser of "git commit-tree" has been rewritten to + use the parse-options API. + + * Suggest GitGitGadget instead of submitGit as a way to submit + patches based on GitHub PR to us. + + * The test framework has been updated to help developers by making it + easier to run most of the tests under different versions of + over-the-wire protocols. + + * Dev support update to make it easier to compare two formatted + results from our documentation. + + * The scripted "git rebase" implementation has been retired. + + * "git multi-pack-index verify" did not scale well with the number of + packfiles, which is being improved. + + * "git stash" has been rewritten in C. + + * The "check-docs" Makefile target to support developers has been + updated. + + * The tests have been updated not to rely on the abbreviated option + names the parse-options API offers, to protect us from an + abbreviated form of an option that used to be unique within the + command getting non-unique when a new option that share the same + prefix is added. + + * The scripted version of "git rebase -i" wrote and rewrote the todo + list many times during a single step of its operation, and the + recent C-rewrite made a faithful conversion of the logic to C. The + implementation has been updated to carry necessary information + around in-core to avoid rewriting the same file over and over + unnecessarily. + + * Test framework update to more robustly clean up leftover files and + processes after tests are done. + + * Conversion from unsigned char[20] to struct object_id continues. + + * While running "git diff" in a lazy clone, we can upfront know which + missing blobs we will need, instead of waiting for the on-demand + machinery to discover them one by one. The code learned to aim to + achieve better performance by batching the request for these + promised blobs. + + * During an initial "git clone --depth=..." partial clone, it is + pointless to spend cycles for a large portion of the connectivity + check that enumerates and skips promisor objects (which by + definition is all objects fetched from the other side). This has + been optimized out. + + * Mechanically and systematically drop "extern" from function + declaration. + + * The script to aggregate perf result unconditionally depended on + libjson-perl even though it did not have to, which has been + corrected. + + * The internal implementation of "git rebase -i" has been updated to + avoid forking a separate "rebase--interactive" process. + + * Allow DEP and ASLR for Windows build to for security hardening. + + * Performance test framework has been broken and measured the version + of Git that happens to be on $PATH, not the specified one to + measure, for a while, which has been corrected. + + * Optionally "make coccicheck" can feed multiple source files to + spatch, gaining performance while spending more memory. + + * Attempt to use an abbreviated option in "git clone --recurs" is + responded by a request to disambiguate between --recursive and + --recurse-submodules, which is bad because these two are synonyms. + The parse-options API has been extended to define such synonyms + more easily and not produce an unnecessary failure. + + * A pair of private functions in http.c that had names similar to + fread/fwrite did not return the number of elements, which was found + to be confusing. + + * Update collision-detecting SHA-1 code to build properly on HP-UX. + + +Fixes since v2.21 +----------------- + + * "git prune-packed" did not notice and complain against excess + arguments given from the command line, which now it does. + (merge 9b0bd87ed2 rj/prune-packed-excess-args later to maint). + + * Split-index fix. + (merge 6e37c8ed3c nd/split-index-null-base-fix later to maint). + + * "git diff --no-index" may still want to access Git goodies like + --ext-diff and --textconv, but so far these have been ignored, + which has been corrected. + (merge 287ab28bfa jk/diff-no-index-initialize later to maint). + + * Unify RPC code for smart http in protocol v0/v1 and v2, which fixes + a bug in the latter (lack of authentication retry) and generally + improves the code base. + (merge a97d00799a jt/http-auth-proto-v2-fix later to maint). + + * The include file compat/bswap.h has been updated so that it is safe + to (accidentally) include it more than once. + (merge 33aa579a55 jk/guard-bswap-header later to maint). + + * The set of header files used by "make hdr-check" unconditionally + included sha256/gcrypt.h, even when it is not used, causing the + make target to fail. We now skip it when GCRYPT_SHA256 is not in + use. + (merge f23aa18e7f rj/hdr-check-gcrypt-fix later to maint). + + * The Makefile uses 'find' utility to enumerate all the *.h header + files, which is expensive on platforms with slow filesystems; it + now optionally uses "ls-files" if working within a repository, + which is a trick similar to how all sources are enumerated to run + ETAGS on. + (merge 92b88eba9f js/find-lib-h-with-ls-files-when-possible later to maint). + + * "git rebase" that was reimplemented in C did not set ORIG_HEAD + correctly, which has been corrected. + (merge cbd29ead92 js/rebase-orig-head-fix later to maint). + + * Dev support. + (merge f545737144 js/stress-test-ui-tweak later to maint). + + * CFLAGS now can be tweaked when invoking Make while using + DEVELOPER=YesPlease; this did not work well before. + (merge 6d5d4b4e93 ab/makefile-help-devs-more later to maint). + + * "git fsck --connectivity-only" omits computation necessary to sift + the objects that are not reachable from any of the refs into + unreachable and dangling. This is now enabled when dangling + objects are requested (which is done by default, but can be + overridden with the "--no-dangling" option). + (merge 8d8c2a5aef jk/fsck-doc later to maint). + + * On platforms where "git fetch" is killed with SIGPIPE (e.g. OSX), + the upload-pack that runs on the other end that hangs up after + detecting an error could cause "git fetch" to die with a signal, + which led to a flaky test. "git fetch" now ignores SIGPIPE during + the network portion of its operation (this is not a problem as we + check the return status from our write(2)s). + (merge 143588949c jk/no-sigpipe-during-network-transport later to maint). + + * A recent update broke "is this object available to us?" check for + well-known objects like an empty tree (which should yield "yes", + even when there is no on-disk object for an empty tree), which has + been corrected. + (merge f06ab027ef jk/virtual-objects-do-exist later to maint). + + * The setup code has been cleaned up to avoid leaks around the + repository_format structure. + (merge e8805af1c3 ma/clear-repository-format later to maint). + + * "git config --type=color ..." is meant to replace "git config --get-color" + but there is a slight difference that wasn't documented, which is + now fixed. + (merge cd8e7593b9 jk/config-type-color-ends-with-lf later to maint). + + * When the "clean" filter can reduce the size of a huge file in the + working tree down to a small "token" (a la Git LFS), there is no + point in allocating a huge scratch area upfront, but the buffer is + sized based on the original file size. The convert mechanism now + allocates very minimum and reallocates as it receives the output + from the clean filter process. + (merge 02156ab031 jh/resize-convert-scratch-buffer later to maint). + + * "git rebase" uses the refs/rewritten/ hierarchy to store its + intermediate states, which inherently makes the hierarchy per + worktree, but it didn't quite work well. + (merge b9317d55a3 nd/rewritten-ref-is-per-worktree later to maint). + + * "git log -L<from>,<to>:<path>" with "-s" did not suppress the patch + output as it should. This has been corrected. + (merge 05314efaea jk/line-log-with-patch later to maint). + + * "git worktree add" used to do a "find an available name with stat + and then mkdir", which is race-prone. This has been fixed by using + mkdir and reacting to EEXIST in a loop. + (merge 7af01f2367 ms/worktree-add-atomic-mkdir later to maint). + + * Build update for SHA-1 with collision detection. + (merge 07a20f569b jk/sha1dc later to maint). + + * Build procedure has been fixed around use of asciidoctor instead of + asciidoc. + (merge 185f9a0ea0 ma/asciidoctor-fixes later to maint). + + * remote-http transport did not anonymize URLs reported in its error + messages at places. + (merge c1284b21f2 js/anonymize-remote-curl-diag later to maint). + + * Error messages given from the http transport have been updated so + that they can be localized. + (merge ed8b4132c8 js/remote-curl-i18n later to maint). + + * "git init" forgot to read platform-specific repository + configuration, which made Windows port to ignore settings of + core.hidedotfiles, for example. + + * A corner-case object name ambiguity while the sequencer machinery + is working (e.g. "rebase -i -x") has been fixed. + + * "git format-patch" did not diagnose an error while opening the + output file for the cover-letter, which has been corrected. + (merge 2fe95f494c jc/format-patch-error-check later to maint). + + * "git checkout -f <branch>" while the index has an unmerged path + incorrectly left some paths in an unmerged state, which has been + corrected. + + * A corner case bug in the refs API has been corrected. + (merge d3322eb28b jk/refs-double-abort later to maint). + + * Unicode update. + (merge 584b62c37b bb/unicode-12 later to maint). + + * dumb-http walker has been updated to share more error recovery + strategy with the normal codepath. + + * A buglet in configuration parser has been fixed. + (merge 19e7fdaa58 nd/include-if-wildmatch later to maint). + + * The documentation for "git read-tree --reset -u" has been updated. + (merge b5a0bd694c nd/read-tree-reset-doc later to maint). + + * Code clean-up around a much-less-important-than-it-used-to-be + update_server_info() function. + (merge b3223761c8 jk/server-info-rabbit-hole later to maint). + + * The message given when "git commit -a <paths>" errors out has been + updated. + (merge 5a1dbd48bc nd/commit-a-with-paths-msg-update later to maint). + + * "git cherry-pick --options A..B", after giving control back to the + user to ask help resolving a conflicted step, did not honor the + options it originally received, which has been corrected. + + * Various glitches in "git gc" around reflog handling have been fixed. + + * The code to read from commit-graph file has been cleanup with more + careful error checking before using data read from it. + + * Performance fix around "git fetch" that grabs many refs. + (merge b764300912 jt/fetch-pack-wanted-refs-optim later to maint). + + * Protocol v2 support in "git fetch-pack" of shallow clones has been + corrected. + + * Performance fix around "git blame", especially in a linear history + (which is the norm we should optimize for). + (merge f892014943 dk/blame-keep-origin-blob later to maint). + + * Performance fix for "rev-list --parents -- pathspec". + (merge 8320b1dbe7 jk/revision-rewritten-parents-in-prio-queue later to maint). + + * Updating the display with progress message has been cleaned up to + deal better with overlong messages. + (merge 545dc345eb sg/overlong-progress-fix later to maint). + + * "git blame -- path" in a non-bare repository starts blaming from + the working tree, and the same command in a bare repository errors + out because there is no working tree by definition. The command + has been taught to instead start blaming from the commit at HEAD, + which is more useful. + (merge a544fb08f8 sg/blame-in-bare-start-at-head later to maint). + + * An underallocation in the code to read the untracked cache + extension has been corrected. + (merge 3a7b45a623 js/untracked-cache-allocfix later to maint). + + * The code is updated to check the result of memory allocation before + it is used in more places, by using xmalloc and/or xcalloc calls. + (merge 999b951b28 jk/xmalloc later to maint). + + * The GETTEXT_POISON test option has been quite broken ever since it + was made runtime-tunable, which has been fixed. + (merge f88b9cb603 jc/gettext-test-fix later to maint). + + * Test fix on APFS that is incapable of store paths in Latin-1. + (merge 3889149619 js/iso8895-test-on-apfs later to maint). + + * "git submodule foreach <command> --quiet" did not pass the option + down correctly, which has been corrected. + (merge a282f5a906 nd/submodule-foreach-quiet later to maint). + + * "git send-email" has been taught to use quoted-printable when the + payload contains carriage-return. The use of the mechanism is in + line with the design originally added the codepath that chooses QP + when the payload has overly long lines. + (merge 74d76a1701 bc/send-email-qp-cr later to maint). + + * The recently added feature to add addresses that are on + anything-by: trailers in 'git send-email' was found to be way too + eager and considered nonsense strings as if they can be legitimate + beginning of *-by: trailer. This has been tightened. + + * Builds with gettext broke on recent macOS w/ Homebrew, which + seems to have stopped including from /usr/local/include; this + has been corrected. + (merge 92a1377a2a js/macos-gettext-build later to maint). + + * Running "git add" on a repository created inside the current + repository is an explicit indication that the user wants to add it + as a submodule, but when the HEAD of the inner repository is on an + unborn branch, it cannot be added as a submodule. Worse, the files + in its working tree can be added as if they are a part of the outer + repository, which is not what the user wants. These problems are + being addressed. + (merge f937bc2f86 km/empty-repo-is-still-a-repo later to maint). + + * "git cherry-pick" run with the "-x" or the "--signoff" option used + to (and more importantly, ought to) clean up the commit log message + with the --cleanup=space option by default, but this has been + broken since late 2017. This has been fixed. + + * When given a tag that points at a commit-ish, "git replace --graft" + failed to peel the tag before writing a replace ref, which did not + make sense because the old graft mechanism the feature wants to + mimic only allowed to replace one commit object with another. + This has been fixed. + (merge ee521ec4cb cc/replace-graft-peel-tags later to maint). + + * Code tightening against a "wrong" object appearing where an object + of a different type is expected, instead of blindly assuming that + the connection between objects are correctly made. + (merge 97dd512af7 tb/unexpected later to maint). + + * An earlier update for MinGW and Cygwin accidentally broke MSVC build, + which has been fixed. + (merge 22c3634c0f ss/msvc-path-utils-fix later to maint). + + * %(push:track) token used in the --format option to "git + for-each-ref" and friends was not showing the right branch, which + has been fixed. + (merge c646d0934e dr/ref-filter-push-track-fix later to maint). + + * "make check-docs", "git help -a", etc. did not account for cases + where a particular build may deliberately omit some subcommands, + which has been corrected. + + * The logic to tell if a Git repository has a working tree protects + "git branch -D" from removing the branch that is currently checked + out by mistake. The implementation of this logic was broken for + repositories with unusual name, which unfortunately is the norm for + submodules these days. This has been fixed. + (merge f3534c98e4 jt/submodule-repo-is-with-worktree later to maint). + + * AIX shared the same build issues with other BSDs around fileno(fp), + which has been corrected. + (merge ee662bf5c6 cc/aix-has-fileno-as-a-macro later to maint). + + * The autoconf generated configure script failed to use the right + gettext() implementations from -libintl by ignoring useless stub + implementations shipped in some C library, which has been + corrected. + (merge b71e56a683 vk/autoconf-gettext later to maint). + + * Fix index-pack perf test so that the repeated invocations always + run in an empty repository, which emulates the initial clone + situation better. + (merge 775c71e16d jk/p5302-avoid-collision-check-cost later to maint). + + * A "ls-files" that emulates "find" to enumerate files in the working + tree resulted in duplicated Makefile rules that caused the build to + issue an unnecessary warning during a trial build after merge + conflicts are resolved in working tree *.h files but before the + resolved results are added to the index. This has been corrected. + + * "git cherry-pick" (and "revert" that shares the same runtime engine) + that deals with multiple commits got confused when the final step + gets stopped with a conflict and the user concluded the sequence + with "git commit". Attempt to fix it by cleaning up the state + files used by these commands in such a situation. + (merge 4a72486de9 pw/clean-sequencer-state-upon-final-commit later to maint). + + * On a filesystem like HFS+, the names of the refs stored as filesystem + entities may become different from what the end-user expects, just + like files in the working tree get "renamed". Work around the + mismatch by paying attention to the core.precomposeUnicode + configuration. + (merge 8e712ef6fc en/unicode-in-refnames later to maint). + + * The code to generate the multi-pack idx file was not prepared to + see too many packfiles and ran out of open file descriptor, which + has been corrected. + + * To run tests for Git SVN, our scripts for CI used to install the + git-svn package (in the hope that it would bring in the right + dependencies). This has been updated to install the more direct + dependency, namely, libsvn-perl. + (merge db864306cf sg/ci-libsvn-perl later to maint). + + * "git cvsexportcommit" running on msys did not expect cvsnt showed + "cvs status" output with CRLF line endings. + + * The fsmonitor interface got out of sync after the in-core index + file gets discarded, which has been corrected. + (merge 398a3b0899 js/fsmonitor-refresh-after-discarding-index later to maint). + + * "git status" did not know that the "label" instruction in the + todo-list "rebase -i -r" uses should not be shown as a hex object + name. + + * A prerequisite check in the test suite to see if a working jgit is + available was made more robust. + (merge abd0f28983 tz/test-lib-check-working-jgit later to maint). + + * The codepath to parse :<path> that obtains the object name for an + indexed object has been made more robust. + + * Code cleanup, docfix, build fix, etc. + (merge 11f470aee7 jc/test-yes-doc later to maint). + (merge 90503a240b js/doc-symref-in-proto-v1 later to maint). + (merge 5c326d1252 jk/unused-params later to maint). + (merge 68cabbfda3 dl/doc-submodule-wo-subcommand later to maint). + (merge 9903623761 ab/receive-pack-use-after-free-fix later to maint). + (merge 1ede45e44b en/merge-options-doc later to maint). + (merge 3e14dd2c8e rd/doc-hook-used-in-sample later to maint). + (merge c271dc28fd nd/no-more-check-racy later to maint). + (merge e6e15194a8 yb/utf-16le-bom-spellfix later to maint). + (merge bb101aaf0c rd/attr.c-comment-typofix later to maint). + (merge 716a5af812 rd/gc-prune-doc-fix later to maint). + (merge 50b206371d js/untravis-windows later to maint). + (merge dbf47215e3 js/rebase-recreate-merge later to maint). + (merge 56cb2d30f8 dl/reset-doc-no-wrt-abbrev later to maint). + (merge 64eca306a2 ja/dir-rename-doc-markup-fix later to maint). + (merge af91b0230c dl/ignore-docs later to maint). + (merge 59a06e947b ra/t3600-test-path-funcs later to maint). + (merge e041d0781b ar/t4150-remove-cruft later to maint). + (merge 8d75a1d183 ma/asciidoctor-fixes-more later to maint). + (merge 74cc547b0f mh/pack-protocol-doc-fix later to maint). + (merge ed31851fa6 ab/doc-misc-typofixes later to maint). + (merge a7256debd4 nd/checkout-m-doc-update later to maint). + (merge 3a9e1ad78d jt/t5551-protocol-v2-does-not-have-half-auth later to maint). + (merge 0b918b75af sg/t5318-cleanup later to maint). + (merge 68ed71b53c cb/doco-mono later to maint). + (merge a34dca2451 nd/interpret-trailers-docfix later to maint). + (merge cf7b857a77 en/fast-import-parsing-fix later to maint). + (merge fe61ccbc35 po/rerere-doc-fmt later to maint). + (merge ffea0248bf po/describe-not-necessarily-7 later to maint). + (merge 7cb7283adb tg/ls-files-debug-format-fix later to maint). + (merge f64a21bd82 tz/doc-apostrophe-no-longer-needed later to maint). + (merge dbe7b41019 js/t3301-unbreak-notes-test later to maint). + (merge d8083e4180 km/t3000-retitle later to maint). + (merge 9e4cbccbd7 tz/git-svn-doc-markup-fix later to maint). + (merge da9ca955a7 jk/ls-files-doc-markup-fix later to maint). + (merge 6804ba3a58 cw/diff-highlight later to maint). + (merge 1a8787144d nd/submodule-helper-incomplete-line-fix later to maint). + (merge d9ef573837 jk/apache-lsan later to maint). + (merge c871fbee2b js/t6500-use-windows-pid-on-mingw later to maint). + (merge ce4c7bfc90 bl/t4253-exit-code-from-format-patch later to maint). + (merge 397a46db78 js/t5580-unc-alternate-test later to maint). + (merge d4907720a2 cm/notes-comment-fix later to maint). + (merge 9dde06de13 cb/http-push-null-in-message-fix later to maint). + (merge 4c785c0edc js/rebase-config-bitfix later to maint). + (merge 8e9fe16c87 es/doc-gitsubmodules-markup later to maint). diff --git a/Documentation/RelNotes/2.22.1.txt b/Documentation/RelNotes/2.22.1.txt new file mode 100644 index 0000000000..432762f270 --- /dev/null +++ b/Documentation/RelNotes/2.22.1.txt @@ -0,0 +1,150 @@ +Git 2.22.1 Release Notes +======================== + +Fixes since v2.22 +----------------- + + * A relative pathname given to "git init --template=<path> <repo>" + ought to be relative to the directory "git init" gets invoked in, + but it instead was made relative to the repository, which has been + corrected. + + * "git worktree add" used to fail when another worktree connected to + the same repository was corrupt, which has been corrected. + + * The ownership rule for the file descriptor to fast-import remote + backend was mixed up, leading to unrelated file descriptor getting + closed, which has been fixed. + + * "git update-server-info" used to leave stale packfiles in its + output, which has been corrected. + + * The server side support for "git fetch" used to show incorrect + value for the HEAD symbolic ref when the namespace feature is in + use, which has been corrected. + + * "git am -i --resolved" segfaulted after trying to see a commit as + if it were a tree, which has been corrected. + + * "git bundle verify" needs to see if prerequisite objects exist in + the receiving repository, but the command did not check if we are + in a repository upfront, which has been corrected. + + * "git merge --squash" is designed to update the working tree and the + index without creating the commit, and this cannot be countermanded + by adding the "--commit" option; the command now refuses to work + when both options are given. + + * The data collected by fsmonitor was not properly written back to + the on-disk index file, breaking t7519 tests occasionally, which + has been corrected. + + * Update to Unicode 12.1 width table. + + * The command line to invoke a "git cat-file" command from inside + "git p4" was not properly quoted to protect a caret and running a + broken command on Windows, which has been corrected. + + * "git request-pull" learned to warn when the ref we ask them to pull + from in the local repository and in the published repository are + different. + + * When creating a partial clone, the object filtering criteria is + recorded for the origin of the clone, but this incorrectly used a + hardcoded name "origin" to name that remote; it has been corrected + to honor the "--origin <name>" option. + + * "git fetch" into a lazy clone forgot to fetch base objects that are + necessary to complete delta in a thin packfile, which has been + corrected. + + * The filter_data used in the list-objects-filter (which manages a + lazily sparse clone repository) did not use the dynamic array API + correctly---'nr' is supposed to point at one past the last element + of the array in use. This has been corrected. + + * The description about slashes in gitignore patterns (used to + indicate things like "anchored to this level only" and "only + matches directories") has been revamped. + + * The URL decoding code has been updated to avoid going past the end + of the string while parsing %-<hex>-<hex> sequence. + + * The list of for-each like macros used by clang-format has been + updated. + + * "git push --atomic" that goes over the transport-helper (namely, + the smart http transport) failed to prevent refs to be pushed when + it can locally tell that one of the ref update will fail without + having to consult the other end, which has been corrected. + + * "git clean" silently skipped a path when it cannot lstat() it; now + it gives a warning. + + * A codepath that reads from GPG for signed object verification read + past the end of allocated buffer, which has been fixed. + + * "git rm" to resolve a conflicted path leaked an internal message + "needs merge" before actually removing the path, which was + confusing. This has been corrected. + + * The "git clone" documentation refers to command line options in its + description in the short form; they have been replaced with long + forms to make them more recognisable. + + * The configuration variable rebase.rescheduleFailedExec should be + effective only while running an interactive rebase and should not + affect anything when running a non-interactive one, which was not + the case. This has been corrected. + + * "git submodule foreach" did not protect command line options passed + to the command to be run in each submodule correctly, when the + "--recursive" option was in use. + + * Use "Erase in Line" CSI sequence that is already used in the editor + support to clear cruft in the progress output. + + * The codepath to compute delta islands used to spew progress output + without giving the callers any way to squelch it, which has been + fixed. + + * The code to parse scaled numbers out of configuration files has + been made more robust and also easier to follow. + + * An incorrect list of options was cached after command line + completion failed (e.g. trying to complete a command that requires + a repository outside one), which has been corrected. + + * "git rebase --abort" used to leave refs/rewritten/ when concluding + "git rebase -r", which has been corrected. + + * "git stash show 23" used to work, but no more after getting + rewritten in C; this regression has been corrected. + + * "git interpret-trailers" always treated '#' as the comment + character, regardless of core.commentChar setting, which has been + corrected. + + * Code clean-up to avoid signed integer overlaps during binary search. + + * "git checkout -p" needs to selectively apply a patch in reverse, + which did not work well. + + * The commit-graph file is now part of the "files that the runtime + may keep open file descriptors on, all of which would need to be + closed when done with the object store", and the file descriptor to + an existing commit-graph file now is closed before "gc" finalizes a + new instance to replace it. + + * Code restructuring during 2.20 period broke fetching tags via + "import" based transports. + + * We have been trying out a few language features outside c89; the + coding guidelines document did not talk about them and instead had + a blanket ban against them. + + * The internal diff machinery can be made to read out of bounds while + looking for --funcion-context line in a corner case, which has been + corrected. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.22.2.txt b/Documentation/RelNotes/2.22.2.txt new file mode 100644 index 0000000000..940a23f0d9 --- /dev/null +++ b/Documentation/RelNotes/2.22.2.txt @@ -0,0 +1,8 @@ +Git v2.22.2 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4, +v2.17.3, v2.20.2 and in v2.21.1, addressing the security issues +CVE-2019-1348, CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, +CVE-2019-1352, CVE-2019-1353, CVE-2019-1354, CVE-2019-1387, and +CVE-2019-19604; see the release notes for those versions for details. diff --git a/Documentation/RelNotes/2.22.3.txt b/Documentation/RelNotes/2.22.3.txt new file mode 100644 index 0000000000..57296f6d17 --- /dev/null +++ b/Documentation/RelNotes/2.22.3.txt @@ -0,0 +1,5 @@ +Git v2.22.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.22.4.txt b/Documentation/RelNotes/2.22.4.txt new file mode 100644 index 0000000000..8b5f3e3f37 --- /dev/null +++ b/Documentation/RelNotes/2.22.4.txt @@ -0,0 +1,5 @@ +Git v2.22.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.23.0.txt b/Documentation/RelNotes/2.23.0.txt new file mode 100644 index 0000000000..e3c4e78265 --- /dev/null +++ b/Documentation/RelNotes/2.23.0.txt @@ -0,0 +1,348 @@ +Git 2.23 Release Notes +====================== + +Updates since v2.22 +------------------- + +Backward compatibility note + + * The "--base" option of "format-patch" computed the patch-ids for + prerequisite patches in an unstable way, which has been updated to + compute in a way that is compatible with "git patch-id --stable". + + * The "git log" command by default behaves as if the --mailmap option + was given. + + +UI, Workflows & Features + + * The "git fast-export/import" pair has been taught to handle commits + with log messages in encoding other than UTF-8 better. + + * In recent versions of Git, per-worktree refs are exposed in + refs/worktrees/<wtname>/ hierarchy, which means that worktree names + must be a valid refname component. The code now sanitizes the names + given to worktrees, to make sure these refs are well-formed. + + * "git merge" learned "--quit" option that cleans up the in-progress + merge while leaving the working tree and the index still in a mess. + + * "git format-patch" learns a configuration to set the default for + its --notes=<ref> option. + + * The code to show args with potential typo that cannot be + interpreted as a commit-ish has been improved. + + * "git clone --recurse-submodules" learned to set up the submodules + to ignore commit object names recorded in the superproject gitlink + and instead use the commits that happen to be at the tip of the + remote-tracking branches from the get-go, by passing the new + "--remote-submodules" option. + + * The pattern "git diff/grep" use to extract funcname and words + boundary for Matlab has been extend to cover Octave, which is more + or less equivalent. + + * "git help git" was hard to discover (well, at least for some + people). + + * The pattern "git diff/grep" use to extract funcname and words + boundary for Rust has been added. + + * "git status" can be told a non-standard default value for the + "--[no-]ahead-behind" option with a new configuration variable + status.aheadBehind. + + * "git fetch" and "git pull" reports when a fetch results in + non-fast-forward updates to let the user notice unusual situation. + The commands learned "--no-show-forced-updates" option to disable + this safety feature. + + * Two new commands "git switch" and "git restore" are introduced to + split "checking out a branch to work on advancing its history" and + "checking out paths out of the index and/or a tree-ish to work on + advancing the current history" out of the single "git checkout" + command. + + * "git branch --list" learned to always output the detached HEAD as + the first item (when the HEAD is detached, of course), regardless + of the locale. + + * The conditional inclusion mechanism learned to base the choice on + the branch the HEAD currently is on. + + * "git rev-list --objects" learned the "--no-object-names" option to + squelch the path to the object that is used as a grouping hint for + pack-objects. + + * A new tag.gpgSign configuration variable turns "git tag -a" into + "git tag -s". + + * "git multi-pack-index" learned expire and repack subcommands. + + * "git blame" learned to "ignore" commits in the history, whose + effects (as well as their presence) get ignored. + + * "git cherry-pick/revert" learned a new "--skip" action. + + * The tips of refs from the alternate object store can be used as + starting point for reachability computation now. + + * Extra blank lines in "git status" output have been reduced. + + * The commits in a repository can be described by multiple + commit-graph files now, which allows the commit-graph files to be + updated incrementally. + + * "git range-diff" output has been tweaked for easier identification + of which part of what file the patch shown is about. + + +Performance, Internal Implementation, Development Support etc. + + * Update supporting parts of "git rebase" to remove code that should + no longer be used. + + * Developer support to emulate unsatisfied prerequisites in tests to + ensure that the remainder of the tests still succeeds when tests + with prerequisites are skipped. + + * "git update-server-info" learned not to rewrite the file with the + same contents. + + * The way of specifying the path to find dynamic libraries at runtime + has been simplified. The old default to pass -R/path/to/dir has been + replaced with the new default to pass -Wl,-rpath,/path/to/dir, + which is the more recent GCC uses. Those who need to build with an + old GCC can still use "CC_LD_DYNPATH=-R" + + * Prepare use of reachability index in topological walker that works + on a range (A..B). + + * A new tutorial targeting specifically aspiring git-core + developers has been added. + + * Auto-detect how to tell HP-UX aCC where to use dynamically linked + libraries from at runtime. + + * "git mergetool" and its tests now spawn fewer subprocesses. + + * Dev support update to help tracing out tests. + + * Support to build with MSVC has been updated. + + * "git fetch" that grabs from a group of remotes learned to run the + auto-gc only once at the very end. + + * A handful of Windows build patches have been upstreamed. + + * The code to read state files used by the sequencer machinery for + "git status" has been made more robust against a corrupt or stale + state files. + + * "git for-each-ref" with multiple patterns have been optimized. + + * The tree-walk API learned to pass an in-core repository + instance throughout more codepaths. + + * When one step in multi step cherry-pick or revert is reset or + committed, the command line prompt script failed to notice the + current status, which has been improved. + + * Many GIT_TEST_* environment variables control various aspects of + how our tests are run, but a few followed "non-empty is true, empty + or unset is false" while others followed the usual "there are a few + ways to spell true, like yes, on, etc., and also ways to spell + false, like no, off, etc." convention. + + * Adjust the dir-iterator API and apply it to the local clone + optimization codepath. + + * We have been trying out a few language features outside c89; the + coding guidelines document did not talk about them and instead had + a blanket ban against them. + + * A test helper has been introduced to optimize preparation of test + repositories with many simple commits, and a handful of test + scripts have been updated to use it. + + +Fixes since v2.22 +----------------- + + * A relative pathname given to "git init --template=<path> <repo>" + ought to be relative to the directory "git init" gets invoked in, + but it instead was made relative to the repository, which has been + corrected. + + * "git worktree add" used to fail when another worktree connected to + the same repository was corrupt, which has been corrected. + + * The ownership rule for the file descriptor to fast-import remote + backend was mixed up, leading to an unrelated file descriptor getting + closed, which has been fixed. + + * A "merge -c" instruction during "git rebase --rebase-merges" should + give the user a chance to edit the log message, even when there is + otherwise no need to create a new merge and replace the existing + one (i.e. fast-forward instead), but did not. Which has been + corrected. + + * Code cleanup and futureproof. + + * More parameter validation. + + * "git update-server-info" used to leave stale packfiles in its + output, which has been corrected. + + * The server side support for "git fetch" used to show incorrect + value for the HEAD symbolic ref when the namespace feature is in + use, which has been corrected. + + * "git am -i --resolved" segfaulted after trying to see a commit as + if it were a tree, which has been corrected. + + * "git bundle verify" needs to see if prerequisite objects exist in + the receiving repository, but the command did not check if we are + in a repository upfront, which has been corrected. + + * "git merge --squash" is designed to update the working tree and the + index without creating the commit, and this cannot be countermanded + by adding the "--commit" option; the command now refuses to work + when both options are given. + + * The data collected by fsmonitor was not properly written back to + the on-disk index file, breaking t7519 tests occasionally, which + has been corrected. + + * Update to Unicode 12.1 width table. + + * The command line to invoke a "git cat-file" command from inside + "git p4" was not properly quoted to protect a caret and running a + broken command on Windows, which has been corrected. + + * "git request-pull" learned to warn when the ref we ask them to pull + from in the local repository and in the published repository are + different. + + * When creating a partial clone, the object filtering criteria is + recorded for the origin of the clone, but this incorrectly used a + hardcoded name "origin" to name that remote; it has been corrected + to honor the "--origin <name>" option. + + * "git fetch" into a lazy clone forgot to fetch base objects that are + necessary to complete delta in a thin packfile, which has been + corrected. + + * The filter_data used in the list-objects-filter (which manages a + lazily sparse clone repository) did not use the dynamic array API + correctly---'nr' is supposed to point at one past the last element + of the array in use. This has been corrected. + + * The description about slashes in gitignore patterns (used to + indicate things like "anchored to this level only" and "only + matches directories") has been revamped. + + * The URL decoding code has been updated to avoid going past the end + of the string while parsing %-<hex>-<hex> sequence. + + * The list of for-each like macros used by clang-format has been + updated. + + * "git branch --list" learned to show branches that are checked out + in other worktrees connected to the same repository prefixed with + '+', similar to the way the currently checked out branch is shown + with '*' in front. + (merge 6e9381469e nb/branch-show-other-worktrees-head later to maint). + + * Code restructuring during 2.20 period broke fetching tags via + "import" based transports. + + * The commit-graph file is now part of the "files that the runtime + may keep open file descriptors on, all of which would need to be + closed when done with the object store", and the file descriptor to + an existing commit-graph file now is closed before "gc" finalizes a + new instance to replace it. + + * "git checkout -p" needs to selectively apply a patch in reverse, + which did not work well. + + * Code clean-up to avoid signed integer wraparounds during binary search. + + * "git interpret-trailers" always treated '#' as the comment + character, regardless of core.commentChar setting, which has been + corrected. + + * "git stash show 23" used to work, but no more after getting + rewritten in C; this regression has been corrected. + + * "git rebase --abort" used to leave refs/rewritten/ when concluding + "git rebase -r", which has been corrected. + + * An incorrect list of options was cached after command line + completion failed (e.g. trying to complete a command that requires + a repository outside one), which has been corrected. + + * The code to parse scaled numbers out of configuration files has + been made more robust and also easier to follow. + + * The codepath to compute delta islands used to spew progress output + without giving the callers any way to squelch it, which has been + fixed. + + * Protocol capabilities that go over wire should never be translated, + but it was incorrectly marked for translation, which has been + corrected. The output of protocol capabilities for debugging has + been tweaked a bit. + + * Use "Erase in Line" CSI sequence that is already used in the editor + support to clear cruft in the progress output. + + * "git submodule foreach" did not protect command line options passed + to the command to be run in each submodule correctly, when the + "--recursive" option was in use. + + * The configuration variable rebase.rescheduleFailedExec should be + effective only while running an interactive rebase and should not + affect anything when running a non-interactive one, which was not + the case. This has been corrected. + + * The "git clone" documentation refers to command line options in its + description in the short form; they have been replaced with long + forms to make them more recognisable. + + * Generation of pack bitmaps are now disabled when .keep files exist, + as these are mutually exclusive features. + (merge 7328482253 ew/repack-with-bitmaps-by-default later to maint). + + * "git rm" to resolve a conflicted path leaked an internal message + "needs merge" before actually removing the path, which was + confusing. This has been corrected. + + * "git stash --keep-index" did not work correctly on paths that have + been removed, which has been fixed. + (merge b932f6a5e8 tg/stash-keep-index-with-removed-paths later to maint). + + * Window 7 update ;-) + + * A codepath that reads from GPG for signed object verification read + past the end of allocated buffer, which has been fixed. + + * "git clean" silently skipped a path when it cannot lstat() it; now + it gives a warning. + + * "git push --atomic" that goes over the transport-helper (namely, + the smart http transport) failed to prevent refs to be pushed when + it can locally tell that one of the ref update will fail without + having to consult the other end, which has been corrected. + + * The internal diff machinery can be made to read out of bounds while + looking for --function-context line in a corner case, which has been + corrected. + (merge b777f3fd61 jk/xdiff-clamp-funcname-context-index later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge fbec05c210 cc/test-oidmap later to maint). + (merge 7a06fb038c jk/no-system-includes-in-dot-c later to maint). + (merge 81ed2b405c cb/xdiff-no-system-includes-in-dot-c later to maint). + (merge d61e6ce1dd sg/fsck-config-in-doc later to maint). diff --git a/Documentation/RelNotes/2.23.1.txt b/Documentation/RelNotes/2.23.1.txt new file mode 100644 index 0000000000..2083b492ce --- /dev/null +++ b/Documentation/RelNotes/2.23.1.txt @@ -0,0 +1,8 @@ +Git v2.23.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4, +v2.17.3, v2.20.2 and in v2.21.1, addressing the security issues +CVE-2019-1348, CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, +CVE-2019-1352, CVE-2019-1353, CVE-2019-1354, CVE-2019-1387, and +CVE-2019-19604; see the release notes for those versions for details. diff --git a/Documentation/RelNotes/2.23.2.txt b/Documentation/RelNotes/2.23.2.txt new file mode 100644 index 0000000000..b697cbe0e3 --- /dev/null +++ b/Documentation/RelNotes/2.23.2.txt @@ -0,0 +1,5 @@ +Git v2.23.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.23.3.txt b/Documentation/RelNotes/2.23.3.txt new file mode 100644 index 0000000000..2e35490137 --- /dev/null +++ b/Documentation/RelNotes/2.23.3.txt @@ -0,0 +1,5 @@ +Git v2.23.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.24.0.txt b/Documentation/RelNotes/2.24.0.txt new file mode 100644 index 0000000000..bde154124c --- /dev/null +++ b/Documentation/RelNotes/2.24.0.txt @@ -0,0 +1,398 @@ +Git 2.24 Release Notes +====================== + +Updates since v2.23 +------------------- + +Backward compatibility note + + * "filter-branch" is showing its age and alternatives are available. + From this release, we started to discourage its use and hint + people about filter-repo. + +UI, Workflows & Features + + * We now have an active interim maintainer for the Git-Gui part of + the system. Praise and thank Pratyush Yadav for volunteering. + + * The command line parser learned "--end-of-options" notation; the + standard convention for scripters to have hardcoded set of options + first on the command line, and force the command to treat end-user + input as non-options, has been to use "--" as the delimiter, but + that would not work for commands that use "--" as a delimiter + between revs and pathspec. + + * A mechanism to affect the default setting for a (related) group of + configuration variables is introduced. + + * "git fetch" learned "--set-upstream" option to help those who first + clone from their private fork they intend to push to, add the true + upstream via "git remote add" and then "git fetch" from it. + + * Device-tree files learned their own userdiff patterns. + (merge 3c81760bc6 sb/userdiff-dts later to maint). + + * "git rebase --rebase-merges" learned to drive different merge + strategies and pass strategy specific options to them. + + * A new "pre-merge-commit" hook has been introduced. + + * Command line completion updates for "git -c var.name=val" have been + added. + + * The lazy clone machinery has been taught that there can be more + than one promisor remote and consult them in order when downloading + missing objects on demand. + + * The list-objects-filter API (used to create a sparse/lazy clone) + learned to take a combined filter specification. + + * The documentation and tests for "git format-patch" have been + cleaned up. + + * On Windows, the root level of UNC share is now allowed to be used + just like any other directory. + + * The command line completion support (in contrib/) learned about the + "--skip" option of "git revert" and "git cherry-pick". + + * "git rebase --keep-base <upstream>" tries to find the original base + of the topic being rebased and rebase on top of that same base, + which is useful when running the "git rebase -i" (and its limited + variant "git rebase -x"). + + The command also has learned to fast-forward in more cases where it + can instead of replaying to recreate identical commits. + + * A configuration variable tells "git fetch" to write the commit + graph after finishing. + + * "git add -i" has been taught to show the total number of hunks and + the hunks that has been processed so far when showing prompts. + + * "git fetch --jobs=<n>" allowed <n> parallel jobs when fetching + submodules, but this did not apply to "git fetch --multiple" that + fetches from multiple remote repositories. It now does. + + * The installation instruction for zsh completion script (in + contrib/) has been a bit improved. + + +Performance, Internal Implementation, Development Support etc. + + * The code to write commit-graph over given commit object names has + been made a bit more robust. + + * The first line of verbose output from each test piece now carries + the test name and number to help scanning with eyeballs. + + * Further clean-up of the initialization code. + + * xmalloc() used to have a mechanism to ditch memory and address + space resources as the last resort upon seeing an allocation + failure from the underlying malloc(), which made the code complex + and thread-unsafe with dubious benefit, as major memory resource + users already do limit their uses with various other mechanisms. + It has been simplified away. + + * Unnecessary full-tree diff in "git log -L" machinery has been + optimized away. + + * The http transport lacked some optimization the native transports + learned to avoid unnecessary ref advertisement, which has been + corrected. + + * Preparation for SHA-256 upgrade continues in the test department. + (merge 0c37c41d13 bc/hash-independent-tests-part-5 later to maint). + + * The memory ownership model of the "git fast-import" got + straightened out. + + * Output from trace2 subsystem is formatted more prettily now. + + * The internal code originally invented for ".gitignore" processing + got reshuffled and renamed to make it less tied to "excluding" and + stress more that it is about "matching", as it has been reused for + things like sparse checkout specification that want to check if a + path is "included". + + * "git stash" learned to write refreshed index back to disk. + + * Coccinelle checks are done on more source files than before now. + + * The cache-tree code has been taught to be less aggressive in + attempting to see if a tree object it computed already exists in + the repository. + + * The code to parse and use the commit-graph file has been made more + robust against corrupted input. + + * The hg-to-git script (in contrib/) has been updated to work with + Python 3. + + * Update the way build artifacts in t/helper/ directory are ignored. + + * Preparation for SHA-256 upgrade continues. + + * "git log --graph" for an octopus merge is sometimes colored + incorrectly, which is demonstrated and documented but not yet + fixed. + + * The trace2 output, when sending them to files in a designated + directory, can populate the directory with too many files; a + mechanism is introduced to set the maximum number of files and + discard further logs when the maximum is reached. + + * We have adopted a Code-of-conduct document. + (merge 3f9ef874a7 jk/coc later to maint). + + +Fixes since v2.23 +----------------- + + * "git grep --recurse-submodules" that looks at the working tree + files looked at the contents in the index in submodules, instead of + files in the working tree. + (merge 6a289d45c0 mt/grep-submodules-working-tree later to maint). + + * Codepaths to walk tree objects have been audited for integer + overflows and hardened. + (merge 5aa02f9868 jk/tree-walk-overflow later to maint). + + * "git pack-refs" can lose refs that are created while running, which + is getting corrected. + (merge a613d4f817 sc/pack-refs-deletion-racefix later to maint). + + * "git checkout" and "git restore" to re-populate the index from a + tree-ish (typically HEAD) did not work correctly for a path that + was removed and then added again with the intent-to-add bit, when + the corresponding working tree file was empty. This has been + corrected. + + * Compilation fix. + (merge 70597e8386 rs/nedalloc-fixlets later to maint). + + * "git gui" learned to call the clean-up procedure before exiting. + (merge 0d88f3d2c5 py/git-gui-do-quit later to maint). + + * We promoted the "indent heuristics" that decides where to split + diff hunks from experimental to the default a few years ago, but + some stale documentation still marked it as experimental, which has + been corrected. + (merge 64e5e1fba1 sg/diff-indent-heuristic-non-experimental later to maint). + + * Fix a mismerge that happened in 2.22 timeframe. + (merge acb7da05ac en/checkout-mismerge-fix later to maint). + + * "git archive" recorded incorrect length in extended pax header in + some corner cases, which has been corrected. + (merge 71d41ff651 rs/pax-extended-header-length-fix later to maint). + + * On-demand object fetching in lazy clone incorrectly tried to fetch + commits from submodule projects, while still working in the + superproject, which has been corrected. + (merge a63694f523 jt/diff-lazy-fetch-submodule-fix later to maint). + + * Prepare get_short_oid() codepath to be thread-safe. + (merge 7cfcb16b0e rs/sort-oid-array-thread-safe later to maint). + + * "for-each-ref" and friends that show refs did not protect themselves + against ancient tags that did not record tagger names when asked to + show "%(taggername)", which have been corrected. + (merge 8b3f33ef11 mp/for-each-ref-missing-name-or-email later to maint). + + * The "git am" based backend of "git rebase" ignored the result of + updating ".gitattributes" done in one step when replaying + subsequent steps. + (merge 2c65d90f75 bc/reread-attributes-during-rebase later to maint). + + * Tell cURL library to use the same malloc() implementation, with the + xmalloc() wrapper, as the rest of the system, for consistency. + (merge 93b980e58f cb/curl-use-xmalloc later to maint). + + * Build fix to adjust .gitignore to unignore a path that we started to track. + (merge aac6ff7b5b js/visual-studio later to maint). + + * A few implementation fixes in the notes API. + (merge 60fe477a0b mh/notes-duplicate-entries later to maint). + + * Fix an earlier regression to "git push --all" which should have + been forbidden when the target remote repository is set to be a + mirror. + (merge 8e4c8af058 tg/push-all-in-mirror-forbidden later to maint). + + * Fix an earlier regression in the test suite, which mistakenly + stopped running HTTPD tests. + (merge 3960290675 sg/git-test-boolean later to maint). + + * "git rebase --autostash <upstream> <branch>", when <branch> is + different from the current branch, incorrectly moved the tip of the + current branch, which has been corrected. + (merge bf1e28e0ad bw/rebase-autostash-keep-current-branch later to maint). + + * Update support for Asciidoctor documentation toolchain. + (merge 83b0b8953e ma/asciidoctor-refmiscinfo later to maint). + + * Start using DocBook 5 (instead of DocBook 4.5) as Asciidoctor 2.0 + no longer works with the older one. + (merge f6461b82b9 bc/doc-use-docbook-5 later to maint). + + * The markup used in user-manual has been updated to work better with + asciidoctor. + (merge c4d2f6143a ma/user-manual-markup-update later to maint). + + * Make sure the grep machinery does not abort when seeing a payload + that is not UTF-8 even when JIT is not in use with PCRE1. + (merge ad7c543e3b cb/skip-utf8-check-with-pcre1 later to maint). + + * The name of the blob object that stores the filter specification + for sparse cloning/fetching was interpreted in a wrong place in the + code, causing Git to abort. + + * "git log --decorate-refs-exclude=<pattern>" was incorrectly + overruled when the "--simplify-by-decoration" option is used, which + has been corrected. + (merge 0cc7380d88 rs/simplify-by-deco-with-deco-refs-exclude later to maint). + + * The "upload-pack" (the counterpart of "git fetch") needs to disable + commit-graph when responding to a shallow clone/fetch request, but + the way this was done made Git panic, which has been corrected. + + * The object traversal machinery has been optimized not to load tree + objects when we are only interested in commit history. + (merge 72ed80c784 jk/list-objects-optim-wo-trees later to maint). + + * The object name parser for "Nth parent" syntax has been made more + robust against integer overflows. + (merge 59fa5f5a25 rs/nth-parent-parse later to maint). + + * The code used in following tags in "git fetch" has been optimized. + (merge b7e2d8bca5 ms/fetch-follow-tag-optim later to maint). + + * Regression fix for progress output. + (merge 2bb74b53a4 sg/progress-fix later to maint). + + * A bug in merge-recursive code that triggers when a branch with a + symbolic link is merged with a branch that replaces it with a + directory has been fixed. + (merge 83e3ad3b12 jt/merge-recursive-symlink-is-not-a-dir-in-way later to maint). + + * The rename detection logic sorts a list of rename source candidates + by similarity to pick the best candidate, which means that a tie + between sources with the same similarity is broken by the original + location in the original candidate list (which is sorted by path). + Force the sorting by similarity done with a stable sort, which is + not promised by system supplied qsort(3), to ensure consistent + results across platforms. + (merge 2049b8dc65 js/diff-rename-force-stable-sort later to maint). + + * The code to skip "UTF" and "UTF-" prefix, when computing an advice + message, did not work correctly when the prefix was "UTF", which + has been fixed. + (merge b181676ce9 rs/convert-fix-utf-without-dash later to maint). + + * The author names taken from SVN repositories may have extra leading + or trailing whitespaces, which are now munged away. + (merge 4ddd4bddb1 tk/git-svn-trim-author-name later to maint). + + * "git rebase -i" showed a wrong HEAD while "reword" open the editor. + (merge b0a3186140 pw/rebase-i-show-HEAD-to-reword later to maint). + + * A few simplification and bugfixes to PCRE interface. + (merge c581e4a749 ab/pcre-jit-fixes later to maint). + + * PCRE fixes. + (merge ff61681b46 cb/pcre1-cleanup later to maint). + + * "git range-diff" segfaulted when diff.noprefix configuration was + used, as it blindly expected the patch it internally generates to + have the standard a/ and b/ prefixes. The command now forces the + internal patch to be built without any prefix, not to be affected + by any end-user configuration. + (merge 937b76ed49 js/range-diff-noprefix later to maint). + + * "git stash apply" in a subdirectory of a secondary worktree failed + to access the worktree correctly, which has been corrected. + (merge dfd557c978 js/stash-apply-in-secondary-worktree later to maint). + + * The merge-recursive machinery is one of the most complex parts of + the system that accumulated cruft over time. This large series + cleans up the implementation quite a bit. + (merge b657047719 en/merge-recursive-cleanup later to maint). + + * Pretty-printed command line formatter (used in e.g. reporting the + command being run by the tracing API) had a bug that lost an + argument that is an empty string, which has been corrected. + (merge ce2d7ed2fd gs/sq-quote-buf-pretty later to maint). + + * "git range-diff" failed to handle mode-only change, which has been + corrected. + (merge 2b6a9b13ca tg/range-diff-output-update later to maint). + + * Dev support update. + (merge 4f3c1dc5d6 dl/allow-running-cocci-verbosely later to maint). + + * "git format-patch -o <outdir>" did an equivalent of "mkdir <outdir>" + not "mkdir -p <outdir>", which was corrected. + + * "git stash save" lost local changes to submodules, which has been + corrected. + (merge 556895d0c8 jj/stash-reset-only-toplevel later to maint). + + * The atomic push over smart HTTP transport did not work, which has + been corrected. + (merge 6f1194246a bc/smart-http-atomic-push later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge d1387d3895 en/fast-import-merge-doc later to maint). + (merge 1c24a54ea4 bm/repository-layout-typofix later to maint). + (merge 415b770b88 ds/midx-expire-repack later to maint). + (merge 19800bdc3f nd/diff-parseopt later to maint). + (merge 58166c2e9d tg/t0021-racefix later to maint). + (merge 7027f508c7 dl/compat-cleanup later to maint). + (merge e770fbfeff jc/test-cleanup later to maint). + (merge 1fd881d404 rs/trace2-dst-warning later to maint). + (merge 7e92756751 mh/http-urlmatch-cleanup later to maint). + (merge 9784f97321 mh/release-commit-memory-fix later to maint). + (merge 60d198d022 tb/banned-vsprintf-namefix later to maint). + (merge 80e3658647 rs/help-unknown-ref-does-not-return later to maint). + (merge 0a8bc7068f dt/remote-helper-doc-re-lock-option later to maint). + (merge 27fd1e4ea7 en/merge-options-ff-and-friends later to maint). + (merge 502c386ff9 sg/clean-nested-repo-with-ignored later to maint). + (merge 26e3d1cbea am/mailmap-andrey-mazo later to maint). + (merge 47b27c96fa ss/get-time-cleanup later to maint). + (merge dd2e50a84e jk/commit-graph-cleanup later to maint). + (merge 4fd39c76e6 cs/pretty-formats-doc-typofix later to maint). + (merge 40e747e89d dl/submodule-set-branch later to maint). + (merge 689a146c91 rs/commit-graph-use-list-count later to maint). + (merge 0eb7c37a8a js/doc-patch-text later to maint). + (merge 4b3aa170d1 rs/nth-switch-code-simplification later to maint). + (merge 0d4304c124 ah/doc-submodule-ignore-submodules later to maint). + (merge af78249463 cc/svn-fe-py-shebang later to maint). + (merge 7bd97d6dff rs/alias-use-copy-array later to maint). + (merge c46ebc2496 sg/travis-help-debug later to maint). + (merge 24c681794f ps/my-first-contribution-alphasort later to maint). + (merge 75b2c15435 cb/do-not-use-test-cmp-with-a later to maint). + (merge cda0d497e3 bw/submodule-helper-usage-fix later to maint). + (merge fe0ed5d5e9 am/visual-studio-config-fix later to maint). + (merge 2e09c01232 sg/name-rev-cutoff-underflow-fix later to maint). + (merge ddb3c856f3 as/shallow-slab-use-fix later to maint). + (merge 71f4960b91 js/mingw-spawn-with-spaces-in-path later to maint). + (merge 53d687bf5f ah/cleanups later to maint). + (merge f537485fa5 rs/test-remove-useless-debugging-cat later to maint). + (merge 11a3d3aadd dl/rev-list-doc-cleanup later to maint). + (merge d928a8388a am/t0028-utf16-tests later to maint). + (merge b05b40930e dl/t0000-skip-test-test later to maint). + (merge 03d3b1297c js/xdiffi-comment-updates later to maint). + (merge 57d8f4b4c7 js/doc-stash-save later to maint). + (merge 8c1cfd58e3 ta/t1308-typofix later to maint). + (merge fa364ad790 bb/utf8-wcwidth-cleanup later to maint). + (merge 68b69211b2 bb/compat-util-comment-fix later to maint). + (merge 5cc6a4be11 rs/http-push-simplify later to maint). + (merge a81e42d235 rs/column-use-utf8-strnwidth later to maint). + (merge 062a309d36 rs/remote-curl-use-argv-array later to maint). + (merge 3b3c79f6c9 nr/diff-highlight-indent-fix later to maint). + (merge 3444ec2eb2 wb/fsmonitor-bitmap-fix later to maint). + (merge 10da030ab7 cb/pcre2-chartables-leakfix later to maint). + (merge 60e6569a12 js/mingw-needs-hiding-fix later to maint). + (merge 52bd3e4657 rl/gitweb-blame-prev-fix later to maint). diff --git a/Documentation/RelNotes/2.24.1.txt b/Documentation/RelNotes/2.24.1.txt new file mode 100644 index 0000000000..18104850fe --- /dev/null +++ b/Documentation/RelNotes/2.24.1.txt @@ -0,0 +1,8 @@ +Git v2.24.1 Release Notes +========================= + +This release merges up the fixes that appear in v2.14.6, v2.15.4, +v2.17.3, v2.20.2 and in v2.21.1, addressing the security issues +CVE-2019-1348, CVE-2019-1349, CVE-2019-1350, CVE-2019-1351, +CVE-2019-1352, CVE-2019-1353, CVE-2019-1354, CVE-2019-1387, and +CVE-2019-19604; see the release notes for those versions for details. diff --git a/Documentation/RelNotes/2.24.2.txt b/Documentation/RelNotes/2.24.2.txt new file mode 100644 index 0000000000..0049f65503 --- /dev/null +++ b/Documentation/RelNotes/2.24.2.txt @@ -0,0 +1,5 @@ +Git v2.24.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.24.3.txt b/Documentation/RelNotes/2.24.3.txt new file mode 100644 index 0000000000..5302e0f73b --- /dev/null +++ b/Documentation/RelNotes/2.24.3.txt @@ -0,0 +1,5 @@ +Git v2.24.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.25.0.txt b/Documentation/RelNotes/2.25.0.txt new file mode 100644 index 0000000000..91ceb34927 --- /dev/null +++ b/Documentation/RelNotes/2.25.0.txt @@ -0,0 +1,370 @@ +Git 2.25 Release Notes +====================== + +Updates since v2.24 +------------------- + +Backward compatibility notes + + +UI, Workflows & Features + + * A tutorial on object enumeration has been added. + + * The branch description ("git branch --edit-description") has been + used to fill the body of the cover letters by the format-patch + command; this has been enhanced so that the subject can also be + filled. + + * "git rebase --preserve-merges" has been marked as deprecated; this + release stops advertising it in the "git rebase -h" output. + + * The code to generate multi-pack index learned to show (or not to + show) progress indicators. + + * "git apply --3way" learned to honor merge.conflictStyle + configuration variable, like merges would. + + * The custom format for "git log --format=<format>" learned the l/L + placeholder that is similar to e/E that fills in the e-mail + address, but only the local part on the left side of '@'. + + * Documentation pages for "git shortlog" now list commit limiting + options explicitly. + + * The patterns to detect function boundary for Elixir language has + been added. + + * The completion script (in contrib/) learned that the "--onto" + option of "git rebase" can take its argument as the value of the + option. + + * The userdiff machinery has been taught that "async def" is another + way to begin a "function" in Python. + + * "git range-diff" learned to take the "--notes=<ref>" and the + "--no-notes" options to control the commit notes included in the + log message that gets compared. + + * "git rev-parse --show-toplevel" run outside of any working tree did + not error out, which has been corrected. + + * A few commands learned to take the pathspec from the standard input + or a named file, instead of taking it as the command line + arguments, with the "--pathspec-from-file" option. + + * "git submodule" learned a subcommand "set-url". + + * "git log" family learned "--pretty=reference" that gives the name + of a commit in the format that is often used to refer to it in log + messages. + + * The interaction between "git clone --recurse-submodules" and + alternate object store was ill-designed. The documentation and + code have been taught to make more clear recommendations when the + users see failures. + + * Management of sparsely checked-out working tree has gained a + dedicated "sparse-checkout" command. + + * Miscellaneous small UX improvements on "git-p4". + + * "git sparse-checkout list" subcommand learned to give its output in + a more concise form when the "cone" mode is in effect. + + +Performance, Internal Implementation, Development Support etc. + + * Debugging support for lazy cloning has been a bit improved. + + * Move the definition of a set of bitmask constants from 0ctal + literal to (1U<<count) notation. + + * Test updates to prepare for SHA-2 transition continues. + + * Crufty code and logic accumulated over time around the object + parsing and low-level object access used in "git fsck" have been + cleaned up. + + * The implementation of "git log --graph" got refactored and then its + output got simplified. + + * Follow recent push to move API docs from Documentation/ to header + files and update config.h + + * "git bundle" has been taught to use the parse options API. "git + bundle verify" learned "--quiet" and "git bundle create" learned + options to control the progress output. + + * Handling of commit objects that use non UTF-8 encoding during + "rebase -i" has been improved. + + * The beginning of rewriting "git add -i" in C. + + * A label used in the todo list that are generated by "git rebase + --rebase-merges" is used as a part of a refname; the logic to come + up with the label has been tightened to avoid names that cannot be + used as such. + + * The logic to avoid duplicate label names generated by "git rebase + --rebase-merges" forgot that the machinery itself uses "onto" as a + label name, which must be avoided by auto-generated labels, which + has been corrected. + + * We have had compatibility fallback macro definitions for "PRIuMAX", + "PRIu32", etc. but did not for "PRIdMAX", while the code used the + last one apparently without any hiccup reported recently. The + fallback macro definitions for these <inttypes.h> macros that must + appear in C99 systems have been removed. + + * Recently we have declared that GIT_TEST_* variables take the + usual boolean values (it used to be that some used "non-empty + means true" and taking GIT_TEST_VAR=YesPlease as true); make + sure we notice and fail when non-bool strings are given to + these variables. + + * Users of oneway_merge() (like "reset --hard") learned to take + advantage of fsmonitor to avoid unnecessary lstat(2) calls. + + * Performance tweak on "git push" into a repository with many refs + that point at objects we have never heard of. + + * PerfTest fix to avoid stale result mixed up with the latest round + of test results. + + * Hide lower-level verify_signed-buffer() API as a pure helper to + implement the public check_signature() function, in order to + encourage new callers to use the correct and more strict + validation. + + * Unnecessary reading of state variables back from the disk during + sequencer operation has been reduced. + + * The code has been made to avoid gmtime() and localtime() and prefer + their reentrant counterparts. + + * In a repository with many packfiles, the cost of the procedure that + avoids registering the same packfile twice was unnecessarily high + by using an inefficient search algorithm, which has been corrected. + + * Redo "git name-rev" to avoid recursive calls. + + * FreeBSD CI support via Cirrus-CI has been added. + + +Fixes since v2.24 +----------------- + + * "rebase -i" ceased to run post-commit hook by mistake in an earlier + update, which has been corrected. + + * "git notes copy $original" ought to copy the notes attached to the + original object to HEAD, but a mistaken tightening to command line + parameter validation made earlier disabled that feature by mistake. + + * When all files from some subdirectory were renamed to the root + directory, the directory rename heuristics would fail to detect that + as a rename/merge of the subdirectory to the root directory, which has + been corrected. + + * Code clean-up and a bugfix in the logic used to tell worktree local + and repository global refs apart. + (merge f45f88b2e4 sg/dir-trie-fixes later to maint). + + * "git stash save" in a working tree that is sparsely checked out + mistakenly removed paths that are outside the area of interest. + (merge 4a58c3d7f7 js/update-index-ignore-removal-for-skip-worktree later to maint). + + * "git rev-parse --git-path HEAD.lock" did not give the right path + when run in a secondary worktree. + (merge 76a53d640f js/git-path-head-dot-lock-fix later to maint). + + * "git merge --no-commit" needs "--no-ff" if you do not want to move + HEAD, which has been corrected in the manual page for "git bisect". + (merge 8dd327b246 ma/bisect-doc-sample-update later to maint). + + * "git worktree add" internally calls "reset --hard" that should not + descend into submodules, even when submodule.recurse configuration + is set, but it was affected. This has been corrected. + (merge 4782cf2ab6 pb/no-recursive-reset-hard-in-worktree-add later to maint). + + * Messages from die() etc. can be mixed up from multiple processes + without even line buffering on Windows, which has been worked + around. + (merge 116d1fa6c6 js/vreportf-wo-buffering later to maint). + + * HTTP transport had possible allocator/deallocator mismatch, which + has been corrected. + + * The watchman integration for fsmonitor was racy, which has been + corrected to be more conservative. + (merge dd0b61f577 kw/fsmonitor-watchman-fix later to maint). + + * Fetching from multiple remotes into the same repository in parallel + had a bad interaction with the recent change to (optionally) update + the commit-graph after a fetch job finishes, as these parallel + fetches compete with each other. Which has been corrected. + + * Recent update to "git stash pop" made the command empty the index + when run with the "--quiet" option, which has been corrected. + + * "git fetch" codepath had a big "do not lazily fetch missing objects + when I ask if something exists" switch. This has been corrected by + marking the "does this thing exist?" calls with "if not please do not + lazily fetch it" flag. + + * Test update to avoid wasted cycles. + (merge e0316695ec sg/skip-skipped-prereq later to maint). + + * Error handling after "git push" finishes sending the packdata and + waits for the response to the remote side has been improved. + (merge ad7a403268 jk/send-pack-remote-failure later to maint). + + * Some codepaths in "gitweb" that forgot to escape URLs generated + based on end-user input have been corrected. + (merge a376e37b2c jk/gitweb-anti-xss later to maint). + + * CI jobs for macOS has been made less chatty when updating perforce + package used during testing. + (merge 0dbc4a0edf jc/azure-ci-osx-fix-fix later to maint). + + * "git unpack-objects" used to show progress based only on the number + of received and unpacked objects, which stalled when it has to + handle an unusually large object. It now shows the throughput as + well. + (merge bae60ba7e9 sg/unpack-progress-throughput later to maint). + + * The sequencer machinery compared the HEAD and the state it is + attempting to commit to decide if the result would be a no-op + commit, even when amending a commit, which was incorrect, and + has been corrected. + + * The code to parse GPG output used to assume incorrectly that the + finterprint for the primary key would always be present for a valid + signature, which has been corrected. + (merge 67a6ea6300 hi/gpg-optional-pkfp-fix later to maint). + + * "git submodule status" and "git submodule status --cached" show + different things, but the documentation did not cover them + correctly, which has been corrected. + (merge 8d483c8408 mg/doc-submodule-status-cached later to maint). + + * "git reset --patch $object" without any pathspec should allow a + tree object to be given, but incorrectly required a committish, + which has been corrected. + + * "git submodule status" that is run from a subdirectory of the + superproject did not work well, which has been corrected. + (merge 1f3aea22c7 mg/submodule-status-from-a-subdirectory later to maint). + + * The revision walking machinery uses resources like per-object flag + bits that need to be reset before a new iteration of walking + begins, but the resources related to topological walk were not + cleared correctly, which has been corrected. + (merge 0aa0c2b2ec mh/clear-topo-walk-upon-reset later to maint). + + * TravisCI update. + (merge 176441bfb5 sg/osx-force-gcc-9 later to maint). + + * While running "revert" or "cherry-pick --edit" for multiple + commits, a recent regression incorrectly detected "nothing to + commit, working tree clean", instead of replaying the commits, + which has been corrected. + (merge befd4f6a81 sg/assume-no-todo-update-in-cherry-pick later to maint). + + * Work around a issue where a FD that is left open when spawning a + child process and is kept open in the child can interfere with the + operation in the parent process on Windows. + + * One kind of progress messages were always given during commit-graph + generation, instead of following the "if it takes more than two + seconds, show progress" pattern, which has been corrected. + + * "git rebase" did not work well when format.useAutoBase + configuration variable is set, which has been corrected. + + * The "diff" machinery learned not to lose added/removed blank lines + in the context when --ignore-blank-lines and --function-context are + used at the same time. + (merge 0bb313a552 rs/xdiff-ignore-ws-w-func-context later to maint). + + * The test on "fast-import" used to get stuck when "fast-import" died + in the middle. + (merge 0d9b0d7885 sg/t9300-robustify later to maint). + + * "git format-patch" can take a set of configured format.notes values + to specify which notes refs to use in the log message part of the + output. The behaviour of this was not consistent with multiple + --notes command line options, which has been corrected. + (merge e0f9095aaa dl/format-patch-notes-config-fixup later to maint). + + * "git p4" used to ignore lfs.storage configuration variable, which + has been corrected. + (merge ea94b16fb8 rb/p4-lfs later to maint). + + * Assorted fixes to the directory traversal API. + (merge 6836d2fe06 en/fill-directory-fixes later to maint). + + * Forbid pathnames that the platform's filesystem cannot represent on + MinGW. + (merge 4dc42c6c18 js/mingw-reserved-filenames later to maint). + + * "git rebase --signoff" stopped working when the command was written + in C, which has been corrected. + (merge 4fe7e43c53 en/rebase-signoff-fix later to maint). + + * An earlier update to Git for Windows declared that a tree object is + invalid if it has a path component with backslash in it, which was + overly strict, which has been corrected. The only protection the + Windows users need is to prevent such path (or any path that their + filesystem cannot check out) from entering the index. + (merge 224c7d70fa js/mingw-loosen-overstrict-tree-entry-checks later to maint). + + * The code to write split commit-graph file(s) upon fetching computed + bogus value for the parameter used in splitting the resulting + files, which has been corrected. + (merge 63020f175f ds/commit-graph-set-size-mult later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 80736d7c5e jc/am-show-current-patch-docfix later to maint). + (merge 8b656572ca sg/commit-graph-usage-fix later to maint). + (merge 6c02042139 mr/clone-dir-exists-to-path-exists later to maint). + (merge 44ae131e38 sg/blame-indent-heuristics-is-now-the-default later to maint). + (merge 0115e5d929 dl/doc-diff-no-index-implies-exit-code later to maint). + (merge 270de6acbe en/t6024-style later to maint). + (merge 14c4776d75 ns/test-desc-typofix later to maint). + (merge 68d40f30c4 dj/typofix-merge-strat later to maint). + (merge f66e0401ab jk/optim-in-pack-idx-conversion later to maint). + (merge 169bed7421 rs/parse-options-dup-null-fix later to maint). + (merge 51bd6be32d rs/use-copy-array-in-mingw-shell-command-preparation later to maint). + (merge b018719927 ma/t7004 later to maint). + (merge 932757b0cc ar/install-doc-update-cmds-needing-the-shell later to maint). + (merge 46efd28be1 ep/guard-kset-tar-headers later to maint). + (merge 9e5afdf997 ec/fetch-mark-common-refs-trace2 later to maint). + (merge f0e58b3fe8 pb/submodule-update-fetches later to maint). + (merge 2a02262078 dl/t5520-cleanup later to maint). + (merge a4fb016ba1 js/pkt-line-h-typofix later to maint). + (merge 54a7a64613 rs/simplify-prepare-cmd later to maint). + (merge 3eae30e464 jk/lore-is-the-archive later to maint). + (merge 14b7664df8 dl/lore-is-the-archive later to maint). + (merge 0e40a73a4c po/bundle-doc-clonable later to maint). + (merge e714b898c6 as/t7812-missing-redirects-fix later to maint). + (merge 528d9e6d01 jk/perf-wo-git-dot-pm later to maint). + (merge fc42f20e24 sg/test-squelch-noise-in-commit-bulk later to maint). + (merge c64368e3a2 bc/t9001-zsh-in-posix-emulation-mode later to maint). + (merge 11de8dd7ef dr/branch-usage-casefix later to maint). + (merge e05e8cf074 rs/archive-zip-code-cleanup later to maint). + (merge 147ee35558 rs/commit-export-env-simplify later to maint). + (merge 4507ecc771 rs/patch-id-use-oid-to-hex later to maint). + (merge 51a0a4ed95 mr/bisect-use-after-free later to maint). + (merge cc2bd5c45d pb/submodule-doc-xref later to maint). + (merge df5be01669 ja/doc-markup-cleanup later to maint). + (merge 7c5cea7242 mr/bisect-save-pointer-to-const-string later to maint). + (merge 20a67e8ce9 js/use-test-tool-on-path later to maint). + (merge 4e61b2214d ew/packfile-syscall-optim later to maint). + (merge ace0f86c7f pb/clarify-line-log-doc later to maint). + (merge 763a59e71c en/merge-recursive-oid-eq-simplify later to maint). + (merge 4e2c4c0d4f do/gitweb-typofix-in-comments later to maint). + (merge 421c0ffb02 jb/doc-multi-pack-idx-fix later to maint). + (merge f8740c586b pm/am-in-body-header-doc-update later to maint). + (merge 5814d44d9b tm/doc-submodule-absorb-fix later to maint). diff --git a/Documentation/RelNotes/2.25.1.txt b/Documentation/RelNotes/2.25.1.txt new file mode 100644 index 0000000000..cd869b02bb --- /dev/null +++ b/Documentation/RelNotes/2.25.1.txt @@ -0,0 +1,55 @@ +Git 2.25.1 Release Notes +======================== + +Fixes since v2.25 +----------------- + + * "git commit" gives output similar to "git status" when there is + nothing to commit, but without honoring the advise.statusHints + configuration variable, which has been corrected. + + * has_object_file() said "no" given an object registered to the + system via pretend_object_file(), making it inconsistent with + read_object_file(), causing lazy fetch to attempt fetching an + empty tree from promisor remotes. + + * The code that tries to skip over the entries for the paths in a + single directory using the cache-tree was not careful enough + against corrupt index file. + + * Complete an update to tutorial that encourages "git switch" over + "git checkout" that was done only half-way. + + * Reduce unnecessary round-trip when running "ls-remote" over the + stateless RPC mechanism. + + * "git restore --staged" did not correctly update the cache-tree + structure, resulting in bogus trees to be written afterwards, which + has been corrected. + + * The code recently added to move to the entry beyond the ones in the + same directory in the index in the sparse-cone mode did not count + the number of entries to skip over incorrectly, which has been + corrected. + + * Work around test breakages caused by custom regex engine used in + libasan, when address sanitizer is used with more recent versions + of gcc and clang. + + * "git fetch --refmap=" option has got a better documentation. + + * Corner case bugs in "git clean" that stems from a (necessarily for + performance reasons) awkward calling convention in the directory + enumeration API has been corrected. + + * "git grep --no-index" should not get affected by the contents of + the .gitmodules file but when "--recurse-submodules" is given or + the "submodule.recurse" variable is set, it did. Now these + settings are ignored in the "--no-index" mode. + + * Technical details of the bundle format has been documented. + + * Unhelpful warning messages during documentation build have been + squelched. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.25.2.txt b/Documentation/RelNotes/2.25.2.txt new file mode 100644 index 0000000000..303c53a17f --- /dev/null +++ b/Documentation/RelNotes/2.25.2.txt @@ -0,0 +1,60 @@ +Git 2.25.2 Release Notes +======================== + +Fixes since v2.25.1 +------------------- + + * Minor bugfixes to "git add -i" that has recently been rewritten in C. + + * An earlier update to show the location of working tree in the error + message did not consider the possibility that a git command may be + run in a bare repository, which has been corrected. + + * The "--recurse-submodules" option of various subcommands did not + work well when run in an alternate worktree, which has been + corrected. + + * Running "git rm" on a submodule failed unnecessarily when + .gitmodules is only cache-dirty, which has been corrected. + + * "git rebase -i" identifies existing commits in its todo file with + their abbreviated object name, which could become ambigous as it + goes to create new commits, and has a mechanism to avoid ambiguity + in the main part of its execution. A few other cases however were + not covered by the protection against ambiguity, which has been + corrected. + + * The index-pack code now diagnoses a bad input packstream that + records the same object twice when it is used as delta base; the + code used to declare a software bug when encountering such an + input, but it is an input error. + + * The code to automatically shrink the fan-out in the notes tree had + an off-by-one bug, which has been killed. + + * "git check-ignore" did not work when the given path is explicitly + marked as not ignored with a negative entry in the .gitignore file. + + * The merge-recursive machinery failed to refresh the cache entry for + a merge result in a couple of places, resulting in an unnecessary + merge failure, which has been fixed. + + * Fix for a bug revealed by a recent change to make the protocol v2 + the default. + + * "git merge signed-tag" while lacking the public key started to say + "No signature", which was utterly wrong. This regression has been + reverted. + + * MinGW's poll() emulation has been improved. + + * "git show" and others gave an object name in raw format in its + error output, which has been corrected to give it in hex. + + * Both "git ls-remote -h" and "git grep -h" give short usage help, + like any other Git subcommand, but it is not unreasonable to expect + that the former would behave the same as "git ls-remote --head" + (there is no other sensible behaviour for the latter). The + documentation has been updated in an attempt to clarify this. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.25.3.txt b/Documentation/RelNotes/2.25.3.txt new file mode 100644 index 0000000000..15f7f21f10 --- /dev/null +++ b/Documentation/RelNotes/2.25.3.txt @@ -0,0 +1,5 @@ +Git v2.25.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.25.4.txt b/Documentation/RelNotes/2.25.4.txt new file mode 100644 index 0000000000..0dbb5daeec --- /dev/null +++ b/Documentation/RelNotes/2.25.4.txt @@ -0,0 +1,5 @@ +Git v2.25.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.26.0.txt b/Documentation/RelNotes/2.26.0.txt new file mode 100644 index 0000000000..3a7a734c26 --- /dev/null +++ b/Documentation/RelNotes/2.26.0.txt @@ -0,0 +1,341 @@ +Git 2.26 Release Notes +====================== + +Updates since v2.25 +------------------- + +Backward compatibility notes + + * "git rebase" uses a different backend that is based on the 'merge' + machinery by default. There are a few known differences in the + behaviour from the traditional machinery based on patch+apply. + + If your workflow is negatively affected by this change, please + report it to git@vger.kernel.org so that we can take a look into + it. After doing so, you can set the 'rebase.backend' configuration + variable to 'apply', in order to use the old default behaviour in + the meantime. + + +UI, Workflows & Features + + * Sample credential helper for using .netrc has been updated to work + out of the box. + + * gpg.minTrustLevel configuration variable has been introduced to + tell various signature verification codepaths the required minimum + trust level. + + * The command line completion (in contrib/) learned to complete + subcommands and arguments to "git worktree". + + * Disambiguation logic to tell revisions and pathspec apart has been + tweaked so that backslash-escaped glob special characters do not + count in the "wildcards are pathspec" rule. + + * One effect of specifying where the GIT_DIR is (either with the + environment variable, or with the "git --git-dir=<where> cmd" + option) is to disable the repository discovery. This has been + placed a bit more stress in the documentation, as new users often + get confused. + + * Two help messages given when "git add" notices the user gave it + nothing to add have been updated to use advise() API. + + * A new version of fsmonitor-watchman hook has been introduced, to + avoid races. + + * "git config" learned to show in which "scope", in addition to in + which file, each config setting comes from. + + * The basic 7 colors learned the brighter counterparts + (e.g. "brightred"). + + * "git sparse-checkout" learned a new "add" subcommand. + + * A configuration element used for credential subsystem can now use + wildcard pattern to specify for which set of URLs the entry + applies. + + * "git clone --recurse-submodules --single-branch" now uses the same + single-branch option when cloning the submodules. + + * "git rm" and "git stash" learns the new "--pathspec-from-file" + option. + + * "git am --show-current-patch" is a way to show the piece of e-mail + for the stopped step, which is not suitable to directly feed "git + apply" (it is designed to be a good "git am" input). It learned a + new option to show only the patch part. + + * Handling of conflicting renames in merge-recursive have further + been made consistent with how existing codepaths try to mimic what + is done to add/add conflicts. + + +Performance, Internal Implementation, Development Support etc. + + * Tell .editorconfig that in this project, *.txt files are indented + with tabs. + + * The test-lint machinery knew to check "VAR=VAL shell_function" + construct, but did not check "VAR= shell_function", which has been + corrected. + + * Replace "git config --bool" calls with "git config --type=bool" in + sample templates. + + * The effort to move "git-add--interactive" to C continues. + + * Improve error message generation for "git submodule add". + + * Preparation of test scripts for the day when the object names will + use SHA-256 continues. + + * Warn programmers about pretend_object_file() that allows the code + to tentatively use in-core objects. + + * The way "git pack-objects" reuses objects stored in existing pack + to generate its result has been improved. + + * The transport protocol version 2 becomes the default one. + + * Traditionally, we avoided threaded grep while searching in objects + (as opposed to files in the working tree) as accesses to the object + layer is not thread-safe. This limitation is getting lifted. + + * "git rebase -i" (and friends) used to unnecessarily check out the + tip of the branch to be rebased, which has been corrected. + + * A low-level API function get_oid(), that accepts various ways to + name an object, used to issue end-user facing error messages + without l10n, which has been updated to be translatable. + + * Unneeded connectivity check is now disabled in a partial clone when + fetching into it. + + * Some rough edges in the sparse-checkout feature, especially around + the cone mode, have been cleaned up. + + * The diff-* plumbing family of subcommands now pay attention to the + diff.wsErrorHighlight configuration, which has been ignored before; + this allows "git add -p" to also show the whitespace problems to + the end user. + + * Some codepaths were given a repository instance as a parameter to + work in the repository, but passed the_repository instance to its + callees, which has been cleaned up (somewhat). + + * Memory footprint and performance of "git name-rev" has been + improved. + + * The object reachability bitmap machinery and the partial cloning + machinery were not prepared to work well together, because some + object-filtering criteria that partial clones use inherently rely + on object traversal, but the bitmap machinery is an optimization + to bypass that object traversal. There however are some cases + where they can work together, and they were taught about them. + + * "git rebase" has learned to use the merge backend (i.e. the + machinery that drives "rebase -i") by default, while allowing + "--apply" option to use the "apply" backend (e.g. the moral + equivalent of "format-patch piped to am"). The rebase.backend + configuration variable can be set to customize. + + * Underlying machinery of "git bisect--helper" is being refactored + into pieces that are more easily reused. + + +Fixes since v2.25 +----------------- + + * "git commit" gives output similar to "git status" when there is + nothing to commit, but without honoring the advise.statusHints + configuration variable, which has been corrected. + + * has_object_file() said "no" given an object registered to the + system via pretend_object_file(), making it inconsistent with + read_object_file(), causing lazy fetch to attempt fetching an + empty tree from promisor remotes. + + * Complete an update to tutorial that encourages "git switch" over + "git checkout" that was done only half-way. + + * C pedantry ;-) fix. + + * The code that tries to skip over the entries for the paths in a + single directory using the cache-tree was not careful enough + against corrupt index file. + + * Reduce unnecessary round-trip when running "ls-remote" over the + stateless RPC mechanism. + + * "git restore --staged" did not correctly update the cache-tree + structure, resulting in bogus trees to be written afterwards, which + has been corrected. + + * The code recently added to move to the entry beyond the ones in the + same directory in the index in the sparse-cone mode did not count + the number of entries to skip over incorrectly, which has been + corrected. + + * Rendering by "git log --graph" of ancestry lines leading to a merge + commit were made suboptimal to waste vertical space a bit with a + recent update, which has been corrected. + + * Work around test breakages caused by custom regex engine used in + libasan, when address sanitizer is used with more recent versions + of gcc and clang. + + * Minor bugfixes to "git add -i" that has recently been rewritten in C. + + * "git fetch --refmap=" option has got a better documentation. + + * "git checkout X" did not correctly fail when X is not a local + branch but could name more than one remote-tracking branches + (i.e. to be dwimmed as the starting point to create a corresponding + local branch), which has been corrected. + (merge fa74180d08 am/checkout-file-and-ref-ref-ambiguity later to maint). + + * Corner case bugs in "git clean" that stems from a (necessarily for + performance reasons) awkward calling convention in the directory + enumeration API has been corrected. + + * A fetch that is told to recursively fetch updates in submodules + inevitably produces reams of output, and it becomes hard to spot + error messages. The command has been taught to enumerate + submodules that had errors at the end of the operation. + (merge 0222540827 es/fetch-show-failed-submodules-atend later to maint). + + * The "--recurse-submodules" option of various subcommands did not + work well when run in an alternate worktree, which has been + corrected. + + * Futureproofing a test not to depend on the current implementation + detail. + + * Running "git rm" on a submodule failed unnecessarily when + .gitmodules is only cache-dirty, which has been corrected. + + * C pedantry ;-) fix. + + * "git grep --no-index" should not get affected by the contents of + the .gitmodules file but when "--recurse-submodules" is given or + the "submodule.recurse" variable is set, it did. Now these + settings are ignored in the "--no-index" mode. + + * Technical details of the bundle format has been documented. + + * Unhelpful warning messages during documentation build have been squelched. + + * "git rebase -i" identifies existing commits in its todo file with + their abbreviated object name, which could become ambiguous as it + goes to create new commits, and has a mechanism to avoid ambiguity + in the main part of its execution. A few other cases however were + not covered by the protection against ambiguity, which has been + corrected. + + * Allow the rebase.missingCommitsCheck configuration to kick in when + "rebase --edit-todo" and "rebase --continue" restarts the procedure. + (merge 5a5445d878 ag/edit-todo-drop-check later to maint). + + * The way "git submodule status" reports an initialized but not yet + populated submodule has not been reimplemented correctly when a + part of the "git submodule" command was rewritten in C, which has + been corrected. + (merge f38c92452d pk/status-of-uncloned-submodule later to maint). + + * The code to automatically shrink the fan-out in the notes tree had + an off-by-one bug, which has been killed. + + * The index-pack code now diagnoses a bad input packstream that + records the same object twice when it is used as delta base; the + code used to declare a software bug when encountering such an + input, but it is an input error. + + + * The code to compute the commit-graph has been taught to use a more + robust way to tell if two object directories refer to the same + thing. + (merge a7df60cac8 tb/commit-graph-object-dir later to maint). + + * "git remote rename X Y" needs to adjust configuration variables + (e.g. branch.<name>.remote) whose value used to be X to Y. + branch.<name>.pushRemote is now also updated. + + * Update to doc-diff. + + * Doc markup fix. + + * "git check-ignore" did not work when the given path is explicitly + marked as not ignored with a negative entry in the .gitignore file. + + * The merge-recursive machinery failed to refresh the cache entry for + a merge result in a couple of places, resulting in an unnecessary + merge failure, which has been fixed. + + * Fix for a bug revealed by a recent change to make the protocol v2 + the default. + + * In rare cases "git worktree add <path>" could think that <path> + was already a registered worktree even when it wasn't and refuse + to add the new worktree. This has been corrected. + (merge bb69b3b009 es/worktree-avoid-duplication-fix later to maint). + + * "git push" should stop from updating a branch that is checked out + when receive.denyCurrentBranch configuration is set, but it failed + to pay attention to checkouts in secondary worktrees. This has + been corrected. + (merge 4d864895a2 hv/receive-denycurrent-everywhere later to maint). + + * "git rebase BASE BRANCH" rebased/updated the tip of BRANCH and + checked it out, even when the BRANCH is checked out in a different + worktree. This has been corrected. + (merge b5cabb4a96 es/do-not-let-rebase-switch-to-protected-branch later to maint). + + * "git describe" in a repository with multiple root commits sometimes + gave up looking for the best tag to describe a given commit with + too early, which has been adjusted. + + * "git merge signed-tag" while lacking the public key started to say + "No signature", which was utterly wrong. This regression has been + reverted. + + * MinGW's poll() emulation has been improved. + + * "git show" and others gave an object name in raw format in its + error output, which has been corrected to give it in hex. + + * "git fetch" over HTTP walker protocol did not show any progress + output. We inherently do not know how much work remains, but still + we can show something not to bore users. + (merge 7655b4119d rs/show-progress-in-dumb-http-fetch later to maint). + + * Both "git ls-remote -h" and "git grep -h" give short usage help, + like any other Git subcommand, but it is not unreasonable to expect + that the former would behave the same as "git ls-remote --head" + (there is no other sensible behaviour for the latter). The + documentation has been updated in an attempt to clarify this. + + * Other code cleanup, docfix, build fix, etc. + (merge d0d0a357a1 am/update-pathspec-f-f-tests later to maint). + (merge f94f7bd00d am/test-pathspec-f-f-error-cases later to maint). + (merge c513a958b6 ss/t6025-modernize later to maint). + (merge b441717256 dl/test-must-fail-fixes later to maint). + (merge d031049da3 mt/sparse-checkout-doc-update later to maint). + (merge 145136a95a jc/skip-prefix later to maint). + (merge 5290d45134 jk/alloc-cleanups later to maint). + (merge 7a9f8ca805 rs/parse-options-concat-dup later to maint). + (merge 517b60564e rs/strbuf-insertstr later to maint). + (merge f696a2b1c8 jk/mailinfo-cleanup later to maint). + (merge de26f02db1 js/test-avoid-pipe later to maint). + (merge a2dc43414c es/doc-mentoring later to maint). + (merge 02bbbe9df9 es/worktree-cleanup later to maint). + (merge 2ce6d075fa rs/micro-cleanups later to maint). + (merge 27f182b3fc rs/blame-typefix-for-fingerprint later to maint). + (merge 3c29e21eb0 ma/test-cleanup later to maint). + (merge 240fc04f81 ag/rebase-remove-redundant-code later to maint). + (merge d68ce906c7 rs/commit-graph-code-simplification later to maint). + (merge a51d9e8f07 rj/t1050-use-test-path-is-file later to maint). + (merge fd0bc17557 kk/complete-diff-color-moved later to maint). + (merge 65bf820d0e en/test-cleanup later to maint). diff --git a/Documentation/RelNotes/2.26.1.txt b/Documentation/RelNotes/2.26.1.txt new file mode 100644 index 0000000000..1b4ecb3fdc --- /dev/null +++ b/Documentation/RelNotes/2.26.1.txt @@ -0,0 +1,5 @@ +Git v2.26.1 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.26.2.txt b/Documentation/RelNotes/2.26.2.txt new file mode 100644 index 0000000000..d434d0c695 --- /dev/null +++ b/Documentation/RelNotes/2.26.2.txt @@ -0,0 +1,5 @@ +Git v2.26.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.27.0.txt b/Documentation/RelNotes/2.27.0.txt new file mode 100644 index 0000000000..5fb8c0cf67 --- /dev/null +++ b/Documentation/RelNotes/2.27.0.txt @@ -0,0 +1,515 @@ +Git 2.27 Release Notes +====================== + +Updates since v2.26 +------------------- + +Backward compatibility notes + + * When "git describe C" finds that commit C is pointed by a signed or + annotated tag, which records T as its tagname in the object, the + command gives T as its answer. Even if the user renames or moves + such a tag from its natural location in the "refs/tags/" hierarchy, + "git describe C" would still give T as the answer, but in such a + case "git show T^0" would no longer work as expected. There may be + nothing at "refs/tags/T" or even worse there may be a different tag + instead. + + Starting from this version, "git describe" will always use the + "long" version, as if the "--long" option were given, when giving + its output based on such a misplaced tag to work around the problem. + + * "git pull" issues a warning message until the pull.rebase + configuration variable is explicitly given, which some existing + users may find annoying---those who prefer not to rebase need to + set the variable to false to squelch the warning. + + +UI, Workflows & Features + + * A handful of options to configure SSL when talking to proxies have + been added. + + * Smudge/clean conversion filters are now given more information + (e.g. the object of the tree-ish in which the blob being converted + appears, in addition to its path, which has already been given). + + * When "git describe C" finds an annotated tag with tagname A to be + the best name to explain commit C, and the tag is stored in a + "wrong" place in the refs/tags hierarchy, e.g. refs/tags/B, the + command gave a warning message but used A (not B) to describe C. + If C is exactly at the tag, the describe output would be "A", but + "git rev-parse A^0" would not be equal as "git rev-parse C^0". The + behavior of the command has been changed to use the "long" form + i.e. A-0-gOBJECTNAME, which is correctly interpreted by rev-parse. + + * "git pull" learned to warn when no pull.rebase configuration + exists, and neither --[no-]rebase nor --ff-only is given (which + would result a merge). + + * "git p4" learned four new hooks and also "--no-verify" option to + bypass them (and the existing "p4-pre-submit" hook). + + * "git pull" shares many options with underlying "git fetch", but + some of them were not documented and some of those that would make + sense to pass down were not passed down. + + * "git rebase" learned the "--no-gpg-sign" option to countermand + commit.gpgSign the user may have. + + * The output from "git format-patch" uses RFC 2047 encoding for + non-ASCII letters on From: and Subject: headers, so that it can + directly be fed to e-mail programs. A new option has been added + to produce these headers in raw. + + * "git log" learned "--show-pulls" that helps pathspec limited + history views; a merge commit that takes the whole change from a + side branch, which is normally omitted from the output, is shown + in addition to the commits that introduce real changes. + + * The interactive input from various codepaths are consolidated and + any prompt possibly issued earlier are fflush()ed before we read. + + * Allow "git rebase" to reapply all local commits, even if the may be + already in the upstream, without checking first. + + * The 'pack.useSparse' configuration variable now defaults to 'true', + enabling an optimization that has been experimental since Git 2.21. + + * "git rebase" happens to call some hooks meant for "checkout" and + "commit" by this was not a designed behaviour than historical + accident. This has been documented. + + * "git merge" learns the "--autostash" option. + + * "sparse-checkout" UI improvements. + + * "git update-ref --stdin" learned a handful of new verbs to let the + user control ref update transactions more explicitly, which helps + as an ingredient to implement two-phase commit-style atomic + ref-updates across multiple repositories. + + * "git commit-graph write" learned different ways to write out split + files. + + * Introduce an extension to the commit-graph to make it efficient to + check for the paths that were modified at each commit using Bloom + filters. + + * The approxidate parser learns to parse seconds with fraction and + ignore fractional part. + + * The userdiff patterns for Markdown documents have been added. + + * The sparse-checkout patterns have been forbidden from excluding all + paths, leaving an empty working tree, for a long time. This + limitation has been lifted. + + * "git restore --staged --worktree" now defaults to take the contents + out of "HEAD", instead of erring out. + + * "git p4" learned to recover from a (broken) state where a directory + and a file are recorded at the same path in the Perforce repository + the same way as their clients do. + + * "git multi-pack-index repack" has been taught to honor some + repack.* configuration variables. + + +Performance, Internal Implementation, Development Support etc. + + * The advise API has been revamped to allow more systematic enumeration of + advice knobs in the future. + + * SHA-256 transition continues. + + * The code to interface with GnuPG has been refactored. + + * "git stash" has kept an escape hatch to use the scripted version + for a few releases, which got stale. It has been removed. + + * Enable tests that require GnuPG on Windows. + + * Minor test usability improvement. + + * Trace2 enhancement to allow logging of the environment variables. + + * Test clean-up continues. + + * Perf-test update. + + * A Windows-specific test element has been made more robust against + misuse from both user's environment and programmer's errors. + + * Various tests have been updated to work around issues found with + shell utilities that come with busybox etc. + + * The config API made mixed uses of int and size_t types to represent + length of various pieces of text it parsed, which has been updated + to use the correct type (i.e. size_t) throughout. + + * The "--decorate-refs" and "--decorate-refs-exclude" options "git + log" takes have learned a companion configuration variable + log.excludeDecoration that sits at the lowest priority in the + family. + + * A new CI job to build and run test suite on linux with musl libc + has been added. + + * Update the CI configuration to use GitHub Actions, retiring the one + based on Azure Pipelines. + + * The directory traversal code had redundant recursive calls which + made its performance characteristics exponential with respect to + the depth of the tree, which was corrected. + + * "git blame" learns to take advantage of the "changed-paths" Bloom + filter stored in the commit-graph file. + + * The "bugreport" tool has been added. + + * The object walk with object filter "--filter=tree:0" can now take + advantage of the pack bitmap when available. + + * Instead of always building all branches at GitHub via Actions, + users can specify which branches to build. + + * Codepaths that show progress meter have been taught to also use the + start_progress() and the stop_progress() calls as a "region" to be + traced. + + * Instead of downloading Windows SDK for CI jobs for windows builds + from an external site (wingit.blob.core.windows.net), use the one + created in the windows-build job, to work around quota issues at + the external site. + + +Fixes since v2.26 +----------------- + + * The real_path() convenience function can easily be misused; with a + bit of code refactoring in the callers' side, its use has been + eliminated. + (merge 49d3c4b481 am/real-path-fix later to maint). + + * Update "git p4" to work with Python 3. + (merge 6bb40ed20a yz/p4-py3 later to maint). + + * The mechanism to prevent "git commit" from making an empty commit + or amending during an interrupted cherry-pick was broken during the + rewrite of "git rebase" in C, which has been corrected. + (merge 430b75f720 pw/advise-rebase-skip later to maint). + + * Fix "git checkout --recurse-submodules" of a nested submodule + hierarchy. + (merge 846f34d351 pb/recurse-submodules-fix later to maint). + + * The "--fork-point" mode of "git rebase" regressed when the command + was rewritten in C back in 2.20 era, which has been corrected. + (merge f08132f889 at/rebase-fork-point-regression-fix later to maint). + + * The import-tars importer (in contrib/fast-import/) used to create + phony files at the top-level of the repository when the archive + contains global PAX headers, which made its own logic to detect and + omit the common leading directory ineffective, which has been + corrected. + (merge c839fcff65 js/import-tars-do-not-make-phony-files-from-pax-headers later to maint). + + * Simplify the commit ancestry connectedness check in a partial clone + repository in which "promised" objects are assumed to be obtainable + lazily on-demand from promisor remote repositories. + (merge 2b98478c6f jt/connectivity-check-optim-in-partial-clone later to maint). + + * The server-end of the v2 protocol to serve "git clone" and "git + fetch" was not prepared to see a delim packets at unexpected + places, which led to a crash. + (merge cacae4329f jk/harden-protocol-v2-delim-handling later to maint). + + * When fed a midx that records no objects, some codepaths tried to + loop from 0 through (num_objects-1), which, due to integer + arithmetic wrapping around, made it nonsense operation with out of + bounds array accesses. The code has been corrected to reject such + an midx file. + (merge 796d61cdc0 dr/midx-avoid-int-underflow later to maint). + + * Utitiles run via the run_command() API were not spawned correctly + on Cygwin, when the paths to them are given as a full path with + backslashes. + (merge 05ac8582bc ak/run-command-on-cygwin-fix later to maint). + + * "git pull --rebase" tried to run a rebase even after noticing that + the pull results in a fast-forward and no rebase is needed nor + sensible, for the past few years due to a mistake nobody noticed. + (merge fbae70ddc6 en/pull-do-not-rebase-after-fast-forwarding later to maint). + + * "git rebase" with the merge backend did not work well when the + rebase.abbreviateCommands configuration was set. + (merge de9f1d3ef4 ag/rebase-merge-allow-ff-under-abbrev-command later to maint). + + * The logic to auto-follow tags by "git clone --single-branch" was + not careful to avoid lazy-fetching unnecessary tags, which has been + corrected. + (merge 167a575e2d jk/use-quick-lookup-in-clone-for-tag-following later to maint). + + * "git rebase -i" did not leave the reflog entries correctly. + (merge 1f6965f994 en/sequencer-reflog-action later to maint). + + * The more aggressive updates to remote-tracking branches we had for + the past 7 years or so were not reflected in the documentation, + which has been corrected. + (merge a44088435c pb/pull-fetch-doc later to maint). + + * We've left the command line parsing of "git log :/a/b/" broken for + about a full year without anybody noticing, which has been + corrected. + (merge 0220461071 jc/missing-ref-store-fix later to maint). + + * Misc fixes for Windows. + (merge 3efc128cd5 js/mingw-fixes later to maint). + + * "git rebase" (again) learns to honor "--no-keep-empty", which lets + the user to discard commits that are empty from the beginning (as + opposed to the ones that become empty because of rebasing). The + interactive rebase also marks commits that are empty in the todo. + (merge 50ed76148a en/rebase-no-keep-empty later to maint). + + * Parsing the host part out of URL for the credential helper has been corrected. + (merge 4c5971e18a jk/credential-parsing-end-of-host-in-URL later to maint). + + * Document the recommended way to abort a failing test early (e.g. by + exiting a loop), which is to say "return 1". + (merge 7cc112dc95 jc/doc-test-leaving-early later to maint). + + * The code that refreshes the last access and modified time of + on-disk packfiles and loose object files have been updated. + (merge 312cd76130 lr/freshen-file-fix later to maint). + + * Validation of push certificate has been made more robust against + timing attacks. + (merge 719483e547 bc/constant-memequal later to maint). + + * The custom hash function used by "git fast-import" has been + replaced with the one from hashmap.c, which gave us a nice + performance boost. + (merge d8410a816b jk/fast-import-use-hashmap later to maint). + + * The "git submodule" command did not initialize a few variables it + internally uses and was affected by variable settings leaked from + the environment. + (merge 65d100c4dd lx/submodule-clear-variables later to maint). + + * Raise the minimum required version of docbook-xsl package to 1.74, + as 1.74.0 was from late 2008, which is more than 10 years old, and + drop compatibility cruft from our documentation suite. + (merge 3c255ad660 ma/doc-discard-docbook-xsl-1.73 later to maint). + + * "git log" learns "--[no-]mailmap" as a synonym to "--[no-]use-mailmap" + (merge 88acccda38 jc/log-no-mailmap later to maint). + + * "git commit-graph write --expire-time=<timestamp>" did not use the + given timestamp correctly, which has been corrected. + (merge b09b785c78 ds/commit-graph-expiry-fix later to maint). + + * Tests update to use "test-chmtime" instead of "touch -t". + (merge e892a56845 ds/t5319-touch-fix later to maint). + + * "git diff" in a partial clone learned to avoid lazy loading blob + objects in more casese when they are not needed. + (merge 95acf11a3d jt/avoid-prefetch-when-able-in-diff later to maint). + + * "git push --atomic" used to show failures for refs that weren't + even pushed, which has been corrected. + (merge dfe1b7f19c jx/atomic-push later to maint). + + * Code in builtin/*, i.e. those can only be called from within + built-in subcommands, that implements bulk of a couple of + subcommands have been moved to libgit.a so that they could be used + by others. + (merge 9460fd48b5 dl/libify-a-few later to maint). + + * Allowing the user to split a patch hunk while "git stash -p" does + not work well; a band-aid has been added to make this (partially) + work better. + + * "git diff-tree --pretty --notes" used to hit an assertion failure, + as it forgot to initialize the notes subsystem. + (merge 5778b22b3d tb/diff-tree-with-notes later to maint). + + * "git range-diff" fixes. + (merge 8d1675eb7f vd/range-diff-with-custom-pretty-format-fix later to maint). + + * "git grep" did not quote a path with unusual character like other + commands (like "git diff", "git status") do, but did quote when run + from a subdirectory, both of which has been corrected. + (merge 45115d8490 mt/grep-cquote-path later to maint). + + * GNU/Hurd is also among the ones that need the fopen() wrapper. + (merge 274a1328fb jc/gnu-hurd-lets-fread-read-dirs later to maint). + + * Those fetching over protocol v2 from linux-next and other kernel + repositories are reporting that v2 often fetches way too much than + needed. + (merge 11c7f2a30b jn/demote-proto2-from-default later to maint). + + * The upload-pack protocol v2 gave up too early before finding a + common ancestor, resulting in a wasteful fetch from a fork of a + project. This has been corrected to match the behaviour of v0 + protocol. + (merge 2f0a093dd6 jt/v2-fetch-nego-fix later to maint). + + * The build procedure did not use the libcurl library and its include + files correctly for a custom-built installation. + (merge 0573831950 jk/build-with-right-curl later to maint). + + * Tighten "git mailinfo" to notice and error out when decoded result + contains NUL in it. + (merge 3919997447 dd/mailinfo-with-nul later to maint). + + * Fix in-core inconsistency after fetching into a shallow repository + that broke the code to write out commit-graph. + (merge 37b9dcabfc tb/reset-shallow later to maint). + + * The commit-graph code exhausted file descriptors easily when it + does not have to. + (merge c8828530b7 tb/commit-graph-fd-exhaustion-fix later to maint). + + * The multi-pack-index left mmapped file descriptors open when it + does not have to. + (merge 6c7ff7cf7f ds/multi-pack-index later to maint). + + * Recent update to Homebrew used by macOS folks breaks build by + moving gettext library and necessary headers. + (merge a0b3108618 ds/build-homebrew-gettext-fix later to maint). + + * Incompatible options "--root" and "--fork-point" of "git rebase" + have been marked and documented as being incompatible. + (merge a35413c378 en/rebase-root-and-fork-point-are-incompatible later to maint). + + * Error and verbose trace messages from "git push" did not redact + credential material embedded in URLs. + (merge d192fa5006 js/anonymise-push-url-in-errors later to maint). + + * Update the parser used for credential.<URL>.<variable> + configuration, to handle <URL>s with '/' in them correctly. + (merge b44d0118ac bc/wildcard-credential later to maint). + + * Recent updates broke parsing of "credential.<url>.<key>" where + <url> is not a full URL (e.g. [credential "https://"] helper = ...) + stopped working, which has been corrected. + (merge 9a121b0d22 js/partial-urlmatch-2.17 later to maint). + (merge cd93e6c029 js/partial-urlmatch later to maint). + + * Some of the files commit-graph subsystem keeps on disk did not + correctly honor the core.sharedRepository settings and some were + left read-write. + + * In error messages that "git switch" mentions its option to create a + new branch, "-b/-B" options were shown, where "-c/-C" options + should be, which has been corrected. + (merge 7c16ef7577 dl/switch-c-option-in-error-message later to maint). + + * With the recent tightening of the code that is used to parse + various parts of a URL for use in the credential subsystem, a + hand-edited credential-store file causes the credential helper to + die, which is a bit too harsh to the users. Demote the error + behaviour to just ignore and keep using well-formed lines instead. + (merge c03859a665 cb/credential-store-ignore-bogus-lines later to maint). + + * The samples in the credential documentation has been updated to + make it clear that we depict what would appear in the .git/config + file, by adding appropriate quotes as needed.. + (merge 177681a07e jk/credential-sample-update later to maint). + + * "git branch" and other "for-each-ref" variants accepted multiple + --sort=<key> options in the increasing order of precedence, but it + had a few breakages around "--ignore-case" handling, and tie-breaking + with the refname, which have been fixed. + (merge 7c5045fc18 jk/for-each-ref-multi-key-sort-fix later to maint). + + * The coding guideline for shell scripts instructed to refer to a + variable with dollar-sign inside arithmetic expansion to work + around a bug in old versions of dash, which is a thing of the past. + Now we are not forbidden from writing $((var+1)). + (merge 32b5fe7f0e jk/arith-expansion-coding-guidelines later to maint). + + * The <stdlib.h> header on NetBSD brings in its own definition of + hmac() function (eek), which conflicts with our own and unrelated + function with the same name. Our function has been renamed to work + around the issue. + (merge 3013118eb8 cb/avoid-colliding-with-netbsd-hmac later to maint). + + * The basic test did not honor $TEST_SHELL_PATH setting, which has + been corrected. + (merge 0555e4af58 cb/t0000-use-the-configured-shell later to maint). + + * Minor in-code comments and documentation updates around credential + API. + (merge 1aed817f99 cb/credential-doc-fixes later to maint). + + * Teach "am", "commit", "merge" and "rebase", when they are run with + the "--quiet" option, to pass "--quiet" down to "gc --auto". + (merge 7c3e9e8cfb jc/auto-gc-quiet later to maint). + + * The code to skip unmerged paths in the index when sparse checkout + is in use would have made out-of-bound access of the in-core index + when the last path was unmerged, which has been corrected. + + * Serving a "git fetch" client over "git://" and "ssh://" protocols + using the on-wire protocol version 2 was buggy on the server end + when the client needs to make a follow-up request to + e.g. auto-follow tags. + (merge 08450ef791 cc/upload-pack-v2-fetch-fix later to maint). + + * "git bisect replay" had trouble with input files when they used + CRLF line ending, which has been corrected. + (merge 6c722cbe5a cw/bisect-replay-with-dos later to maint). + + * "rebase -i" segfaulted when rearranging a sequence that has a + fix-up that applies another fix-up (which may or may not be a + fix-up of yet another step). + (merge 02471e7e20 js/rebase-autosquash-double-fixup-fix later to maint). + + * "git fsck" ensures that the paths recorded in tree objects are + sorted and without duplicates, but it failed to notice a case where + a blob is followed by entries that sort before a tree with the same + name. This has been corrected. + (merge 9068cfb20f rs/fsck-duplicate-names-in-trees later to maint). + + * Code clean-up by removing a compatibility implementation of a + function we no longer use. + (merge 84b0115f0d cb/no-more-gmtime later to maint). + + * When a binary file gets modified and renamed on both sides of history + to different locations, both files would be written to the working + tree but both would have the contents from "ours". This has been + corrected so that the path from each side gets their original content. + + * Other code cleanup, docfix, build fix, etc. + (merge 564956f358 jc/maintain-doc later to maint). + (merge 7422b2a0a1 sg/commit-slab-clarify-peek later to maint). + (merge 9c688735f6 rs/doc-passthru-fetch-options later to maint). + (merge 757c2ba3e2 en/oidset-uninclude-hashmap later to maint). + (merge 8312aa7d74 jc/config-tar later to maint). + (merge d00a5bdd50 ss/submodule-foreach-cb later to maint). + (merge 64d1022e14 ar/test-style-fixes later to maint). + (merge 4a465443a6 ds/doc-clone-filter later to maint). + (merge bb2dbe301b jk/t3419-drop-expensive-tests later to maint). + (merge d3507cc712 js/test-junit-finalization-fix later to maint). + (merge 2149b6748f bc/faq later to maint). + (merge 12dc0879f1 jk/test-cleanup later to maint). + (merge 344420bf0f pb/rebase-doc-typofix later to maint). + (merge 7cd54d37dc dl/wrapper-fix-indentation later to maint). + (merge 78725ebda9 jc/allow-strlen-substitution-in-shell-scripts later to maint). + (merge 2ecfcdecc6 jm/gitweb-fastcgi-utf8 later to maint). + (merge 0740d0a5d3 jk/oid-array-cleanups later to maint). + (merge a1aba0c95c js/t0007-typofix later to maint). + (merge 76ba7fa225 ma/config-doc-fix later to maint). + (merge 826f0c0df2 js/subtree-doc-update-to-asciidoctor-2 later to maint). + (merge 88eaf361e0 eb/mboxrd-doc later to maint). + (merge 051cc54941 tm/zsh-complete-switch-restore later to maint). + (merge 39102cf4fe ms/doc-revision-illustration-fix later to maint). + (merge 4d9378bfad eb/gitweb-more-trailers later to maint). + (merge bdccbf7047 mt/doc-worktree-ref later to maint). + (merge ce9baf234f dl/push-recurse-submodules-fix later to maint). + (merge 4153274052 bc/doc-credential-helper-value later to maint). + (merge 5c7bb0146e jc/codingstyle-compare-with-null later to maint). diff --git a/Documentation/RelNotes/2.3.3.txt b/Documentation/RelNotes/2.3.3.txt index 5ef12644c2..850dc68ede 100644 --- a/Documentation/RelNotes/2.3.3.txt +++ b/Documentation/RelNotes/2.3.3.txt @@ -12,7 +12,7 @@ Fixes since v2.3.2 * Description given by "grep -h" for its --exclude-standard option was phrased poorly. - * Documentaton for "git remote add" mentioned "--tags" and + * Documentation for "git remote add" mentioned "--tags" and "--no-tags" and it was not clear that fetch from the remote in the future will use the default behaviour when neither is given to override it. diff --git a/Documentation/RelNotes/2.3.7.txt b/Documentation/RelNotes/2.3.7.txt index fc95812cb3..5769184081 100644 --- a/Documentation/RelNotes/2.3.7.txt +++ b/Documentation/RelNotes/2.3.7.txt @@ -4,7 +4,7 @@ Git v2.3.7 Release Notes Fixes since v2.3.6 ------------------ - * An earlier update to the parser that disects a URL broke an + * An earlier update to the parser that dissects a URL broke an address, followed by a colon, followed by an empty string (instead of the port number), e.g. ssh://example.com:/path/to/repo. diff --git a/Documentation/RelNotes/2.4.3.txt b/Documentation/RelNotes/2.4.3.txt index 914d2c1860..422e930aa2 100644 --- a/Documentation/RelNotes/2.4.3.txt +++ b/Documentation/RelNotes/2.4.3.txt @@ -66,7 +66,7 @@ Fixes since v2.4.3 * Some time ago, "git blame" (incorrectly) lost the convert_to_git() call when synthesizing a fake "tip" commit that represents the state in the working tree, which broke folks who record the history - with LF line ending to make their project portabile across + with LF line ending to make their project portable across platforms while terminating lines in their working tree files with CRLF for their platform. diff --git a/Documentation/RelNotes/2.5.0.txt b/Documentation/RelNotes/2.5.0.txt index 87044504c5..84723f912a 100644 --- a/Documentation/RelNotes/2.5.0.txt +++ b/Documentation/RelNotes/2.5.0.txt @@ -172,7 +172,8 @@ Performance, Internal Implementation, Development Support etc. incorrect patch text to "git apply". Add tests to demonstrate this. - I have a slight suspicion that this may be $gmane/87202 coming back + I have a slight suspicion that this may be + cf. <7vtzf77wjp.fsf@gitster.siamese.dyndns.org> coming back and biting us (I seem to have said "let's run with this and see what happens" back then). diff --git a/Documentation/RelNotes/2.7.0.txt b/Documentation/RelNotes/2.7.0.txt index 563dadc57e..e3cbf3a73c 100644 --- a/Documentation/RelNotes/2.7.0.txt +++ b/Documentation/RelNotes/2.7.0.txt @@ -40,7 +40,7 @@ UI, Workflows & Features * "git interpret-trailers" can now run outside of a Git repository. - * "git p4" learned to reencode the pathname it uses to communicate + * "git p4" learned to re-encode the pathname it uses to communicate with the p4 depot with a new option. * Give progress meter to "git filter-branch". diff --git a/Documentation/RelNotes/2.7.1.txt b/Documentation/RelNotes/2.7.1.txt index 6553d69e33..6323feaf64 100644 --- a/Documentation/RelNotes/2.7.1.txt +++ b/Documentation/RelNotes/2.7.1.txt @@ -10,7 +10,7 @@ Fixes since v2.7 setting GIT_WORK_TREE environment themselves. * The "exclude_list" structure has the usual "alloc, nr" pair of - fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot + fields to be used by ALLOC_GROW(), but clear_pattern_list() forgot to reset 'alloc' to 0 when it cleared 'nr' to discard the managed array. diff --git a/Documentation/RelNotes/2.7.3.txt b/Documentation/RelNotes/2.7.3.txt index 6adf038915..f618d71efd 100644 --- a/Documentation/RelNotes/2.7.3.txt +++ b/Documentation/RelNotes/2.7.3.txt @@ -20,7 +20,7 @@ Fixes since v2.7.2 tests. * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a - rev, i.e. the object named by the the pathname with wildcard + rev, i.e. the object named by the pathname with wildcard characters in a tree object. * "git rev-parse --git-common-dir" used in the worktree feature diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.txt index 25079710fa..27320b6a9f 100644 --- a/Documentation/RelNotes/2.8.0.txt +++ b/Documentation/RelNotes/2.8.0.txt @@ -189,7 +189,7 @@ Performance, Internal Implementation, Development Support etc. * Some calls to strcpy(3) triggers a false warning from static analyzers that are less intelligent than humans, and reducing the number of these false hits helps us notice real issues. A few - calls to strcpy(3) in a couple of protrams that are already safe + calls to strcpy(3) in a couple of programs that are already safe has been rewritten to avoid false warnings. * The "name_path" API was an attempt to reduce the need to construct @@ -270,7 +270,7 @@ notes for details). setting GIT_WORK_TREE environment themselves. * The "exclude_list" structure has the usual "alloc, nr" pair of - fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot + fields to be used by ALLOC_GROW(), but clear_pattern_list() forgot to reset 'alloc' to 0 when it cleared 'nr' to discard the managed array. diff --git a/Documentation/RelNotes/2.8.3.txt b/Documentation/RelNotes/2.8.3.txt index fedd9968e5..a63825ed87 100644 --- a/Documentation/RelNotes/2.8.3.txt +++ b/Documentation/RelNotes/2.8.3.txt @@ -55,8 +55,8 @@ Fixes since v2.8.2 This is necessary to use Git on Windows shared directories, and is already enabled for the MinGW and plain Windows builds. It also has been used in Cygwin packaged versions of Git for quite a while. - See http://thread.gmane.org/gmane.comp.version-control.git/291853 - and http://thread.gmane.org/gmane.comp.version-control.git/275680. + See https://lore.kernel.org/git/20160419091055.GF2345@dinwoodie.org/ + and https://lore.kernel.org/git/20150811100527.GW14466@dinwoodie.org/. * "git replace -e" did not honour "core.editor" configuration. diff --git a/Documentation/RelNotes/2.9.0.txt b/Documentation/RelNotes/2.9.0.txt index b61d36712f..991640119a 100644 --- a/Documentation/RelNotes/2.9.0.txt +++ b/Documentation/RelNotes/2.9.0.txt @@ -368,7 +368,7 @@ notes for details). This is necessary to use Git on Windows shared directories, and is already enabled for the MinGW and plain Windows builds. It also has been used in Cygwin packaged versions of Git for quite a while. - See http://thread.gmane.org/gmane.comp.version-control.git/291853 + See https://lore.kernel.org/git/20160419091055.GF2345@dinwoodie.org/ * "merge-octopus" strategy did not ensure that the index is clean when merge begins. diff --git a/Documentation/RelNotes/2.9.3.txt b/Documentation/RelNotes/2.9.3.txt index 695b86f612..305e08062b 100644 --- a/Documentation/RelNotes/2.9.3.txt +++ b/Documentation/RelNotes/2.9.3.txt @@ -36,7 +36,7 @@ Fixes since v2.9.2 * One part of "git am" had an oddball helper function that called stuff from outside "his" as opposed to calling what we have "ours", which was not gender-neutral and also inconsistent with the rest of - the system where outside stuff is usuall called "theirs" in + the system where outside stuff is usually called "theirs" in contrast to "ours". * The test framework learned a new helper test_match_signal to diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b44fd51f27..4515cab519 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -80,7 +80,9 @@ GitHub-Travis CI hints section for details. Do not forget to update the documentation to describe the updated behavior and make sure that the resulting documentation set formats -well. It is currently a liberal mixture of US and UK English norms for +well (try the Documentation/doc-diff script). + +We currently have a liberal mixture of US and UK English norms for spelling and grammar, which is somewhat unfortunate. A huge patch that touches the files all over the place only to correct the inconsistency is not welcome, though. Potential clashes with other changes that can @@ -140,19 +142,25 @@ 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 sha1 (subject, date)", -with the subject enclosed in a pair of double-quotes, like this: +branch, use the format "abbreviated hash (subject, date)", like this: .... - Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30) + 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 -format, or this invocation of `git show`: +format (with the subject enclosed in a pair of double-quotes), or this +invocation of `git show`: + +.... + git show -s --pretty=reference <commit> +.... + +or, on an older version of Git without support for --pretty=reference: .... - git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit> + git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> .... [[git-tools]] @@ -370,15 +378,15 @@ such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". Some parts of the system have dedicated maintainers with their own repositories. -- 'git-gui/' comes from git-gui project, maintained by Pat Thoyts: +- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav: - git://repo.or.cz/git-gui.git + https://github.com/prati0100/git-gui.git -- 'gitk-git/' comes from Paul Mackerras's gitk project: +- `gitk-git/` comes from Paul Mackerras's gitk project: git://ozlabs.org/~paulus/gitk -- 'po/' comes from the localization coordinator, Jiang Xin: +- `po/` comes from the localization coordinator, Jiang Xin: https://github.com/git-l10n/git-po/ diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 2c16c536ba..3e4c13971b 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -31,24 +31,6 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-docbook[] -ifndef::git-asciidoc-no-roff[] -# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. -# v1.72 breaks with this because it replaces dots not in roff requests. -[listingblock] -<example><title>{title}</title> -<literallayout class="monospaced"> -ifdef::doctype-manpage[] - .ft C -endif::doctype-manpage[] -| -ifdef::doctype-manpage[] - .ft -endif::doctype-manpage[] -</literallayout> -{title#}</example> -endif::git-asciidoc-no-roff[] - -ifdef::git-asciidoc-no-roff[] ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] @@ -67,7 +49,6 @@ ifdef::doctype-manpage[] {title#}</para></formalpara> {title%}<simpara></simpara> endif::doctype-manpage[] -endif::git-asciidoc-no-roff[] endif::backend-docbook[] ifdef::doctype-manpage[] @@ -78,9 +59,9 @@ template::[header-declarations] <refmeta> <refentrytitle>{mantitle}</refentrytitle> <manvolnum>{manvolnum}</manvolnum> -<refmiscinfo class="source">Git</refmiscinfo> -<refmiscinfo class="version">{git_version}</refmiscinfo> -<refmiscinfo class="manual">Git Manual</refmiscinfo> +<refmiscinfo class="source">{mansource}</refmiscinfo> +<refmiscinfo class="version">{manversion}</refmiscinfo> +<refmiscinfo class="manual">{manmanual}</refmiscinfo> </refmeta> <refnamediv> <refname>{manname}</refname> diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index ec83b4959e..d906a00803 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -9,20 +9,40 @@ module Git named :chrome def process(parent, target, attrs) - if parent.document.basebackend? 'html' - prefix = parent.document.attr('git-relative-html-prefix') - %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n) + prefix = parent.document.attr('git-relative-html-prefix') + if parent.document.doctype == 'book' + "<ulink url=\"#{prefix}#{target}.html\">" \ + "#{target}(#{attrs[1]})</ulink>" + elsif parent.document.basebackend? 'html' + %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) elsif parent.document.basebackend? 'docbook' "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>\n" + "</citerefentry>" end end end + + class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor + def process document, output + if document.basebackend? 'docbook' + mansource = document.attributes['mansource'] + manversion = document.attributes['manversion'] + manmanual = document.attributes['manmanual'] + new_tags = "" \ + "<refmiscinfo class=\"source\">#{mansource}</refmiscinfo>\n" \ + "<refmiscinfo class=\"version\">#{manversion}</refmiscinfo>\n" \ + "<refmiscinfo class=\"manual\">#{manmanual}</refmiscinfo>\n" + output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>") + end + output + end + end end end Asciidoctor::Extensions.register do inline_macro Git::Documentation::LinkGitProcessor, :linkgit + postprocessor Git::Documentation::DocumentPostProcessor end diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index dc41957afa..5d122db6e9 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -110,5 +110,24 @@ commit. And the default value is 40. If there are more than one `-C` options given, the <num> argument of the last `-C` will take effect. +--ignore-rev <rev>:: + Ignore changes made by the revision when assigning blame, as if the + change never happened. Lines that were changed or added by an ignored + commit will be blamed on the previous commit that changed that line or + nearby lines. This option may be specified multiple times to ignore + more than one revision. If the `blame.markIgnoredLines` config option + is set, then lines that were changed by an ignored commit and attributed to + another commit will be marked with a `?` in the blame output. If the + `blame.markUnblamableLines` config option is set, then those lines touched + by an ignored commit that we could not attribute to another revision are + marked with a '*'. + +--ignore-revs-file <file>:: + Ignore revisions listed in `file`, which must be in the same format as an + `fsck.skipList`. This option may be repeated, and these files will be + processed after any files specified with the `blame.ignoreRevsFile` config + option. An empty file name, `""`, will clear the list of revs from + previously processed files. + -h:: Show help message. diff --git a/Documentation/config.txt b/Documentation/config.txt index 8283443c97..ef0768b91a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2,11 +2,13 @@ CONFIGURATION FILE ------------------ The Git configuration file contains a number of variables that affect -the Git commands' behavior. The `.git/config` file in each repository -is used to store the configuration for that repository, and -`$HOME/.gitconfig` is used to store a per-user configuration as -fallback values for the `.git/config` file. The file `/etc/gitconfig` -can be used to store a system-wide default configuration. +the Git commands' behavior. The files `.git/config` and optionally +`config.worktree` (see the "CONFIGURATION FILE" section of +linkgit:git-worktree[1]) in each repository are used to store the +configuration for that repository, and `$HOME/.gitconfig` is used to +store a per-user configuration as fallback values for the `.git/config` +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 @@ -141,7 +143,21 @@ refer to linkgit:gitignore[5] for details. For convenience: `gitdir/i`:: This is the same as `gitdir` except that matching is done - case-insensitively (e.g. on case-insensitive file sytems) + case-insensitively (e.g. on case-insensitive file systems) + +`onbranch`:: + The data that follows the keyword `onbranch:` is taken to be a + pattern with standard globbing wildcards and two additional + ones, `**/` and `/**`, that can match multiple path components. + If we are in a worktree where the name of the branch that is + currently checked out matches the pattern, the include condition + is met. ++ +If the pattern ends with `/`, `**` will be automatically added. For +example, the pattern `foo/` becomes `foo/**`. In other words, it matches +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. A few more notes on matching via `gitdir` and `gitdir/i`: @@ -163,47 +179,54 @@ to either specify only the realpath version, or both versions. Example ~~~~~~~ - # Core variables - [core] - ; Don't trust file modes - filemode = false - - # Our diff algorithm - [diff] - external = /usr/local/bin/diff-wrapper - renames = true - - [branch "devel"] - remote = origin - merge = refs/heads/devel - - # Proxy settings - [core] - gitProxy="ssh" for "kernel.org" - gitProxy=default-proxy ; for the rest - - [include] - path = /path/to/foo.inc ; include by absolute path - path = foo.inc ; find "foo.inc" relative to the current file - path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory - - ; include if $GIT_DIR is /path/to/foo/.git - [includeIf "gitdir:/path/to/foo/.git"] - path = /path/to/foo.inc - - ; include for all repositories inside /path/to/group - [includeIf "gitdir:/path/to/group/"] - path = /path/to/foo.inc - - ; include for all repositories inside $HOME/to/group - [includeIf "gitdir:~/to/group/"] - path = /path/to/foo.inc - - ; relative paths are always relative to the including - ; file (if the condition is true); their location is not - ; affected by the condition - [includeIf "gitdir:/path/to/group/"] - path = foo.inc +---- +# Core variables +[core] + ; Don't trust file modes + filemode = false + +# Our diff algorithm +[diff] + external = /usr/local/bin/diff-wrapper + renames = true + +[branch "devel"] + remote = origin + merge = refs/heads/devel + +# Proxy settings +[core] + gitProxy="ssh" for "kernel.org" + gitProxy=default-proxy ; for the rest + +[include] + path = /path/to/foo.inc ; include by absolute path + path = foo.inc ; find "foo.inc" relative to the current file + path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory + +; include if $GIT_DIR is /path/to/foo/.git +[includeIf "gitdir:/path/to/foo/.git"] + path = /path/to/foo.inc + +; include for all repositories inside /path/to/group +[includeIf "gitdir:/path/to/group/"] + path = /path/to/foo.inc + +; include for all repositories inside $HOME/to/group +[includeIf "gitdir:~/to/group/"] + path = /path/to/foo.inc + +; relative paths are always relative to the including +; file (if the condition is true); their location is not +; affected by the condition +[includeIf "gitdir:/path/to/group/"] + path = foo.inc + +; include only if we are in a worktree where foo-branch is +; currently checked out +[includeIf "onbranch:foo-branch"] + path = foo.inc +---- Values ~~~~~~ @@ -225,7 +248,7 @@ boolean:: false;; Boolean false literals are `no`, `off`, `false`, `0` and the empty string. + -When converting value to the canonical form using `--bool` type +When converting a value to its canonical form using the `--type=bool` type specifier, 'git config' will ensure that the output is "true" or "false" (spelled in lowercase). @@ -241,7 +264,9 @@ color:: + 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. +foreground; the second is the background. All the basic colors except +`normal` have a bright variant that can be speficied by prefixing the +color with `bright`, like `brightred`. + 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 @@ -287,3466 +312,158 @@ 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[] -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': -+ --- - pushUpdateRejected:: - Set this variable to 'false' if you want to disable - 'pushNonFFCurrent', - 'pushNonFFMatching', 'pushAlreadyExists', - 'pushFetchFirst', and 'pushNeedsForce' - 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. - pushAlreadyExists:: - Shown when linkgit:git-push[1] rejects an update that - does not qualify for fast-forwarding (e.g., a tag.) - pushFetchFirst:: - Shown when linkgit:git-push[1] rejects an update that - tries to overwrite a remote ref that points at an - object we do not have. - pushNeedsForce:: - Shown when linkgit:git-push[1] rejects an update that - 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. - statusHints:: - Show directions on how to proceed from the current - state in the output of linkgit:git-status[1], in - the template shown when writing commit messages in - linkgit:git-commit[1], and in the help message shown - by linkgit:git-checkout[1] when switching branch. - 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. - resolveConflict:: - Advice shown by various commands when conflicts - prevent the operation from being performed. - 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-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] 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. --- - -core.fileMode:: - Tells Git if the executable bit of files in the working tree - is to be honored. -+ -Some filesystems lose the executable bit when a file that is -marked as executable is checked out, or checks out a -non-executable file with executable bit on. -linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem -to see if it handles the executable bit correctly -and this variable is automatically set as necessary. -+ -A repository, however, may be on a filesystem that handles -the filemode correctly, and this variable is set to 'true' -when created, but later may be made accessible from another -environment that loses the filemode (e.g. exporting ext4 via -CIFS mount, visiting a Cygwin created repository with -Git for Windows or Eclipse). -In such a case it may be necessary to set this variable to 'false'. -See linkgit:git-update-index[1]. -+ -The default is true (when core.filemode is not specified in the config file). - -core.hideDotFiles:: - (Windows-only) If true, mark newly-created directories and files whose - name starts with a dot as hidden. If 'dotGitOnly', only the `.git/` - directory is hidden, but no other files starting with a dot. The - default mode is 'dotGitOnly'. - -core.ignoreCase:: - Internal variable which enables various workarounds to enable - Git to work better on filesystems that are not case sensitive, - like APFS, HFS+, FAT, NTFS, etc. For example, if a directory listing - finds "makefile" when Git expects "Makefile", Git will assume - it is really the same file, and continue to remember it as - "Makefile". -+ -The default is false, except linkgit:git-clone[1] or linkgit:git-init[1] -will probe and set core.ignoreCase true if appropriate when the repository -is created. -+ -Git relies on the proper configuration of this variable for your operating -and file system. Modifying this value may result in unexpected behavior. - -core.precomposeUnicode:: - This option is only used by Mac OS implementation of Git. - When core.precomposeUnicode=true, Git reverts the unicode decomposition - of filenames done by Mac OS. This is useful when sharing a repository - between Mac OS and Linux or Windows. - (Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). - When false, file names are handled fully transparent by Git, - which is backward compatible with older versions of Git. - -core.protectHFS:: - If set to true, do not allow checkout of paths that would - be considered equivalent to `.git` on an HFS+ filesystem. - Defaults to `true` on Mac OS, and `false` elsewhere. - -core.protectNTFS:: - If set to true, do not allow checkout of paths that would - cause problems with the NTFS filesystem, e.g. conflict with - 8.3 "short" names. - 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]. - -core.trustctime:: - If false, the ctime differences between the index and the - working tree are ignored; useful when the inode change time - is regularly modified by something outside Git (file system - crawlers and some backup systems). - See linkgit:git-update-index[1]. True by default. - -core.splitIndex:: - If true, the split-index feature of the index will be used. - See linkgit:git-update-index[1]. False by default. - -core.untrackedCache:: - Determines what to do about the untracked cache feature of the - index. It will be kept, if this variable is unset or set to - `keep`. It will automatically be added if set to `true`. And - it will automatically be removed, if set to `false`. Before - setting it to `true`, you should check that mtime is working - properly on your system. - See linkgit:git-update-index[1]. `keep` by default. - -core.checkStat:: - Determines which stat fields to match between the index - and work tree. The user can set this to 'default' or - 'minimal'. Default (or explicitly 'default'), is to check - all fields, including the sub-second part of mtime and ctime. - -core.quotePath:: - Commands that output paths (e.g. 'ls-files', 'diff'), will - quote "unusual" characters in the pathname by enclosing the - pathname in double-quotes and escaping those characters with - backslashes in the same way C escapes control characters (e.g. - `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with - values larger than 0x80 (e.g. octal `\302\265` for "micro" in - UTF-8). If this variable is set to false, bytes higher than - 0x80 are not considered "unusual" any more. Double-quotes, - backslash and control characters are always escaped regardless - of the setting of this variable. A simple space character is - not considered "unusual". Many commands can output pathnames - completely verbatim using the `-z` option. The default value - is true. - -core.eol:: - Sets the line ending type to use in the working directory for - files that have the `text` property set when core.autocrlf is false. - Alternatives are 'lf', 'crlf' and 'native', which uses the platform's - native line ending. The default value is `native`. See - linkgit:gitattributes[5] for more information on end-of-line - conversion. - -core.safecrlf:: - If true, makes Git check if converting `CRLF` is reversible when - end-of-line conversion is active. Git will verify if a command - modifies a file in the work tree either directly or indirectly. - For example, committing a file followed by checking out the - same file should yield the original file in the work tree. If - this is not the case for the current setting of - `core.autocrlf`, Git will reject the file. The variable can - be set to "warn", in which case Git will only warn about an - irreversible conversion but continue the operation. -+ -CRLF conversion bears a slight chance of corrupting data. -When it is enabled, Git will convert CRLF to LF during commit and LF to -CRLF during checkout. A file that contains a mixture of LF and -CRLF before the commit cannot be recreated by Git. For text -files this is the right thing to do: it corrects line endings -such that we have only LF line endings in the repository. -But for binary files that are accidentally classified as text the -conversion can corrupt data. -+ -If you recognize such corruption early you can easily fix it by -setting the conversion type explicitly in .gitattributes. Right -after committing you still have the original file in your work -tree and this file is not yet corrupted. You can explicitly tell -Git that this file is binary and Git will handle the file -appropriately. -+ -Unfortunately, the desired effect of cleaning up text files with -mixed line endings and the undesired effect of corrupting binary -files cannot be distinguished. In both cases CRLFs are removed -in an irreversible way. For text files this is the right thing -to do because CRLFs are line endings, while for binary files -converting CRLFs corrupts data. -+ -Note, this safety check does not mean that a checkout will generate a -file identical to the original file for a different setting of -`core.eol` and `core.autocrlf`, but only for the current one. For -example, a text file with `LF` would be accepted with `core.eol=lf` -and could later be checked out with `core.eol=crlf`, in which case the -resulting file would contain `CRLF`, although the original file -contained `LF`. However, in both work trees the line endings would be -consistent, that is either all `LF` or all `CRLF`, but never mixed. A -file with mixed line endings would be reported by the `core.safecrlf` -mechanism. - -core.autocrlf:: - Setting this variable to "true" is the same as setting - the `text` attribute to "auto" on all files and core.eol to "crlf". - Set to true if you want to have `CRLF` line endings in your - working directory and the repository has LF line endings. - This variable can be set to 'input', - in which case no output conversion is performed. - -core.checkRoundtripEncoding:: - A comma and/or whitespace separated list of encodings that Git - performs UTF-8 round trip checks on if they are used in an - `working-tree-encoding` attribute (see linkgit:gitattributes[5]). - The default value is `SHIFT-JIS`. - -core.symlinks:: - If false, symbolic links are checked out as small plain files that - contain the link text. linkgit:git-update-index[1] and - linkgit:git-add[1] will not change the recorded type to regular - file. Useful on filesystems like FAT that do not support - symbolic links. -+ -The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] -will probe and set core.symlinks false if appropriate when the repository -is created. - -core.gitProxy:: - A "proxy command" to execute (as 'command host port') instead - of establishing direct connection to the remote server when - using the Git protocol for fetching. If the variable value is - in the "COMMAND for DOMAIN" format, the command is applied only - on hostnames ending with the specified domain string. This variable - may be set multiple times and is matched in the given order; - the first match wins. -+ -Can be overridden by the `GIT_PROXY_COMMAND` environment variable -(which always applies universally, without the special "for" -handling). -+ -The special string `none` can be used as the proxy command to -specify that no proxy be used for a given domain pattern. -This is useful for excluding servers inside a firewall from -proxy use, while defaulting to a common proxy for external domains. - -core.sshCommand:: - If this variable is set, `git fetch` and `git push` will - use the specified command instead of `ssh` when they need to - connect to a remote system. The command is in the same form as - the `GIT_SSH_COMMAND` environment variable and is overridden - when the environment variable is set. - -core.ignoreStat:: - If true, Git will avoid using lstat() calls to detect if files have - changed by setting the "assume-unchanged" bit for those tracked files - which it has updated identically in both the index and working tree. -+ -When files are modified outside of Git, the user will need to stage -the modified files explicitly (e.g. see 'Examples' section in -linkgit:git-update-index[1]). -Git will not normally detect changes to those files. -+ -This is useful on systems where lstat() calls are very slow, such as -CIFS/Microsoft Windows. -+ -False by default. - -core.preferSymlinkRefs:: - Instead of the default "symref" format for HEAD - and other symbolic reference files, use symbolic links. - This is sometimes needed to work with old scripts that - expect HEAD to be a symbolic link. - -core.bare:: - If true this repository is assumed to be 'bare' and has no - working directory associated with it. If this is the case a - number of commands that require a working directory will be - disabled, such as linkgit:git-add[1] or linkgit:git-merge[1]. -+ -This setting is automatically guessed by linkgit:git-clone[1] or -linkgit:git-init[1] when the repository was created. By default a -repository that ends in "/.git" is assumed to be not bare (bare = -false), while all other repositories are assumed to be bare (bare -= true). - -core.worktree:: - Set the path to the root of the working tree. - If `GIT_COMMON_DIR` environment variable is set, core.worktree - is ignored and not used for determining the root of working tree. - This can be overridden by the `GIT_WORK_TREE` environment - variable and the `--work-tree` command-line option. - The value can be an absolute path or relative to the path to - the .git directory, which is either specified by --git-dir - or GIT_DIR, or automatically discovered. - If --git-dir or GIT_DIR is specified but none of - --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the top level - of your working tree. -+ -Note that this variable is honored even when set in a configuration -file in a ".git" subdirectory of a directory and its value differs -from the latter directory (e.g. "/path/to/.git/config" has -core.worktree set to "/different/path"), which is most likely a -misconfiguration. Running Git commands in the "/path/to" directory will -still use "/different/path" as the root of the work tree and can cause -confusion unless you know what you are doing (e.g. you are creating a -read-only snapshot of the same index to a location different from the -repository's usual working tree). - -core.logAllRefUpdates:: - Enable the reflog. Updates to a ref <ref> is logged to the file - "`$GIT_DIR/logs/<ref>`", by appending the new and old - SHA-1, the date/time and the reason of the update, but - only when the file exists. If this configuration - variable is set to `true`, missing "`$GIT_DIR/logs/<ref>`" - file is automatically created for branch heads (i.e. under - `refs/heads/`), remote refs (i.e. under `refs/remotes/`), - note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`. - If it is set to `always`, then a missing reflog is automatically - created for any ref under `refs/`. -+ -This information can be used to determine what commit -was the tip of a branch "2 days ago". -+ -This value is true by default in a repository that has -a working directory associated with it, and false by -default in a bare repository. - -core.repositoryFormatVersion:: - Internal variable identifying the repository format and layout - version. - -core.sharedRepository:: - When 'group' (or 'true'), the repository is made shareable between - several users in a group (making sure all the files and objects are - group-writable). When 'all' (or 'world' or 'everybody'), the - repository will be readable by all users, additionally to being - group-shareable. When 'umask' (or 'false'), Git will use permissions - reported by umask(2). When '0xxx', where '0xxx' is an octal number, - files in the repository will have this mode value. '0xxx' will override - user's umask value (whereas the other options will only override - requested parts of the user's umask value). Examples: '0660' will make - the repo read/write-able for the owner and group, but inaccessible to - others (equivalent to 'group' unless umask is e.g. '0022'). '0640' is a - repository that is group-readable but not group-writable. - See linkgit:git-init[1]. False by default. - -core.warnAmbiguousRefs:: - If true, Git will warn you if the ref name you passed it is ambiguous - and might match multiple refs in the repository. True by default. - -core.compression:: - An integer -1..9, indicating a default compression level. - -1 is the zlib default. 0 means no compression, - and 1..9 are various speed/size tradeoffs, 9 being slowest. - If set, this provides a default to other compression variables, - such as `core.looseCompression` and `pack.compression`. - -core.looseCompression:: - An integer -1..9, indicating the compression level for objects that - are not in a pack file. -1 is the zlib default. 0 means no - compression, and 1..9 are various speed/size tradeoffs, 9 being - slowest. If not set, defaults to core.compression. If that is - not set, defaults to 1 (best speed). - -core.packedGitWindowSize:: - Number of bytes of a pack file to map into memory in a - single mapping operation. Larger window sizes may allow - your system to process a smaller number of large pack files - more quickly. Smaller window sizes will negatively affect - performance due to increased calls to the operating system's - memory manager, but may improve performance when accessing - a large number of large pack files. -+ -Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 -MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should -be reasonable for all users/operating systems. You probably do -not need to adjust this value. -+ -Common unit suffixes of 'k', 'm', or 'g' are supported. +include::config/core.txt[] -core.packedGitLimit:: - Maximum number of bytes to map simultaneously into memory - from pack files. If Git needs to access more than this many - bytes at once to complete an operation it will unmap existing - regions to reclaim virtual address space within the process. -+ -Default is 256 MiB on 32 bit platforms and 32 TiB (effectively -unlimited) on 64 bit platforms. -This should be reasonable for all users/operating systems, except on -the largest projects. You probably do not need to adjust this value. -+ -Common unit suffixes of 'k', 'm', or 'g' are supported. - -core.deltaBaseCacheLimit:: - Maximum number of bytes to reserve for caching base objects - that may be referenced by multiple deltified objects. By storing the - entire decompressed base objects in a cache Git is able - to avoid unpacking and decompressing frequently used base - objects multiple times. -+ -Default is 96 MiB on all platforms. This should be reasonable -for all users/operating systems, except on the largest projects. -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. -+ -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. -+ -Common unit suffixes of 'k', 'm', or 'g' are supported. - -core.excludesFile:: - Specifies the pathname to the file that contains patterns to - describe paths that are not meant to be tracked, in addition - to '.gitignore' (per-directory) and '.git/info/exclude'. - Defaults to `$XDG_CONFIG_HOME/git/ignore`. - If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` - is used instead. See linkgit:gitignore[5]. - -core.askPass:: - Some commands (e.g. svn and http interfaces) that interactively - ask for a password can be told to use an external program given - via the value of this variable. Can be overridden by the `GIT_ASKPASS` - environment variable. If not set, fall back to the value of the - `SSH_ASKPASS` environment variable or, failing that, a simple password - prompt. The external program shall be given a suitable prompt as - command-line argument and write the password on its STDOUT. - -core.attributesFile:: - In addition to '.gitattributes' (per-directory) and - '.git/info/attributes', Git looks into this file for attributes - (see linkgit:gitattributes[5]). Path expansions are made the same - way as for `core.excludesFile`. Its default value is - `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not - set or empty, `$HOME/.config/git/attributes` is used instead. - -core.hooksPath:: - By default Git will look for your hooks in the - '$GIT_DIR/hooks' directory. Set this to different path, - e.g. '/etc/git/hooks', and Git will try to find your hooks in - that directory, e.g. '/etc/git/hooks/pre-receive' instead of - in '$GIT_DIR/hooks/pre-receive'. -+ -The path can be either absolute or relative. A relative path is -taken as relative to the directory where the hooks are run (see -the "DESCRIPTION" section of linkgit:githooks[5]). -+ -This configuration variable is useful in cases where you'd like to -centrally configure your Git hooks instead of configuring them on a -per-repository basis, or as a more flexible and centralized -alternative to having an `init.templateDir` where you've changed -default hooks. - -core.editor:: - Commands such as `commit` and `tag` that let you edit - messages by launching an editor use the value of this - variable when it is set, and the environment variable - `GIT_EDITOR` is not set. See linkgit:git-var[1]. - -core.commentChar:: - 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 - (default '#'). -+ -If set to "auto", `git-commit` would select a character that is not -the beginning character of any line in existing commit messages. - -core.filesRefLockTimeout:: - The length of time, in milliseconds, to retry when trying to - lock an individual reference. Value 0 means not to retry at - all; -1 means to try indefinitely. Default is 100 (i.e., - retry for 100ms). - -core.packedRefsTimeout:: - The length of time, in milliseconds, to retry when trying to - lock the `packed-refs` file. Value 0 means not to retry at - all; -1 means to try indefinitely. Default is 1000 (i.e., - retry for 1 second). - -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. - -core.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 - is the `$GIT_PAGER` environment variable, then `core.pager` - configuration, then `$PAGER`, and then the default chosen at - compile time (usually 'less'). -+ -When the `LESS` environment variable is unset, Git sets it to `FRX` -(if `LESS` environment variable is set, Git does not change it at -all). If you want to selectively override Git's default setting -for `LESS`, you can set `core.pager` to e.g. `less -S`. This will -be passed to the shell by Git, which will translate the final -command to `LESS=FRX less -S`. The environment does not set the -`S` option but the command line does, instructing less to truncate -long lines. Similarly, setting `core.pager` to `less -+F` will -deactivate the `F` option specified by the environment from the -command-line, deactivating the "quit if one screen" behavior of -`less`. One can specifically activate some flags for particular -commands: for example, setting `pager.blame` to `less -S` enables -line truncation only for `git blame`. -+ -Likewise, when the `LV` environment variable is unset, Git sets it -to `-c`. You can override this setting by exporting `LV` with -another value or setting `core.pager` to `lv +c`. - -core.whitespace:: - A comma separated list of common whitespace problems to - notice. 'git diff' will use `color.diff.whitespace` to - highlight them, and 'git apply --whitespace=error' will - consider them as errors. You can prefix `-` to disable - any of them (e.g. `-trailing-space`): -+ -* `blank-at-eol` treats trailing whitespaces at the end of the line - as an error (enabled by default). -* `space-before-tab` treats a space character that appears immediately - before a tab character in the initial indent part of the line as an - error (enabled by default). -* `indent-with-non-tab` treats a line that is indented with space - characters instead of the equivalent tabs as an error (not enabled by - default). -* `tab-in-indent` treats a tab character in the initial indent part of - the line as an error (not enabled by default). -* `blank-at-eof` treats blank lines added at the end of file as an error - (enabled by default). -* `trailing-space` is a short-hand to cover both `blank-at-eol` and - `blank-at-eof`. -* `cr-at-eol` treats a carriage-return at the end of line as - part of the line terminator, i.e. with it, `trailing-space` - does not trigger if the character before such a carriage-return - is not a whitespace (not enabled by default). -* `tabwidth=<n>` tells how many character positions a tab occupies; this - 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.fsyncObjectFiles:: - This boolean will enable 'fsync()' when writing object files. -+ -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"). +include::config/add.txt[] -core.preloadIndex:: - Enable parallel index preload for operations like 'git diff' -+ -This can speed up operations like 'git diff' and 'git status' especially -on filesystems like NFS that have weak caching semantics and thus -relatively high IO latencies. When enabled, Git will do the -index comparison to the filesystem data in parallel, allowing -overlapping IO's. Defaults to true. - -core.createObject:: - You can set this to 'link', in which case a hardlink followed by - a delete of the source are used to make sure that object creation - 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 -check that makes sure that existing object files will not get overwritten. - -core.notesRef:: - When showing commit messages, also show notes which are stored in - the given ref. The ref must be fully qualified. If the given - ref does not exist, it is not an error but means that no - notes should be printed. -+ -This setting defaults to "refs/notes/commits", and it can be overridden by -the `GIT_NOTES_REF` environment variable. See linkgit:git-notes[1]. - -gc.commitGraph:: - If true, then gc will rewrite the commit-graph file when - linkgit:git-gc[1] is run. When using linkgit:git-gc[1] - '--auto' the commit-graph will be updated if housekeeping is - required. Default is false. See linkgit:git-commit-graph[1] - for details. - -core.useReplaceRefs:: - If set to `false`, behave as if the `--no-replace-objects` - option was given on the command line. See linkgit:git[1] and - linkgit:git-replace[1] for more information. - -core.multiPackIndex:: - Use the multi-pack-index file to track multiple packfiles using a - single index. See link:technical/multi-pack-index.html[the - multi-pack-index design document]. - -core.sparseCheckout:: - Enable "sparse checkout" feature. See section "Sparse checkout" in - linkgit:git-read-tree[1] for more information. - -core.abbrev:: - Set the length object names are abbreviated to. If - unspecified or set to "auto", an appropriate value is - computed based on the approximate number of packed objects - in your repository, which hopefully is enough for - abbreviated object names to stay unique for some time. - The minimum length is 4. - -add.ignoreErrors:: -add.ignore-errors (deprecated):: - Tells 'git add' to continue adding files when some files cannot be - added due to indexing errors. Equivalent to the `--ignore-errors` - option of linkgit:git-add[1]. `add.ignore-errors` is deprecated, - as it does not follow the usual naming convention for configuration - variables. - -alias.*:: - Command aliases for the linkgit:git[1] command wrapper - e.g. - after defining "alias.last = cat-file commit HEAD", the invocation - "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. - A quote pair or a backslash can be used to quote them. -+ -If the alias expansion is prefixed with an exclamation point, -it will be treated as a shell command. For example, defining -"alias.new = !gitk --all --not ORIG_HEAD", the invocation -"git new" is equivalent to running the shell command -"gitk --all --not ORIG_HEAD". Note that shell commands will be -executed from the top-level directory of a repository, which may -not necessarily be the current directory. -`GIT_PREFIX` is set as returned by running 'git rev-parse --show-prefix' -from the original current directory. See linkgit:git-rev-parse[1]. - -am.keepcr:: - If true, git-am will call git-mailsplit for patches in mbox format - with parameter `--keep-cr`. In this case git-mailsplit will - not remove `\r` from lines ending with `\r\n`. Can be overridden - by giving `--no-keep-cr` from the command line. - See linkgit:git-am[1], linkgit:git-mailsplit[1]. - -am.threeWay:: - By default, `git am` will fail if the patch does not apply cleanly. When - set to true, this setting tells `git am` to fall back on 3-way merge if - the patch records the identity of blobs it is supposed to apply to and - we have those blobs available locally (equivalent to giving the `--3way` - option from the command line). Defaults to `false`. - See linkgit:git-am[1]. - -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 - respect all whitespace differences. - See linkgit:git-apply[1]. - -apply.whitespace:: - Tells 'git apply' how to handle whitespaces, in the same way - as the `--whitespace` option. See linkgit:git-apply[1]. - -blame.blankBoundary:: - Show blank commit object name for boundary commits in - linkgit:git-blame[1]. This option defaults to false. - -blame.coloring:: - This determines the coloring scheme to be applied to blame - output. It can be 'repeatedLines', 'highlightRecent', - or 'none' which is the default. - -blame.date:: - Specifies the format used to output dates in linkgit:git-blame[1]. - If unset the iso format is used. For supported values, - see the discussion of the `--date` option at linkgit:git-log[1]. - -blame.showEmail:: - Show the author email instead of author name in linkgit:git-blame[1]. - This option defaults to false. - -blame.showRoot:: - Do not treat root commits as boundaries in linkgit:git-blame[1]. - This option defaults to false. - -branch.autoSetupMerge:: - Tells 'git branch' and 'git checkout' to set up new branches - so that linkgit:git-pull[1] will appropriately merge from the - starting point branch. Note that even if this option is not set, - this behavior can be chosen per-branch using the `--track` - and `--no-track` options. The valid settings are: `false` -- no - 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. - -branch.autoSetupRebase:: - When a new branch is created with 'git branch' or 'git checkout' - that tracks another branch, this variable tells Git to set - up pull to rebase instead of merge (see "branch.<name>.rebase"). - When `never`, rebase is never automatically set to true. - When `local`, rebase is set to true for tracked branches of - other local branches. - When `remote`, rebase is set to true for tracked branches of - remote-tracking branches. - When `always`, rebase will be set to true for all tracking - branches. - See "branch.autoSetupMerge" for details on how to set up a - branch to track another branch. - This option defaults to never. - -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 - 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. - Additionally, `.` (a period) is the current local repository - (a dot-repository), see `branch.<name>.merge`'s final note below. - -branch.<name>.pushRemote:: - When on branch <name>, it overrides `branch.<name>.remote` for - pushing. It also overrides `remote.pushDefault` for pushing - from branch <name>. When you pull from one place (e.g. your - upstream) and push to another place (e.g. your own publishing - repository), you would want to set `remote.pushDefault` to - specify the remote to push to for all branches, and use this - option to override it for a specific branch. - -branch.<name>.merge:: - Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which - branch to merge and can also affect 'git push' (see push.default). - When in branch <name>, it tells 'git fetch' the default - refspec to be marked for merging in FETCH_HEAD. The value is - 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 - '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. - If you wish to setup 'git pull' so that it merges into <name> from - another branch in the local repository, you can point - branch.<name>.merge to the desired branch, and use the relative path - setting `.` (a period) for branch.<name>.remote. - -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and - supported options are the same as those of linkgit:git-merge[1], but - option values containing whitespace characters are currently not - supported. - -branch.<name>.rebase:: - When true, rebase the branch <name> on top of the fetched branch, - instead of merging the default branch from the default remote when - "git pull" is run. See "pull.rebase" for doing this in a non - branch-specific manner. -+ -When `merges`, 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, 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`, the rebase is run in interactive mode. -+ -*NOTE*: this is a possibly dangerous operation; do *not* use -it unless you understand the implications (see linkgit:git-rebase[1] -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 - request-pull summary. - -browser.<tool>.cmd:: - Specify the command to invoke the specified browser. The - specified command is evaluated in shell with the URLs passed - as arguments. (See linkgit:git-web{litdd}browse[1].) - -browser.<tool>.path:: - Override the path for the given tool that may be used to - browse HTML help (see `-w` option in linkgit:git-help[1]) or a - working repository in gitweb (see linkgit:git-instaweb[1]). - -checkout.defaultRemote:: - When you run 'git checkout <something>' and only have one - remote, it may implicitly fall back on checking out and - tracking e.g. 'origin/<something>'. This stops working as soon - as you have more than one remote with a '<something>' - reference. This setting allows for setting the name of a - preferred remote that should always win when it comes to - disambiguation. The typical use-case is to set this to - `origin`. -+ -Currently this is used by linkgit:git-checkout[1] when 'git checkout -<something>' will checkout the '<something>' branch on another remote, -and by linkgit:git-worktree[1] when 'git worktree add' refers to a -remote branch. This setting might be used for other checkout-like -commands or functionality in the future. - -clean.requireForce:: - A boolean to make git-clean do nothing unless given -f, - -i or -n. Defaults to true. - -color.advice:: - A boolean to enable/disable color in hints (e.g. when a push - failed, see `advice.*` for a list). May be set to `always`, - `false` (or `never`) or `auto` (or `true`), in which case colors - are used only when the error output goes to a terminal. If - unset, then the value of `color.ui` is used (`auto` by default). - -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. -+ -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 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. -+ -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. - -color.branch:: - A boolean to enable/disable color in the output of - linkgit:git-branch[1]. May be set to `always`, - `false` (or `never`) or `auto` (or `true`), in which case colors are used - only when the output is to a terminal. If unset, then the - value of `color.ui` is used (`auto` by default). - -color.branch.<slot>:: - Use customized color for branch coloration. `<slot>` is one of - `current` (the current branch), `local` (a local branch), - `remote` (a remote-tracking branch in refs/remotes/), - `upstream` (upstream tracking branch), `plain` (other - refs). - -color.diff:: - Whether to use ANSI escape sequences to add color to patches. - If this is set to `always`, linkgit:git-diff[1], - linkgit:git-log[1], and linkgit:git-show[1] will use color - for all patches. If it is set to `true` or `auto`, those - commands will only use color when output is to the terminal. - If unset, then the value of `color.ui` is used (`auto` by - default). -+ -This does not affect linkgit:git-format-patch[1] or the -'git-diff-{asterisk}' plumbing commands. Can be overridden on the -command line with the `--color[=<when>]` option. - -diff.colorMoved:: - If set to either a valid `<mode>` or a true value, moved lines - in a diff are colored differently, for details of valid modes - see '--color-moved' in linkgit:git-diff[1]. If simply set to - true the default color mode will be used. When set to false, - moved lines are not colored. - -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]. - -color.diff.<slot>:: - Use customized color for diff colorization. `<slot>` specifies - which part of the patch to use the specified color, and is one - of `context` (context text - `plain` is a historical synonym), - `meta` (metainformation), `frag` - (hunk header), 'func' (function in hunk header), `old` (removed lines), - `new` (added lines), `commit` (commit headers), `whitespace` - (highlighting whitespace errors), `oldMoved` (deleted lines), - `newMoved` (added lines), `oldMovedDimmed`, `oldMovedAlternative`, - `oldMovedAlternativeDimmed`, `newMovedDimmed`, `newMovedAlternative` - `newMovedAlternativeDimmed` (See the '<mode>' - setting of '--color-moved' in linkgit:git-diff[1] for details), - `contextDimmed`, `oldDimmed`, `newDimmed`, `contextBold`, - `oldBold`, and `newBold` (see linkgit:git-range-diff[1] for details). - -color.decorate.<slot>:: - Use customized color for 'git log --decorate' output. `<slot>` is one - of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local - branches, remote-tracking branches, tags, stash and HEAD, respectively - and `grafted` for grafted commits. - -color.grep:: - When set to `always`, always highlight matches. When `false` (or - `never`), never. When set to `true` or `auto`, use color only - when the output is written to the terminal. If unset, then the - value of `color.ui` is used (`auto` by default). - -color.grep.<slot>:: - Use customized color for grep colorization. `<slot>` specifies which - part of the line to use the specified color, and is one of -+ --- -`context`;; - non-matching text in context lines (when using `-A`, `-B`, or `-C`) -`filename`;; - filename prefix (when not using `-h`) -`function`;; - function name lines (when using `-p`) -`lineNumber`;; - line number prefix (when using `-n`) -`column`;; - column number prefix (when using `--column`) -`match`;; - matching text (same as setting `matchContext` and `matchSelected`) -`matchContext`;; - matching text in context lines -`matchSelected`;; - matching text in selected lines -`selected`;; - non-matching text in selected lines -`separator`;; - separators between fields on a line (`:`, `-`, and `=`) - and between hunks (`--`) --- - -color.interactive:: - When set to `always`, always use colors for interactive prompts - and displays (such as those used by "git-add --interactive" and - "git-clean --interactive"). When false (or `never`), never. - When set to `true` or `auto`, use colors only when the output is - to the terminal. If unset, then the value of `color.ui` is - used (`auto` by default). - -color.interactive.<slot>:: - Use customized color for 'git add --interactive' and 'git clean - --interactive' output. `<slot>` may be `prompt`, `header`, `help` - or `error`, for four distinct types of normal output from - interactive commands. - -color.pager:: - A boolean to enable/disable colored output when the pager is in - use (default is true). - -color.push:: - A boolean to enable/disable color in push errors. May be set to - `always`, `false` (or `never`) or `auto` (or `true`), in which - case colors are used only when the error output goes to a terminal. - If unset, then the value of `color.ui` is used (`auto` by default). - -color.push.error:: - Use customized color for push errors. - -color.remote:: - If set, keywords at the start of the line are highlighted. The - keywords are "error", "warning", "hint" and "success", and are - matched case-insensitively. May be set to `always`, `false` (or - `never`) or `auto` (or `true`). If unset, then the value of - `color.ui` is used (`auto` by default). - -color.remote.<slot>:: - Use customized color for each remote keyword. `<slot>` may be - `hint`, `warning`, `success` or `error` which match the - corresponding keyword. - -color.showBranch:: - A boolean to enable/disable color in the output of - linkgit:git-show-branch[1]. May be set to `always`, - `false` (or `never`) or `auto` (or `true`), in which case colors are used - only when the output is to a terminal. If unset, then the - value of `color.ui` is used (`auto` by default). - -color.status:: - A boolean to enable/disable color in the output of - linkgit:git-status[1]. May be set to `always`, - `false` (or `never`) or `auto` (or `true`), in which case colors are used - only when the output is to a terminal. If unset, then the - value of `color.ui` is used (`auto` by default). - -color.status.<slot>:: - Use customized color for status colorization. `<slot>` is - one of `header` (the header text of the status message), - `added` or `updated` (files which are added but not committed), - `changed` (files which are changed but not added in the index), - `untracked` (files which are not tracked by Git), - `branch` (the current branch), - `nobranch` (the color the 'no branch' warning is shown in, defaulting - to red), - `localBranch` or `remoteBranch` (the local and remote branch names, - respectively, when branch and tracking information is displayed in the - status short-format), or - `unmerged` (files which have unmerged changes). - -color.transport:: - A boolean to enable/disable color when pushes are rejected. May be - set to `always`, `false` (or `never`) or `auto` (or `true`), in which - case colors are used only when the error output goes to a terminal. - If unset, then the value of `color.ui` is used (`auto` by default). - -color.transport.rejected:: - Use customized color when a push was rejected. - -color.ui:: - This variable determines the default value for variables such - as `color.diff` and `color.grep` that control the use of color - per command family. Its scope will expand as more commands learn - configuration to set a default for the `--color` option. Set it - to `false` or `never` if you prefer Git commands not to use - color unless enabled explicitly with some other configuration - or the `--color` option. Set it to `always` if you want all - output not intended for machine consumption to use color, to - `true` or `auto` (this is the default since Git 1.8.4) if you - want such output to use color when written to the terminal. - -column.ui:: - Specify whether supported commands should output in columns. - This variable consists of a list of tokens separated by spaces - or commas: -+ -These options control when the feature should be enabled -(defaults to 'never'): -+ --- -`always`;; - always show in columns -`never`;; - never show in columns -`auto`;; - show in columns if the output is to the terminal --- -+ -These options control layout (defaults to 'column'). Setting any -of these implies 'always' if none of 'always', 'never', or 'auto' are -specified. -+ --- -`column`;; - fill columns before rows -`row`;; - fill rows before columns -`plain`;; - show in one column --- -+ -Finally, these options can be combined with a layout option (defaults -to 'nodense'): -+ --- -`dense`;; - make unequal size columns to utilize more space -`nodense`;; - make equal size columns --- - -column.branch:: - Specify whether to output branch listing in `git branch` in columns. - See `column.ui` for details. - -column.clean:: - Specify the layout when list items in `git clean -i`, which always - shows files and directories in columns. See `column.ui` for details. - -column.status:: - Specify whether to output untracked files in `git status` in columns. - See `column.ui` for details. - -column.tag:: - Specify whether to output tag listing in `git tag` in columns. - See `column.ui` for details. - -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 - 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). - -commit.gpgSign:: - - A boolean to specify whether all commits should be GPG signed. - Use of this option when doing operations such as rebase can - result in a large number of commits being signed. It may be - convenient to use an agent to avoid typing your GPG passphrase - several times. - -commit.status:: - A boolean to enable/disable inclusion of status information in the - commit message template when using an editor to prepare the commit - message. Defaults to true. - -commit.template:: - Specify the pathname of a file to use as the template for - new commit messages. - -commit.verbose:: - A boolean or int to specify the level of verbose with `git commit`. - See linkgit:git-commit[1]. - -credential.helper:: - Specify an external helper to be called when a username or - password credential is needed; the helper may consult external - storage to avoid prompting the user for the credentials. Note - that multiple helpers may be defined. See linkgit:gitcredentials[7] - for details. - -credential.useHttpPath:: - When acquiring credentials, consider the "path" component of an http - or https URL to be important. Defaults to false. See - linkgit:gitcredentials[7] for more information. - -credential.username:: - If no username is set for a network authentication, use this username - by default. See credential.<context>.* below, and - linkgit:gitcredentials[7]. - -credential.<url>.*:: - Any of the credential.* options above can be applied selectively to - 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. - -credentialCache.ignoreSIGHUP:: - Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting. - -completion.commands:: - This is only used by git-completion.bash to add or remove - commands from the list of completed commands. Normally only - porcelain commands and a few select others are completed. You - can add more commands, separated by space, in this - variable. Prefixing the command with '-' will remove it from - the existing list. - -include::diff-config.txt[] - -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. - The specified command is evaluated in shell with the following - variables available: 'LOCAL' is set to the name of the temporary - 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. - -difftool.prompt:: - Prompt before each invocation of the diff tool. - -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 - 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. - -fetch.recurseSubmodules:: - This option can be either set to a boolean value or to 'on-demand'. - Setting it to a boolean changes the behavior of fetch and pull to - unconditionally recurse into submodules when set to true or to not - recurse at all when set to false. When set to 'on-demand' (the default - value), fetch and pull will only recurse into a populated submodule - when its superproject retrieves a commit that updates the submodule's - reference. - -fetch.fsckObjects:: - If it is set to true, git-fetch-pack will check all fetched - objects. See `transfer.fsckObjects` for what's - checked. Defaults to false. If not set, the value of - `transfer.fsckObjects` is used instead. - -fetch.fsck.<msg-id>:: - Acts like `fsck.<msg-id>`, but is used by - linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See - the `fsck.<msg-id>` documentation for details. - -fetch.fsck.skipList:: - Acts like `fsck.skipList`, but is used by - linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See - the `fsck.skipList` documentation for details. - -fetch.unpackLimit:: - If the number of objects fetched over the Git native - transfer is below this - limit, then the objects will be unpacked into loose object - files. However if the number of received objects equals or - exceeds this limit then the received pack will be stored as - a pack, after adding any missing delta bases. Storing the - pack from a push can make the push operation complete faster, - especially on slow filesystems. If not set, the value of - `transfer.unpackLimit` is used instead. - -fetch.prune:: - If true, fetch will automatically behave as if the `--prune` - option was given on the command line. See also `remote.<name>.prune` - and the PRUNING section of linkgit:git-fetch[1]. - -fetch.pruneTags:: - If true, fetch will automatically behave as if the - `refs/tags/*:refs/tags/*` refspec was provided when pruning, - if not set already. This allows for setting both this option - and `fetch.prune` to maintain a 1=1 mapping to upstream - refs. See also `remote.<name>.pruneTags` and the PRUNING - section of linkgit:git-fetch[1]. - -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. - -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; 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). - Unknown values will cause 'git fetch' to error out. -+ -See also the `--negotiation-tip` option for linkgit:git-fetch[1]. - -format.attach:: - Enable multipart/mixed attachments as the default for - '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]. - -format.from:: - Provides the default value for the `--from` option to format-patch. - Accepts a boolean value, or a name and email address. If false, - format-patch defaults to `--no-from`, using commit authors directly in - the "From:" field of patch mails. If true, format-patch defaults to - `--from`, using your committer identity in the "From:" field of patch - mails and including a "From:" field in the body of the patch mail if - different. If set to a non-boolean value, format-patch uses that - value instead of your committer identity. 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 - is more than one patch. It can be enabled or disabled for all - messages by setting it to "true" or "false". See --numbered - option in linkgit:git-format-patch[1]. - -format.headers:: - Additional email headers to include in a patch to be submitted - by mail. See linkgit:git-format-patch[1]. - -format.to:: -format.cc:: - Additional recipients to include in a patch to be submitted - by mail. See the --to and --cc options in - linkgit:git-format-patch[1]. - -format.subjectPrefix:: - The default for format-patch is to output files with the '[PATCH]' - subject prefix. Use this variable to change that prefix. - -format.signature:: - The default for format-patch is to output a signature containing - the Git version number. Use this variable to change that default. - Set this variable to the empty string ("") to suppress - signature generation. - -format.signatureFile:: - Works just like format.signature except the contents of the - file specified by this variable will be used as the signature. - -format.suffix:: - The default for format-patch is to output files with the suffix - `.patch`. Use this variable to change that suffix (make sure to - include the dot if you want it). - -format.pretty:: - The default pretty format for log/show/whatchanged command, - See linkgit:git-log[1], linkgit:git-show[1], - linkgit:git-whatchanged[1]. - -format.thread:: - The default threading style for 'git format-patch'. Can be - a boolean value, or `shallow` or `deep`. `shallow` threading - makes every mail a reply to the head of the series, - where the head is chosen from the cover letter, the - `--in-reply-to`, and the first patch mail, in this order. - `deep` threading makes every mail a reply to the previous one. - A true boolean value is the same as `shallow`, and a false - value disables threading. - -format.signOff:: - A boolean value which lets you enable the `-s/--signoff` option of - format-patch by default. *Note:* Adding the Signed-off-by: line to a - patch should be a conscious act and means that you certify you have - the rights to submit this work under the same open source license. - Please see the 'SubmittingPatches' document for further discussion. - -format.coverLetter:: - A boolean that controls whether to generate a cover-letter when - format-patch is invoked, but in addition can be set to "auto", to - generate a cover-letter only when there's more than one patch. - -format.outputDirectory:: - Set a custom directory to store the resulting files instead of the - current working directory. - -format.useAutoBase:: - A boolean value which lets you enable the `--base=auto` option of - format-patch by default. - -filter.<driver>.clean:: - The command which is used to convert the content of a worktree - file to a blob upon checkin. See linkgit:gitattributes[5] for - details. - -filter.<driver>.smudge:: - The command which is used to convert the content of a blob - object to a worktree file upon checkout. See - linkgit:gitattributes[5] for details. - -fsck.<msg-id>:: - During fsck git may find issues with legacy data which - wouldn't be generated by current versions of git, and which - wouldn't be sent over the wire if `transfer.fsckObjects` was - set. This feature is intended to support working with legacy - repositories containing such data. -+ -Setting `fsck.<msg-id>` will be picked up by linkgit:git-fsck[1], but -to accept pushes of such data set `receive.fsck.<msg-id>` instead, or -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. -+ -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. -+ -When `fsck.<msg-id>` is set, errors can be switched to warnings and -vice versa by configuring the `fsck.<msg-id>` setting where the -`<msg-id>` is the fsck message ID and the value is one of `error`, -`warn` or `ignore`. For convenience, fsck prefixes the error/warning -with the message ID, e.g. "missingEmail: invalid author/committer line -- missing email" means that setting `fsck.missingEmail = ignore` will -hide that issue. -+ -In general, it is better to enumerate existing objects with problems -with `fsck.skipList`, instead of listing the kind of breakages these -problematic objects share to be ignored, as doing the latter will -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. - -fsck.skipList:: - The path to a sorted list of object names (i.e. one SHA-1 per - line) that are known to be broken in a non-fatal way and should - be ignored. This feature is useful when an established project - should be accepted 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. -+ -Like `fsck.<msg-id>` this variable has corresponding -`receive.fsck.skipList` and `fetch.fsck.skipList` variants. -+ -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. - -gc.aggressiveDepth:: - The depth parameter used in the delta compression - algorithm used by 'git gc --aggressive'. This defaults - to 50. - -gc.aggressiveWindow:: - The window size parameter used in the delta compression - algorithm used by 'git gc --aggressive'. This defaults - to 250. - -gc.auto:: - When there are approximately more than this many loose - objects in the repository, `git gc --auto` will pack them. - Some Porcelain commands use this command to perform a - light-weight garbage collection from time to time. The - default value is 6700. Setting this to 0 disables it. - -gc.autoPackLimit:: - When there are more than this many packs that are not - marked with `*.keep` file in the repository, `git gc - --auto` consolidates them into one larger pack. The - default value is 50. Setting this to 0 disables it. - -gc.autoDetach:: - Make `git gc --auto` return immediately and run in 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-base-pack` - except that all packs that meet the threshold are kept, not - just the base 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 -will be repacked. After this the number of packs should go below -gc.autoPackLimit and gc.bigPackThreshold should be respected again. - -gc.logExpiry:: - If the file gc.log exists, then `git gc --auto` won't run - unless that file is more than 'gc.logExpiry' old. Default is - "1.day". See `gc.pruneExpire` for more ways to specify its - value. - -gc.packRefs:: - Running `git pack-refs` in a repository renders it - unclonable by Git versions prior to 1.5.1.2 over dumb - transports such as HTTP. This variable determines whether - 'git gc' runs `git pack-refs`. This can be set to `notbare` - to enable it within all non-bare repos or it can be set to a - boolean value. The default is `true`. - -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]. - -gc.worktreePruneExpire:: - When 'git gc' is run, it calls - 'git worktree prune --expire 3.months.ago'. - This config variable can be used to set a different grace - period. The value "now" may be used to disable the grace - period and prune `$GIT_DIR/worktrees` immediately, or "never" - may be used to suppress pruning. - -gc.reflogExpire:: -gc.<pattern>.reflogExpire:: - 'git reflog expire' removes reflog entries older than - this time; defaults to 90 days. The value "now" expires all - entries immediately, and "never" suppresses expiration - altogether. With "<pattern>" (e.g. - "refs/stash") in the middle the setting applies only to - the refs that match the <pattern>. - -gc.reflogExpireUnreachable:: -gc.<pattern>.reflogExpireUnreachable:: - 'git reflog expire' removes reflog entries older than - this time and are not reachable from the current tip; - defaults to 30 days. The value "now" expires all entries - immediately, and "never" suppresses expiration altogether. - With "<pattern>" (e.g. "refs/stash") - in the middle, the setting applies only to the refs that - match the <pattern>. - -gc.rerereResolved:: - Records of conflicted merge you resolved earlier are - kept for this many days when 'git rerere gc' is run. - You can also use more human-readable "1.month.ago", etc. - The default is 60 days. See linkgit:git-rerere[1]. - -gc.rerereUnresolved:: - Records of conflicted merge you have not resolved are - kept for this many days when 'git rerere gc' is run. - You can also use more human-readable "1.month.ago", etc. - The default is 15 days. See linkgit:git-rerere[1]. - -gitcvs.commitMsgAnnotation:: - Append this string to each commit message. Set to empty string - to disable this feature. Defaults to "via git-CVS emulator". - -gitcvs.enabled:: - Whether the CVS server interface is enabled for this repository. - See linkgit:git-cvsserver[1]. - -gitcvs.logFile:: - Path to a log file where the CVS server interface well... logs - various stuff. See linkgit:git-cvsserver[1]. - -gitcvs.usecrlfattr:: - If true, the server will look up the end-of-line conversion - attributes for files to determine the `-k` modes to use. If - the attributes force Git to treat a file as text, - the `-k` mode will be left blank so CVS clients will - treat it as text. If they suppress text conversion, the file - will be set with '-kb' mode, which suppresses any newline munging - the client might otherwise do. If the attributes do not allow - the file type to be determined, then `gitcvs.allBinary` is - used. See linkgit:gitattributes[5]. - -gitcvs.allBinary:: - This is used if `gitcvs.usecrlfattr` does not resolve - the correct '-kb' mode to use. If true, all - unresolved files are sent to the client in - mode '-kb'. This causes the client to treat them - as binary files, which suppresses any newline munging it - otherwise might do. Alternatively, if it is set to "guess", - then the contents of the file are examined to decide if - it is binary, similar to `core.autocrlf`. - -gitcvs.dbName:: - Database used by git-cvsserver to cache revision information - derived from the Git repository. The exact meaning depends on the - used database driver, for SQLite (which is the default driver) this - is a filename. Supports variable substitution (see - linkgit:git-cvsserver[1] for details). May not contain semicolons (`;`). - Default: '%Ggitcvs.%m.sqlite' - -gitcvs.dbDriver:: - Used Perl DBI driver. You can specify any available driver - for this here, but it might not work. git-cvsserver is tested - with 'DBD::SQLite', reported to work with 'DBD::Pg', and - reported *not* to work with 'DBD::mysql'. Experimental feature. - May not contain double colons (`:`). Default: 'SQLite'. - See linkgit:git-cvsserver[1]. - -gitcvs.dbUser, gitcvs.dbPass:: - Database user and password. Only useful if setting `gitcvs.dbDriver`, - since SQLite has no concept of database users and/or passwords. - 'gitcvs.dbUser' supports variable substitution (see - linkgit:git-cvsserver[1] for details). - -gitcvs.dbTableNamePrefix:: - Database table name prefix. Prepended to the names of any - database tables used, allowing a single database to be used - for several repositories. Supports variable substitution (see - linkgit:git-cvsserver[1] for details). Any non-alphabetic - characters will be replaced with underscores. - -All gitcvs variables except for `gitcvs.usecrlfattr` and -`gitcvs.allBinary` can also be specified as -'gitcvs.<access_method>.<varname>' (where 'access_method' -is one of "ext" and "pserver") to make them apply only for the given -access method. - -gitweb.category:: -gitweb.description:: -gitweb.owner:: -gitweb.url:: - See linkgit:gitweb[1] for description. - -gitweb.avatar:: -gitweb.blame:: -gitweb.grep:: -gitweb.highlight:: -gitweb.patches:: -gitweb.pickaxe:: -gitweb.remote_heads:: -gitweb.showSizes:: -gitweb.snapshot:: - See linkgit:gitweb.conf[5] for description. - -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. - See `grep.threads` in linkgit:git-grep[1] for more information. - -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. - -gpg.program:: - Use this custom program instead of "`gpg`" found on `$PATH` when - making or verifying a PGP signature. The program must support the - same command-line interface as GPG, namely, to verify a detached - signature, "`gpg --verify $file - <$signature`" 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 - 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". - -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". - -gui.commitMsgWidth:: - Defines how wide the commit message window is in the - linkgit:git-gui[1]. "75" is the default. - -gui.diffContext:: - Specifies how many context lines should be used in calls to diff - made by the linkgit:git-gui[1]. The default is "5". - -gui.displayUntracked:: - Determines if linkgit:git-gui[1] shows untracked files - in the file list. The default is "true". - -gui.encoding:: - Specifies the default 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]). - If this option is not set, the tools default to the - locale encoding. - -gui.matchTrackingBranch:: - Determines if new branches created with linkgit:git-gui[1] should - default to tracking remote branches with matching names or - not. Default: "false". - -gui.newBranchTemplate:: - Is used as suggested name when creating new branches using the - linkgit:git-gui[1]. - -gui.pruneDuringFetch:: - "true" if linkgit:git-gui[1] should prune remote-tracking branches when - performing a fetch. The default value is "false". - -gui.trustmtime:: - Determines if linkgit:git-gui[1] should trust the file modification - timestamp or not. By default the timestamps are not trusted. - -gui.spellingDictionary:: - Specifies the dictionary used for spell checking commit messages in - the linkgit:git-gui[1]. When set to "none" spell checking is turned - off. - -gui.fastCopyBlame:: - If true, 'git gui blame' uses `-C` instead of `-C -C` for original - location detection. It makes blame significantly faster on huge - repositories at the expense of less thorough copy detection. - -gui.copyBlameThreshold:: - Specifies the threshold to use in 'git gui blame' original location - detection, measured in alphanumeric characters. See the - linkgit:git-blame[1] manual for more information on copy detection. - -gui.blamehistoryctx:: - Specifies the radius of history context in days to show in - linkgit:gitk[1] for the selected commit, when the `Show History - Context` menu item is invoked from 'git gui blame'. If this - variable is set to zero, the whole history is shown. - -guitool.<name>.cmd:: - Specifies the shell command line to execute when the corresponding item - of the linkgit:git-gui[1] `Tools` menu is invoked. This option is - mandatory for every tool. The command is executed from the root of - the working directory, and in the environment it receives the name of - the tool as `GIT_GUITOOL`, the name of the currently selected file as - 'FILENAME', and the name of the current branch as 'CUR_BRANCH' (if - the head is detached, 'CUR_BRANCH' is empty). - -guitool.<name>.needsFile:: - Run the tool only if a diff is selected in the GUI. It guarantees - that 'FILENAME' is not empty. - -guitool.<name>.noConsole:: - Run the command silently, without creating a window to display its - output. - -guitool.<name>.noRescan:: - Don't rescan the working directory for changes after the tool - finishes execution. - -guitool.<name>.confirm:: - Show a confirmation dialog before actually running the tool. - -guitool.<name>.argPrompt:: - Request a string argument from the user, and pass it to the tool - through the `ARGS` environment variable. Since requesting an - argument implies confirmation, the 'confirm' option has no effect - if this is enabled. If the option is set to 'true', 'yes', or '1', - the dialog uses a built-in generic prompt; otherwise the exact - value of the variable is used. - -guitool.<name>.revPrompt:: - Request a single valid revision from the user, and set the - `REVISION` environment variable. In other aspects this option - is similar to 'argPrompt', and can be used together with it. - -guitool.<name>.revUnmerged:: - Show only unmerged branches in the 'revPrompt' subdialog. - This is useful for tools similar to merge or rebase, but not - for things like checkout or reset. - -guitool.<name>.title:: - Specifies the title to use for the prompt dialog. The default - is the tool name. - -guitool.<name>.prompt:: - Specifies the general prompt string to display at the top of - the dialog, before subsections for 'argPrompt' and 'revPrompt'. - The default value includes the actual command. - -help.browser:: - Specify the browser that will be used to display help in the - 'web' format. See linkgit:git-help[1]. - -help.format:: - Override the default help format used by linkgit:git-help[1]. - Values 'man', 'info', 'web' and 'html' are supported. 'man' is - the default. 'web' and 'html' are the same. - -help.autoCorrect:: - Automatically correct and execute mistyped commands after - waiting for the given number of deciseconds (0.1 sec). If more - than one command can be deduced from the entered text, nothing - will be executed. If the value of this option is negative, - the corrected command will be executed immediately. If the - value is 0 - the command will be just shown but not executed. - This is the default. - -help.htmlPath:: - Specify the path where the HTML documentation resides. File system paths - and URLs are supported. HTML pages will be prefixed with this path when - help is displayed in the 'web' format. This defaults to the documentation - path of your Git installation. - -http.proxy:: - Override the HTTP proxy, normally configured using the 'http_proxy', - 'https_proxy', and 'all_proxy' environment variables (see `curl(1)`). In - addition to the syntax understood by curl, it is possible to specify a - proxy string with a user name but no password, in which case git will - attempt to acquire one in the same way it does for other credentials. See - linkgit:gitcredentials[7] for more information. The syntax thus is - '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden - on a per-remote basis; see remote.<name>.proxy - -http.proxyAuthMethod:: - Set the method with which to authenticate against the HTTP proxy. This - only takes effect if the configured proxy string contains a user name part - (i.e. is of the form 'user@host' or 'user@host:port'). This can be - overridden on a per-remote basis; see `remote.<name>.proxyAuthMethod`. - Both can be overridden by the `GIT_HTTP_PROXY_AUTHMETHOD` environment - variable. Possible values are: -+ --- -* `anyauth` - Automatically pick a suitable authentication method. It is - assumed that the proxy answers an unauthenticated request with a 407 - status code and one or more Proxy-authenticate headers with supported - authentication methods. This is the default. -* `basic` - HTTP Basic authentication -* `digest` - HTTP Digest authentication; this prevents the password from being - transmitted to the proxy in clear text -* `negotiate` - GSS-Negotiate authentication (compare the --negotiate option - of `curl(1)`) -* `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) --- - -http.emptyAuth:: - Attempt authentication without seeking a username or password. This - can be used to attempt GSS-Negotiate authentication without specifying - a username in the URL, as libcurl normally requires a username for - authentication. - -http.delegation:: - Control GSSAPI credential delegation. The delegation is disabled - by default in libcurl since version 7.21.7. Set parameter to tell - the server what it is allowed to delegate when it comes to user - credentials. Used with GSS/kerberos. Possible values are: -+ --- -* `none` - Don't allow any delegation. -* `policy` - Delegates if and only if the OK-AS-DELEGATE flag is set in the - Kerberos service ticket, which is a matter of realm policy. -* `always` - Unconditionally allow the server to delegate. --- - - -http.extraHeader:: - Pass an additional HTTP header when communicating with a server. If - more than one such entry exists, all of them are added as extra - headers. To allow overriding the settings inherited from the system - config, an empty value will reset the extra headers to the empty list. - -http.cookieFile:: - The pathname of a file containing previously stored cookie lines, - which should be used - in the Git http session, if they match the server. The file format - of the file to read cookies from should be plain HTTP headers or - the Netscape/Mozilla cookie file format (see `curl(1)`). - NOTE that the file specified with http.cookieFile is used only as - input unless http.saveCookies is set. - -http.saveCookies:: - If set, store cookies received during requests to the file specified by - http.cookieFile. Has no effect if http.cookieFile is unset. - -http.sslVersion:: - The SSL version to use when negotiating an SSL connection, if you - want to force the default. The available and default version - depend on whether libcurl was built against NSS or OpenSSL and the - particular configuration of the crypto library in use. Internally - this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl - documentation for more details on the format of this option and - for the ssl version supported. Actually the possible values of - this option are: - - - sslv2 - - sslv3 - - tlsv1 - - tlsv1.0 - - tlsv1.1 - - tlsv1.2 - - tlsv1.3 +include::config/alias.txt[] -+ -Can be overridden by the `GIT_SSL_VERSION` environment variable. -To force git to use libcurl's default ssl version and ignore any -explicit http.sslversion option, set `GIT_SSL_VERSION` to the -empty string. - -http.sslCipherList:: - A list of SSL ciphers to use when negotiating an SSL connection. - The available ciphers depend on whether libcurl was built against - NSS or OpenSSL and the particular configuration of the crypto - library in use. Internally this sets the 'CURLOPT_SSL_CIPHER_LIST' - option; see the libcurl documentation for more details on the format - of this list. -+ -Can be overridden by the `GIT_SSL_CIPHER_LIST` environment variable. -To force git to use libcurl's default cipher list and ignore any -explicit http.sslCipherList option, set `GIT_SSL_CIPHER_LIST` to the -empty string. - -http.sslVerify:: - Whether to verify the SSL certificate when fetching or pushing - over HTTPS. Defaults to true. Can be overridden by the - `GIT_SSL_NO_VERIFY` environment variable. - -http.sslCert:: - File containing the SSL certificate when fetching or pushing - over HTTPS. Can be overridden by the `GIT_SSL_CERT` environment - variable. - -http.sslKey:: - File containing the SSL private key when fetching or pushing - over HTTPS. Can be overridden by the `GIT_SSL_KEY` environment - variable. - -http.sslCertPasswordProtected:: - Enable Git's password prompt for the SSL certificate. Otherwise - OpenSSL will prompt the user, possibly many times, if the - certificate or private key is encrypted. Can be overridden by the - `GIT_SSL_CERT_PASSWORD_PROTECTED` environment variable. - -http.sslCAInfo:: - File containing the certificates to verify the peer with when - fetching or pushing over HTTPS. Can be overridden by the - `GIT_SSL_CAINFO` environment variable. - -http.sslCAPath:: - Path containing files with the CA certificates to verify the peer - with when fetching or pushing over HTTPS. Can be overridden - by the `GIT_SSL_CAPATH` environment variable. - -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 - public key. See also libcurl 'CURLOPT_PINNEDPUBLICKEY'. git will - exit with an error if this option is set but not supported by - cURL. - -http.sslTry:: - Attempt to use AUTH SSL/TLS and encrypted data transfers - when connecting via regular FTP protocol. This might be needed - if the FTP server requires it for security reasons or you wish - to connect securely whenever remote FTP server supports it. - Default is false since it might trigger certificate verification - errors on misconfigured servers. - -http.maxRequests:: - How many HTTP requests to launch in parallel. Can be overridden - by the `GIT_HTTP_MAX_REQUESTS` environment variable. Default is 5. - -http.minSessions:: - The number of curl sessions (counted across slots) to be kept across - requests. They will not be ended with curl_easy_cleanup() until - http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this - value will be capped at 1. Defaults to 1. - -http.postBuffer:: - Maximum size in bytes of the buffer used by smart HTTP - transports when POSTing data to the remote system. - For requests larger than this buffer size, HTTP/1.1 and - Transfer-Encoding: chunked is used to avoid creating a - massive pack file locally. Default is 1 MiB, which is - sufficient for most requests. - -http.lowSpeedLimit, http.lowSpeedTime:: - If the HTTP transfer speed 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 - 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. - 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 - of common USER_AGENT strings (but not including those like git/1.7.1). - Can be overridden by the `GIT_HTTP_USER_AGENT` environment variable. - -http.followRedirects:: - Whether git should follow HTTP redirects. If set to `true`, git - will transparently follow any redirect issued by a server it - encounters. If set to `false`, git will treat all redirects as - errors. If set to `initial`, git will follow redirects only for - the initial request to a remote, but not for subsequent - follow-up HTTP requests. Since git uses the redirected URL as - the base for the follow-up requests, this is generally - sufficient. The default is `initial`. - -http.<url>.*:: - Any of the http.* options above can be applied selectively to some URLs. - For a config key to match a URL, each element of the config key is - compared to that of the URL, in the following order: -+ --- -. Scheme (e.g., `https` in `https://example.com/`). This field - must match exactly between the config key and the URL. - -. Host/domain name (e.g., `example.com` in `https://example.com/`). - This field must match between the config key and the URL. It is - possible to specify a `*` as part of the host name to match all subdomains - at this level. `https://*.example.com/` for example would match - `https://foo.example.com/`, but not `https://foo.bar.example.com/`. - -. Port number (e.g., `8080` in `http://example.com:8080/`). - This field must match exactly between the config key and the URL. - Omitted port numbers are automatically converted to the correct - default for the scheme before matching. - -. Path (e.g., `repo.git` in `https://example.com/repo.git`). The - path field of the config key must match the path field of the URL - either exactly or as a prefix of slash-delimited path elements. This means - a config key with path `foo/` matches URL path `foo/bar`. A prefix can only - match on a slash (`/`) boundary. Longer matches take precedence (so a config - key with path `foo/bar` is a better match to URL path `foo/bar` than a config - key with just path `foo/`). - -. User name (e.g., `user` in `https://user@example.com/repo.git`). If - the config key has a user name it must match the user name in the - URL exactly. If the config key does not have a user name, that - config key will match a URL with any user name (including none), - but at a lower precedence than a config key with a user name. --- -+ -The list above is ordered by decreasing precedence; a URL that matches -a config key's path is preferred to one that matches its user name. For example, -if the URL is `https://user@example.com/foo/bar` a config key match of -`https://example.com/foo` will be preferred over a config key match of -`https://user@example.com`. -+ -All URLs are normalized before attempting any matching (the password part, -if embedded in the URL, is always ignored for matching purposes) so that -equivalent URLs that are simply spelled differently will match properly. -Environment variable settings always override any matches. The URLs that are -matched against are those given directly to Git commands. This means any URLs -visited as a result of a redirection do not participate in matching. - -ssh.variant:: - By default, Git determines the command line arguments to use - based on the basename of the configured SSH command (configured - using the environment variable `GIT_SSH` or `GIT_SSH_COMMAND` or - the config setting `core.sshCommand`). If the basename is - unrecognized, Git will attempt to detect support of OpenSSH - options by first invoking the configured SSH command with the - `-G` (print configuration) option and will subsequently use - OpenSSH options (if that is successful) or no options besides - the host and remote command (if it fails). -+ -The config variable `ssh.variant` can be set to override this detection. -Valid values are `ssh` (to use OpenSSH options), `plink`, `putty`, -`tortoiseplink`, `simple` (no options except the host and remote command). -The default auto-detection can be explicitly requested using the value -`auto`. Any other value is treated as `ssh`. This setting can also be -overridden via the environment variable `GIT_SSH_VARIANT`. -+ -The current command-line parameters used for each variant are as -follows: -+ --- +include::config/am.txt[] -* `ssh` - [-p port] [-4] [-6] [-o option] [username@]host command +include::config/apply.txt[] -* `simple` - [username@]host command +include::config/blame.txt[] -* `plink` or `putty` - [-P port] [-4] [-6] [username@]host command +include::config/branch.txt[] -* `tortoiseplink` - [-P port] [-4] [-6] -batch [username@]host command +include::config/browser.txt[] --- -+ -Except for the `simple` variant, command-line parameters are likely to -change as git gains new features. - -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 - porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'. - -i18n.logOutputEncoding:: - Character encoding the commit messages are converted to when - running 'git log' and friends. - -imap:: - The configuration variables in the 'imap' section are described - in linkgit:git-imap-send[1]. - -index.version:: - Specify the version with which new index files should be - initialized. This does not affect existing repositories. - -init.templateDir:: - Specify the directory from which templates will be copied. - (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) - -instaweb.browser:: - Specify the program that will be used to browse your working - repository in gitweb. See linkgit:git-instaweb[1]. - -instaweb.httpd:: - The HTTP daemon command-line to start gitweb on your working - repository. See linkgit:git-instaweb[1]. - -instaweb.local:: - If true the web server started by linkgit:git-instaweb[1] will - be bound to the local IP (127.0.0.1). - -instaweb.modulePath:: - The default module path for linkgit:git-instaweb[1] to use - instead of /usr/lib/apache2/modules. Only used if httpd - is Apache. - -instaweb.port:: - The port number to bind the gitweb httpd to. See - linkgit:git-instaweb[1]. - -interactive.singleKey:: - In interactive commands, allow the user to provide one-letter - input with a single key (i.e., without hitting enter). - Currently this is used by the `--patch` mode of - linkgit:git-add[1], linkgit:git-checkout[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. - -interactive.diffFilter:: - When an interactive command (such as `git add --patch`) shows - a colorized diff, git will pipe the diff through the shell - command defined by this configuration variable. The command may - mark up the diff further for human consumption, provided that it - retains a one-to-one correspondence with the lines in the - original diff. Defaults to disabled (no filtering). - -log.abbrevCommit:: - If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may - override this option with `--no-abbrev-commit`. - -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. - -log.decorate:: - Print out the ref names of any commits that are shown by the log - command. If 'short' is specified, the ref name prefixes 'refs/heads/', - 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is - specified, the full ref name (including prefix) will be printed. - If 'auto' is specified, then if the output is going to a terminal, - the ref names are shown as if 'short' were given, otherwise no ref - names are shown. This is the same as the `--decorate` option - of the `git log`. - -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.graphColors:: - A list of colors, separated by commas, that can be used to draw - history lines in `git log --graph`. - -log.showRoot:: - If true, the initial commit will be shown as a big creation event. - This is equivalent to a diff against an empty tree. - Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which - normally hide the root commit will now show it. True by default. - -log.showSignature:: - If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `--show-signature`. - -log.mailmap:: - If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `--use-mailmap`. - -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 - removes everything from the message body before a scissors - line (i.e. consisting mainly of ">8", "8<" and "-"). - -mailmap.file:: - The location of an augmenting mailmap file. The default - mailmap, located in the root of the repository, is loaded - first, then the mailmap file pointed to by this variable. - The location of the mailmap file may be in a repository - subdirectory, or somewhere outside of the repository itself. - See linkgit:git-shortlog[1] and linkgit:git-blame[1]. - -mailmap.blob:: - Like `mailmap.file`, but consider the value as a reference to a - blob in the repository. If both `mailmap.file` and - `mailmap.blob` are given, both are parsed, with entries from - `mailmap.file` taking precedence. In a bare repository, this - defaults to `HEAD:.mailmap`. In a non-bare repository, it - defaults to empty. - -man.viewer:: - Specify the programs that may be used to display help in the - 'man' format. See linkgit:git-help[1]. - -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].) - -man.<tool>.path:: - Override the path for the given tool that may be used to - display help in the 'man' format. See linkgit:git-help[1]. - -include::merge-config.txt[] - -mergetool.<tool>.path:: - Override the path for the given tool. This is useful in case - your tool is not in the PATH. - -mergetool.<tool>.cmd:: - Specify the command to invoke the specified merge tool. The - specified command is evaluated in shell with the following - variables available: 'BASE' is the name of a temporary file - containing the common base of the files to be merged, if available; - 'LOCAL' is the name of a temporary file containing the contents of - the file on the current branch; 'REMOTE' is the name of a temporary - file containing the contents of the file from the branch being - merged; 'MERGED' contains the name of the file to which the merge - tool should write the results of a successful merge. - -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 - indicate the success of the merge. - -mergetool.meld.hasOutput:: - Older versions of `meld` do not support the `--output` option. - Git will attempt to detect whether `meld` supports `--output` - by inspecting the output of `meld --help`. Configuring - `mergetool.meld.hasOutput` will make Git skip these checks and - use the configured value instead. Setting `mergetool.meld.hasOutput` - to `true` tells Git to unconditionally use the `--output` option, - and `false` avoids using `--output`. - -mergetool.keepBackup:: - After performing a merge, the original file with conflict markers - can be saved as a file with a `.orig` extension. If this variable - is set to `false` then this file is not preserved. Defaults to - `true` (i.e. keep the backup files). - -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 - exited. Defaults to `false`. - -mergetool.writeToTemp:: - Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of - conflicting files in the worktree by default. Git will attempt - to use a temporary directory for these files when set `true`. - Defaults to `false`. - -mergetool.prompt:: - Prompt before each invocation of the merge resolution program. - -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 of linkgit:git-notes[1] for more information on each strategy. - -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 in - 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. -+ -This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` -environment variable, which must be a colon separated list of refs or -globs. -+ -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. - -notes.rewriteMode:: - When copying notes during a rewrite (see the - "notes.rewrite.<command>" option), determines 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. 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. -+ -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. - -pack.window:: - The size of the window used by linkgit:git-pack-objects[1] when no - window size is given on the command line. Defaults to 10. - -pack.depth:: - The maximum delta depth used by linkgit:git-pack-objects[1] when no - maximum depth is given on the command line. Defaults to 50. - Maximum value is 4095. - -pack.windowMemory:: - The maximum size of memory that is consumed by each thread - in linkgit:git-pack-objects[1] for pack window memory when - no limit is given on the command line. The value can be - suffixed with "k", "m", or "g". When left unconfigured (or - set explicitly to 0), there will be no limit. - -pack.compression:: - An integer -1..9, indicating the compression level for objects - in a pack file. -1 is the zlib default. 0 means no - compression, and 1..9 are various speed/size tradeoffs, 9 being - slowest. If not set, defaults to core.compression. If that is - not set, defaults to -1, the zlib default, which is "a default - compromise between speed and compression (currently equivalent - to level 6)." -+ -Note that changing the compression level will not automatically recompress -all existing objects. You can force recompression by passing the -F option -to linkgit:git-repack[1]. - -pack.deltaCacheSize:: - The maximum memory in bytes used for caching deltas in - linkgit:git-pack-objects[1] before writing them out to a pack. - This cache is used to speed up the writing object phase by not - having to recompute the final delta result once the best match - for all objects is found. Repacking large repositories on machines - which are tight with memory might be badly impacted by this though, - especially if this cache pushes the system into swapping. - A value of 0 means no limit. The smallest size of 1 byte may be - used to virtually disable this cache. Defaults to 256 MiB. - -pack.deltaCacheLimit:: - The maximum size of a delta, that is cached in - linkgit:git-pack-objects[1]. This cache is used to speed up the - writing object phase by not having to recompute the final delta - result once the best match for all objects is found. - Defaults to 1000. Maximum value is 65535. - -pack.threads:: - Specifies the number of threads to spawn when searching for best - delta matches. This requires that linkgit:git-pack-objects[1] - be compiled with pthreads otherwise this option is ignored with a - 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 - and set the number of threads accordingly. - -pack.indexVersion:: - Specify the default pack index version. Valid values are 1 for - legacy pack index used by Git versions prior to 1.5.2, and 2 for - 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 - 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") -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, -you can use linkgit:git-index-pack[1] on the *.pack file to regenerate -the `*.idx` file. - -pack.packSizeLimit:: - The maximum size of a pack. This setting only affects - packing to a file when repacking, i.e. the git:// protocol - is unaffected. It can be overridden by the `--max-pack-size` - option of linkgit:git-repack[1]. Reaching this limit results - in the creation of multiple packfiles; which in turn prevents - bitmaps from being created. - The minimum size allowed is limited to 1 MiB. - The default is unlimited. - Common unit suffixes of 'k', 'm', or 'g' are - supported. - -pack.useBitmaps:: - When true, git will use pack bitmaps (if available) when packing - to stdout (e.g., during the server side of a fetch). Defaults to - true. You should not generally need to turn this off unless - you are debugging pack bitmaps. - -pack.writeBitmaps (deprecated):: - This is a deprecated synonym for `repack.writeBitmaps`. - -pack.writeBitmapHashCache:: - When true, git will include a "hash cache" section in the bitmap - index (if one is written). This cache can be used to feed git's - delta heuristics, potentially leading to better deltas between - bitmapped and non-bitmapped objects (e.g., when serving a fetch - 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, and that JGit's bitmap - implementation does not understand it, causing it to complain if - Git and JGit are used on the same repository. Defaults to false. - -pager.<cmd>:: - If the value is boolean, turns on or off pagination of the - output of a particular Git subcommand when writing to a tty. - Otherwise, turns on pagination for the subcommand using the - pager specified by the value of `pager.<cmd>`. If `--paginate` - or `--no-pager` is specified on the command line, it takes - precedence over this option. To disable pagination for all - commands, set `core.pager` or `GIT_PAGER` to `cat`. - -pretty.<name>:: - Alias for a --pretty= format string, as specified in - linkgit:git-log[1]. Any aliases defined here can be used just - as the built-in pretty formats could. For example, - running `git config pretty.changelog "format:* %H %s"` - would cause the invocation `git log --pretty=changelog` - to be equivalent to running `git log "--pretty=format:* %H %s"`. - Note that an alias with the same name as a built-in format - will be silently ignored. - -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 - 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: -+ --- +include::config/checkout.txt[] -* `always` - protocol is always able to be used. +include::config/clean.txt[] -* `never` - protocol is never able to be used. +include::config/color.txt[] -* `user` - protocol is only able to be used when `GIT_PROTOCOL_FROM_USER` is - either unset or has a value of 1. This policy should be used when you want a - protocol to be directly usable by the user but don't want it used by commands which - execute clone/fetch/push commands without user input, e.g. recursive - submodule initialization. +include::config/column.txt[] --- +include::config/commit.txt[] -protocol.<name>.allow:: - Set a policy to be used by protocol `<name>` with clone/fetch/push - commands. See `protocol.allow` above for the available policies. -+ -The protocol names currently used by git are: -+ --- - - `file`: any local file-based path (including `file://` URLs, - or local paths) - - - `git`: the anonymous git protocol over a direct TCP - connection (or proxy, if configured) - - - `ssh`: git over ssh (including `host:path` syntax, - `ssh://`, etc). - - - `http`: git over http, both "smart http" and "dumb http". - Note that this does _not_ include `https`; if you want to configure - both, you must do so individually. - - - any external helpers are named by their protocol (e.g., use - `hg` to allow the `git-remote-hg` helper) --- - -protocol.version:: - Experimental. If set, clients will attempt to communicate with a - server using the specified protocol version. If unset, no - attempt will be made by the client to communicate using a - particular protocol version, this results in protocol version 0 - being used. - Supported versions: -+ --- - -* `0` - the original wire protocol. - -* `1` - the original wire protocol with the addition of a version string - in the initial response from the server. - --- - -pull.ff:: - By default, Git does not create an extra merge commit when merging - a commit that is a descendant of the current commit. Instead, the - tip of the current branch is fast-forwarded. When set to `false`, - this variable tells Git to create an extra merge commit in such - a case (equivalent to giving the `--no-ff` option from the command - line). When set to `only`, only such fast-forward merges are - allowed (equivalent to giving the `--ff-only` option from the - command line). This setting overrides `merge.ff` when pulling. - -pull.rebase:: - When true, rebase branches on top of the fetched branch, instead - of merging the default branch from the default remote when "git - pull" is run. See "branch.<name>.rebase" for setting this on a - per-branch basis. -+ -When `merges`, 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, 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`, the rebase is run in interactive mode. -+ -*NOTE*: this is a possibly dangerous operation; do *not* use -it unless you understand the implications (see linkgit:git-rebase[1] -for details). - -pull.octopus:: - The default merge strategy to use when pulling multiple branches - at once. - -pull.twohead:: - The default merge strategy to use when pulling a single branch. - -push.default:: - Defines the action `git push` should take if no refspec is - explicitly given. Different values are well-suited for - specific workflows; for instance, in a purely central workflow - (i.e. the fetch source is equal to the push destination), - `upstream` is probably what you want. Possible values are: -+ --- +include::config/credential.txt[] -* `nothing` - do not push anything (error out) unless a refspec is - explicitly given. This is primarily meant for people who want to - avoid mistakes by always being explicit. +include::config/completion.txt[] -* `current` - push the current branch to update a branch with the same - name on the receiving end. Works in both central and non-central - workflows. +include::config/diff.txt[] -* `upstream` - push the current branch back to the branch whose - changes are usually integrated into the current branch (which is - called `@{upstream}`). This mode only makes sense if you are - pushing to the same repository you would normally pull from - (i.e. central workflow). +include::config/difftool.txt[] -* `tracking` - This is a deprecated synonym for `upstream`. +include::config/fastimport.txt[] -* `simple` - in centralized workflow, work like `upstream` with an - added safety to refuse to push if the upstream branch's name is - different from the local one. -+ -When pushing to a remote that is different from the remote you normally -pull from, work as `current`. This is the safest option and is suited -for beginners. -+ -This mode has become the default in Git 2.0. - -* `matching` - push all branches having the same name on both ends. - This makes the repository you are pushing to remember the set of - branches that will be pushed out (e.g. if you always push 'maint' - and 'master' there and no other branches, the repository you push - to will have these two branches, and your local 'maint' and - 'master' will be pushed there). -+ -To use this mode effectively, you have to make sure _all_ the -branches you would push out are ready to be pushed out before -running 'git push', as the whole point of this mode is to allow you -to push all of the branches in one go. If you usually finish work -on only one branch and push out the result, while other branches are -unfinished, this mode is not for you. Also this mode is not -suitable for pushing into a shared central repository, as other -people may add new branches there, or update the tip of existing -branches outside your control. -+ -This used to be the default, but not since Git 2.0 (`simple` is the -new default). - --- - -push.followTags:: - If set to true enable `--follow-tags` option by default. You - may override this configuration at time of push by specifying - `--no-follow-tags`. - -push.gpgSign:: - May be set to a boolean value, or the string 'if-asked'. A true - value causes all pushes to be GPG signed, as if `--signed` is - passed to linkgit:git-push[1]. The string 'if-asked' causes - pushes to be signed if the server supports it, as if - `--signed=if-asked` is passed to 'git push'. A false value may - override a value from a lower-priority config file. An explicit - command-line flag always overrides this config option. - -push.pushOption:: - When no `--push-option=<option>` argument is given from the - command line, `git push` behaves as if each <value> of - this variable is given as `--push-option=<value>`. -+ -This is a multi-valued variable, and an empty value can be used in a -higher priority configuration file (e.g. `.git/config` in a -repository) to clear the values inherited from a lower priority -configuration files (e.g. `$HOME/.gitconfig`). -+ --- - -Example: - -/etc/gitconfig - push.pushoption = a - push.pushoption = b - -~/.gitconfig - push.pushoption = c - -repo/.git/config - push.pushoption = - push.pushoption = b - -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'. - -include::rebase-config.txt[] - -receive.advertiseAtomic:: - By default, git-receive-pack will advertise the atomic push - capability to its clients. If you don't want to advertise this - capability, set this variable to false. - -receive.advertisePushOptions:: - When set to true, git-receive-pack will advertise the push options - capability to its clients. False by default. - -receive.autogc:: - By default, git-receive-pack will run "git-gc --auto" after - receiving data from git-push and updating refs. You can stop - it by setting this variable to false. - -receive.certNonceSeed:: - By setting this variable to a string, `git receive-pack` - will accept a `git push --signed` and verifies 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 - "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 - hooks (instead of what the receive-pack asked the sending - side to include). This may allow writing checks in - `pre-receive` and `post-receive` a bit easier. Instead of - checking `GIT_PUSH_CERT_NONCE_SLOP` environment variable - that records by how many seconds the nonce is stale to - decide if they want to accept the certificate, they only - can check `GIT_PUSH_CERT_NONCE_STATUS` is `OK`. - -receive.fsckObjects:: - If it is set to true, git-receive-pack will check all received - objects. See `transfer.fsckObjects` for what's checked. - Defaults to false. If not set, the value of - `transfer.fsckObjects` is used instead. - -receive.fsck.<msg-id>:: - Acts like `fsck.<msg-id>`, but is used by - linkgit:git-receive-pack[1] instead of - linkgit:git-fsck[1]. See the `fsck.<msg-id>` documentation for - details. - -receive.fsck.skipList:: - Acts like `fsck.skipList`, but is used by - linkgit:git-receive-pack[1] instead of - linkgit:git-fsck[1]. See the `fsck.skipList` documentation for - details. - -receive.keepAlive:: - After receiving the pack from the client, `receive-pack` may - produce no output (if `--quiet` was specified) while processing - the pack, causing some networks to drop the TCP connection. - With this option set, if `receive-pack` does not transmit - any data in this phase for `receive.keepAlive` seconds, it will - send a short keepalive packet. The default is 5 seconds; set - to 0 to disable keepalives entirely. - -receive.unpackLimit:: - If the number of objects received in a push is below this - limit then the objects will be unpacked into loose object - files. However if the number of received objects equals or - exceeds this limit then the received pack will be stored as - a pack, after adding any missing delta bases. Storing the - pack from a push can make the push operation complete faster, - especially on slow filesystems. If not set, the value of - `transfer.unpackLimit` is used instead. - -receive.maxInputSize:: - If the size of the incoming pack stream is larger than this - limit, then git-receive-pack will error out, instead of - accepting the pack file. If not set or set to 0, then the size - is unlimited. - -receive.denyDeletes:: - If set to true, git-receive-pack will deny a ref update that deletes - the ref. Use this to prevent such a ref deletion via a push. - -receive.denyDeleteCurrent:: - If set to true, git-receive-pack will deny a ref update that - deletes the currently checked out branch of a non-bare repository. - -receive.denyCurrentBranch:: - If set to true or "refuse", git-receive-pack will deny a ref update - to the currently checked out branch of a non-bare repository. - Such a push is potentially dangerous because it brings the HEAD - out of sync with the index and working tree. If set to "warn", - print a warning of such a push to stderr, but allow the push to - proceed. If set to false or "ignore", allow such pushes with no - message. Defaults to "refuse". -+ -Another option is "updateInstead" which will update the working -tree if pushing into the current branch. This option is -intended for synchronizing working directories when one side is not easily -accessible via interactive ssh (e.g. a live web site, hence the requirement -that the working directory be clean). This mode also comes in handy when -developing inside a VM to test and fix code on different Operating Systems. -+ -By default, "updateInstead" will refuse the push if the working tree or -the index have any difference from the HEAD, but the `push-to-checkout` -hook can be used to customize this. See linkgit:githooks[5]. - -receive.denyNonFastForwards:: - If set to true, git-receive-pack will deny a ref update which is - not a fast-forward. Use this to prevent such an update via a push, - even if that push is forced. This configuration variable is - set when initializing a shared repository. - -receive.hideRefs:: - This variable is the same as `transfer.hideRefs`, but applies - only to `receive-pack` (and so affects pushes, but not fetches). - An attempt to update or delete a hidden ref by `git push` is - rejected. - -receive.updateServerInfo:: - If set to true, git-receive-pack will run git-update-server-info - after receiving data from git-push and updating refs. - -receive.shallowUpdate:: - If set to true, .git/shallow can be updated when new refs - require new shallow roots. Otherwise those refs are rejected. - -remote.pushDefault:: - The remote to push to by default. Overrides - `branch.<name>.remote` for all branches, and is overridden by - `branch.<name>.pushRemote` for specific branches. - -remote.<name>.url:: - The URL of a remote repository. See linkgit:git-fetch[1] or - linkgit:git-push[1]. - -remote.<name>.pushurl:: - The push URL of a remote repository. See linkgit:git-push[1]. - -remote.<name>.proxy:: - For remotes that require curl (http, https and ftp), the URL to - the proxy to use for that remote. Set to the empty string to - disable proxying for that remote. - -remote.<name>.proxyAuthMethod:: - For remotes that require curl (http, https and ftp), the method to use for - authenticating against the proxy in use (probably set in - `remote.<name>.proxy`). See `http.proxyAuthMethod`. - -remote.<name>.fetch:: - The default set of "refspec" for linkgit:git-fetch[1]. See - linkgit:git-fetch[1]. - -remote.<name>.push:: - The default set of "refspec" for linkgit:git-push[1]. See - linkgit:git-push[1]. - -remote.<name>.mirror:: - If true, pushing to this remote will automatically behave - as if the `--mirror` option was given on the command line. - -remote.<name>.skipDefaultUpdate:: - If true, this remote will be skipped by default when updating - using linkgit:git-fetch[1] or the `update` subcommand of - linkgit:git-remote[1]. - -remote.<name>.skipFetchAll:: - If true, this remote will be skipped by default when updating - using linkgit:git-fetch[1] or the `update` subcommand of - linkgit:git-remote[1]. - -remote.<name>.receivepack:: - The default program to execute on the remote side when pushing. See - option --receive-pack of linkgit:git-push[1]. - -remote.<name>.uploadpack:: - The default program to execute on the remote side when fetching. See - option --upload-pack of linkgit:git-fetch-pack[1]. - -remote.<name>.tagOpt:: - Setting this value to --no-tags disables automatic tag following when - fetching from remote <name>. Setting it to --tags will fetch every - tag from remote <name>, even if they are not reachable from remote - branch heads. Passing these flags directly to linkgit:git-fetch[1] can - override this setting. See options --tags and --no-tags of - linkgit:git-fetch[1]. - -remote.<name>.vcs:: - Setting this to a value <vcs> will cause Git to interact with - the remote with the git-remote-<vcs> helper. - -remote.<name>.prune:: - When set to true, fetching from this remote by default will also - remove any remote-tracking references that no longer exist on the - remote (as if the `--prune` option was given on the command line). - Overrides `fetch.prune` settings, if any. - -remote.<name>.pruneTags:: - When set to true, fetching from this remote by default will also - remove any local tags that no longer exist on the remote if pruning - is activated in general via `remote.<name>.prune`, `fetch.prune` or - `--prune`. Overrides `fetch.pruneTags` settings, if any. -+ -See also `remote.<name>.prune` and the PRUNING section of -linkgit:git-fetch[1]. - -remotes.<group>:: - The list of remotes which are fetched by "git remote update - <group>". See linkgit:git-remote[1]. - -repack.useDeltaBaseOffset:: - By default, linkgit:git-repack[1] creates packs that use - delta-base offset. If you need to share your repository with - Git older than version 1.4.4, either directly or via a dumb - protocol such as http, then you need to set this option to - "false" and repack. Access from old Git versions over the - native protocol are unaffected by this option. - -repack.packKeptObjects:: - If set to true, makes `git repack` act as if - `--pack-kept-objects` was passed. See linkgit:git-repack[1] for - details. Defaults to `false` normally, but `true` if a bitmap - index is being written (either via `--write-bitmap-index` or - `repack.writeBitmaps`). - -repack.writeBitmaps:: - When true, git will write a bitmap index when packing all - objects to disk (e.g., when `git repack -a` is run). This - index can speed up the "counting objects" phase of subsequent - packs created for clones and fetches, at the cost of some disk - space and extra time spent on the initial repack. This has - no effect if multiple packfiles are created. - Defaults to false. - -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. - -rerere.enabled:: - Activate recording of resolved conflicts, so that identical - conflict hunks can be resolved automatically, should they be - encountered again. By default, linkgit:git-rerere[1] is - enabled if there is an `rr-cache` directory under the - `$GIT_DIR`, e.g. if "rerere" was previously used in the - repository. - -sendemail.identity:: - A configuration identity. When given, causes values in the - 'sendemail.<identity>' subsection to take precedence over - values in the 'sendemail' section. The default identity is - the value of `sendemail.identity`. - -sendemail.smtpEncryption:: - See linkgit:git-send-email[1] for description. Note that this - setting is not subject to the 'identity' mechanism. - -sendemail.smtpssl (deprecated):: - Deprecated alias for 'sendemail.smtpEncryption = ssl'. - -sendemail.smtpsslcertpath:: - Path to ca-certificates (either a directory or a single file). - Set it to an empty string to disable certificate verification. - -sendemail.<identity>.*:: - Identity-specific versions of the 'sendemail.*' parameters - found below, taking precedence over those when this - identity is selected, through either the command-line or - `sendemail.identity`. - -sendemail.aliasesFile:: -sendemail.aliasFileType:: -sendemail.annotate:: -sendemail.bcc:: -sendemail.cc:: -sendemail.ccCmd:: -sendemail.chainReplyTo:: -sendemail.confirm:: -sendemail.envelopeSender:: -sendemail.from:: -sendemail.multiEdit:: -sendemail.signedoffbycc:: -sendemail.smtpPass:: -sendemail.suppresscc:: -sendemail.suppressFrom:: -sendemail.to:: -sendemail.tocmd:: -sendemail.smtpDomain:: -sendemail.smtpServer:: -sendemail.smtpServerPort:: -sendemail.smtpServerOption:: -sendemail.smtpUser:: -sendemail.thread:: -sendemail.transferEncoding:: -sendemail.validate:: -sendemail.xmailer:: - See linkgit:git-send-email[1] for description. - -sendemail.signedoffcc (deprecated):: - Deprecated alias for `sendemail.signedoffbycc`. - -sendemail.smtpBatchSize:: - Number of messages to be sent per connection, after that a relogin - will happen. If the value is 0 or undefined, send all messages in - one connection. - See also the `--batch-size` option of linkgit:git-send-email[1]. - -sendemail.smtpReloginDelay:: - Seconds wait before reconnecting to smtp server. - See also the `--relogin-delay` option of linkgit:git-send-email[1]. - -showbranch.default:: - The default set of branches for linkgit:git-show-branch[1]. - See linkgit:git-show-branch[1]. - -splitIndex.maxPercentChange:: - When the split index feature is used, this specifies the - 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 - shared index is never 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]. - -splitIndex.sharedIndexExpire:: - When the split index feature is used, shared index files that - were not modified since the time this variable specifies will - be removed when a new shared index file is created. The value - "now" expires all entries immediately, and "never" suppresses - expiration altogether. - The default value is "2.weeks.ago". - Note that a shared index file is considered modified (for the - purpose of expiration) each time a new split-index file is - either created based on it or read from it. - See linkgit:git-update-index[1]. - -status.relativePaths:: - By default, linkgit:git-status[1] shows paths relative to the - current directory. Setting this variable to `false` shows paths - relative to the repository root (this was the default for Git - prior to v1.5.4). - -status.short:: - Set to true to enable --short by default in linkgit:git-status[1]. - The option --no-short takes precedence over this variable. - -status.branch:: - Set to true to enable --branch by default in linkgit:git-status[1]. - The option --no-branch takes precedence over this variable. - -status.displayCommentPrefix:: - If set to true, linkgit:git-status[1] will insert a comment - prefix before each output line (starting with - `core.commentChar`, i.e. `#` by default). This was the - behavior of linkgit:git-status[1] in Git 1.8.4 and previous. - Defaults to false. - -status.renameLimit:: - The number of files to consider when performing rename detection - in linkgit:git-status[1] and linkgit:git-commit[1]. Defaults to - the value of diff.renameLimit. - -status.renames:: - Whether and how Git detects renames in linkgit:git-status[1] and - linkgit:git-commit[1] . If set to "false", rename detection is - disabled. If set to "true", basic rename detection is enabled. - If set to "copies" or "copy", Git will detect copies, as well. - Defaults to the value of diff.renames. - -status.showStash:: - If set to true, linkgit:git-status[1] will display the number of - entries currently stashed away. - Defaults to false. - -status.showUntrackedFiles:: - By default, linkgit:git-status[1] and linkgit:git-commit[1] show - files which are not currently tracked by Git. Directories which - 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 - the untracked files. Possible values are: -+ --- -* `no` - Show no untracked files. -* `normal` - Show untracked files and directories. -* `all` - Show also individual files in untracked directories. --- -+ -If this variable is not specified, it defaults to 'normal'. -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 - 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 - that the summary output command will be suppressed for all - submodules when `diff.ignoreSubmodules` is set to 'all' or only - for those submodules where `submodule.<name>.ignore=all`. The only - exception to that rule is that status and commit will show staged - submodule changes. To - also view the summary for ignored submodules you can either use - the --ignore-submodules=dirty command-line option or the 'git - submodule summary' command, which shows a similar output but does - not honor these settings. - -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]. - -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]. - -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 - 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. - -submodule.<name>.update:: - The method by which a submodule is updated by 'git submodule update', - which is the only affected command, others such as - 'git checkout --recurse-submodules' are unaffected. It exists for - historical reasons, when 'git submodule' was the only command to - interact with submodules; settings like `submodule.active` - and `pull.rebase` are more specific. It is populated by - `git submodule init` from the linkgit:gitmodules[5] file. - See description of 'update' command in linkgit:git-submodule[1]. - -submodule.<name>.branch:: - The remote branch name for a submodule, used by `git submodule - update --remote`. Set this option to override the value found in - the `.gitmodules` file. See linkgit:git-submodule[1] and - linkgit:gitmodules[5] for details. - -submodule.<name>.fetchRecurseSubmodules:: - This option can be used to control recursive fetching of this - submodule. It can be overridden by using the --[no-]recurse-submodules - command-line option to "git fetch" and "git pull". - This setting will override that from in the linkgit:gitmodules[5] - file. - -submodule.<name>.ignore:: - Defines under what circumstances "git status" and the diff family show - 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 - 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. - Using "none" (the default when this option is not set) also shows - submodules that have untracked files in their work tree as changed. - This setting overrides any setting made in .gitmodules for this submodule, - both settings can be overridden on the command line by using the - "--ignore-submodules" option. The 'git submodule' commands are not - affected by this setting. - -submodule.<name>.active:: - Boolean value indicating if the submodule is of interest to git - commands. This config option takes precedence over the - submodule.active config option. See linkgit:gitsubmodules[7] for - details. - -submodule.active:: - A repeated field which contains a pathspec used to match against a - submodule's path to determine if the submodule is of interest to git - 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, - except `clone`. - Defaults to false. - -submodule.fetchJobs:: - Specifies how many submodules are fetched/cloned at the same time. - A positive integer allows up to that number of submodules fetched - in parallel. A value of 0 will give some reasonable default. - If unset, it defaults to 1. - -submodule.alternateLocation:: - Specifies how the submodules obtain alternates when submodules are - cloned. Possible values are `no`, `superproject`. - By default `no` is assumed, which doesn't add references. When the - value is set to `superproject` the submodule to be cloned computes - its alternates location relative to the superprojects alternate. - -submodule.alternateErrorStrategy:: - Specifies how to treat errors with the alternates for a submodule - as computed via `submodule.alternateLocation`. Possible values are - `ignore`, `info`, `die`. Default is `die`. - -tag.forceSignAnnotated:: - A boolean to specify whether annotated tags created should be GPG signed. - If `--annotate` is specified on the command line, it takes - precedence over this option. - -tag.sort:: - This variable controls the sort ordering of tags when displayed by - linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the - value of this variable will be used as the default. - -tar.umask:: - This variable can be used to restrict the permission bits of - tar archive entries. The default is 0002, which turns off the - world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) and - linkgit:git-archive[1]. - -transfer.fsckObjects:: - When `fetch.fsckObjects` or `receive.fsckObjects` are - not set, the value of this variable is used instead. - Defaults to false. -+ -When set, the fetch or receive will abort in the case of a malformed -object or a link to a nonexistent object. In addition, various other -issues are checked for, including legacy issues (see `fsck.<msg-id>`), -and potential security issues like the existence of a `.GIT` directory -or a malicious `.gitmodules` file (see the release notes for v2.2.1 -and v2.17.1 for details). Other sanity and security checks may be -added in future releases. -+ -On the receiving side, failing fsckObjects will make those objects -unreachable, see "QUARANTINE ENVIRONMENT" in -linkgit:git-receive-pack[1]. On the fetch side, malformed objects will -instead be left unreferenced in the repository. -+ -Due to the non-quarantine nature of the `fetch.fsckObjects` -implementation it can not be relied upon to leave the object store -clean like `receive.fsckObjects` can. -+ -As objects are unpacked they're written to the object store, so there -can be cases where malicious objects get introduced even though the -"fetch" failed, only to have a subsequent "fetch" succeed because only -new incoming objects are checked, not those that have already been -written to the object store. That difference in behavior should not be -relied upon. In the future, such objects may be quarantined for -"fetch" as well. -+ -For now, the paranoid need to find some way to emulate the quarantine -environment if they'd like the same protection as "push". E.g. in the -case of an internal mirror do the mirroring in two steps, one to fetch -the untrusted objects, and then do a second "push" (which will use the -quarantine) to another internal repo, and have internal clients -consume this pushed-to repository, or embargo internal fetches and -only allow them once a full "fsck" has run (and no new fetches have -happened in the meantime). - -transfer.hideRefs:: - String(s) `receive-pack` and `upload-pack` use to decide which - refs to omit from their initial advertisements. Use more than - one definition to specify multiple prefix strings. A ref that is - under the hierarchies listed in the value of this variable is - excluded, and is hidden when responding to `git push` or `git - fetch`. See `receive.hideRefs` and `uploadpack.hideRefs` for - program-specific versions of this config. -+ -You may also include a `!` in front of the ref name to negate the entry, -explicitly exposing it, even if an earlier entry marked it as hidden. -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. -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. -+ -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 -linkgit:gitnamespaces[7] man page; it's best to keep private data in a -separate repository. - -transfer.unpackLimit:: - When `fetch.unpackLimit` or `receive.unpackLimit` are - not set, the value of this variable is used instead. - The default value is 100. - -uploadarchive.allowUnreachable:: - If true, allow clients to use `git archive --remote` to request - any tree, whether reachable from the ref tips or not. See the - discussion in the "SECURITY" section of - linkgit:git-upload-archive[1] for more details. Defaults to - `false`. - -uploadpack.hideRefs:: - This variable is the same as `transfer.hideRefs`, but applies - only to `upload-pack` (and so affects only fetches, not pushes). - An attempt to fetch a hidden ref by `git fetch` will fail. See - also `uploadpack.allowTipSHA1InWant`. - -uploadpack.allowTipSHA1InWant:: - When `uploadpack.hideRefs` is in effect, allow `upload-pack` - to accept a fetch request that asks for an object at the tip - of a hidden ref (by default, such a request is rejected). - See also `uploadpack.hideRefs`. Even if this is false, a client - may be able to steal objects via the techniques described in the - "SECURITY" section of the linkgit:gitnamespaces[7] man page; it's - best to keep private data in a separate repository. - -uploadpack.allowReachableSHA1InWant:: - Allow `upload-pack` to accept a fetch request that asks for an - object that is reachable from any ref tip. However, note that - calculating object reachability is computationally expensive. - Defaults to `false`. Even if this is false, a client may be able - to steal objects via the techniques described in the "SECURITY" - section of the linkgit:gitnamespaces[7] man page; it's best to - keep private data in a separate repository. - -uploadpack.allowAnySHA1InWant:: - Allow `upload-pack` to accept a fetch request that asks for any - object at all. - Defaults to `false`. - -uploadpack.keepAlive:: - When `upload-pack` has started `pack-objects`, there may be a - quiet period while `pack-objects` prepares the pack. Normally - it would output progress information, but if `--quiet` was used - for the fetch, `pack-objects` will output nothing at all until - the pack data begins. Some clients and networks may consider - the server to be hung and give up. Setting this option instructs - `upload-pack` to send an empty keepalive packet every - `uploadpack.keepAlive` seconds. Setting this option to 0 - disables keepalive packets entirely. The default is 5 seconds. - -uploadpack.packObjectsHook:: - If this option is set, when `upload-pack` would run - `git pack-objects` to create a packfile for a client, it will - run this shell command instead. The `pack-objects` command and - arguments it _would_ have run (including the `git pack-objects` - at the beginning) are appended to the shell command. The stdin - and stdout of the hook are treated as if `pack-objects` itself - was run. I.e., `upload-pack` will feed input intended for - `pack-objects` to the hook, and expects a completed packfile on - stdout. - -uploadpack.allowFilter:: - If this option is set, `upload-pack` will support partial - clone and partial fetch object filtering. -+ -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). - -uploadpack.allowRefInWant:: - If this option is set, `upload-pack` will support the `ref-in-want` - feature of the protocol version 2 `fetch` command. This feature - is intended for the benefit of load-balanced servers which may - not have the same view of what OIDs their refs point to due to - replication delay. - -url.<base>.insteadOf:: - Any URL that starts with this value will be rewritten to - start, instead, with <base>. In cases where some site serves a - large number of repositories, and serves them with multiple - access methods, and some users need to use different access - methods, this feature allows people to specify any of the - equivalent URLs and have Git automatically rewrite the URL to - the best alternative for the particular user, even for a - never-before-seen repository on the site. When more than one - insteadOf strings match a given URL, the longest match is used. -+ -Note that any protocol restrictions will be applied to the rewritten -URL. If the rewrite changes the URL to use a custom protocol or remote -helper, you may need to adjust the `protocol.*.allow` config to permit -the request. In particular, protocols you expect to use for submodules -must be set to `always` rather than the default of `user`. See the -description of `protocol.allow` above. - -url.<base>.pushInsteadOf:: - Any URL that starts with this value will not be pushed to; - instead, it will be rewritten to start with <base>, and the - resulting URL will be pushed to. In cases where some site serves - a large number of repositories, and serves them with multiple - access methods, some of which do not allow push, this feature - allows people to specify a pull-only URL and have Git - automatically use an appropriate URL to push, even for a - never-before-seen repository on the site. When more than one - pushInsteadOf strings match a given URL, the longest match is - used. If a remote has an explicit pushurl, Git will ignore this - setting for that remote. - -user.email:: - Your email address to be recorded in any newly created commits. - Can be overridden by the `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_EMAIL`, and - `EMAIL` environment variables. See linkgit:git-commit-tree[1]. - -user.name:: - Your full name to be recorded in any newly created commits. - Can be overridden by the `GIT_AUTHOR_NAME` and `GIT_COMMITTER_NAME` - environment variables. See linkgit:git-commit-tree[1]. - -user.useConfigOnly:: - Instruct Git to avoid trying to guess defaults for `user.email` - and `user.name`, and instead retrieve the values only from the - configuration. For example, if you have multiple email addresses - and would like to use a different one for each repository, then - with this configuration option set to `true` in the global config - along with a name, Git will prompt you to set up an email before - making new commits in a newly cloned repository. - Defaults to `false`. - -user.signingKey:: - If linkgit:git-tag[1] or linkgit:git-commit[1] is not selecting the - key you want it to automatically when creating a signed tag or - 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. - -versionsort.prereleaseSuffix (deprecated):: - Deprecated alias for `versionsort.suffix`. Ignored if - `versionsort.suffix` is set. - -versionsort.suffix:: - Even when version sort is used in linkgit:git-tag[1], tagnames - with the same base version but different suffixes are still sorted - lexicographically, resulting e.g. in prerelease tags appearing - after the main release (e.g. "1.0-rc1" after "1.0"). This - variable can be specified to determine the sorting order of tags - with different suffixes. -+ -By specifying a single suffix in this variable, any tagname containing -that suffix will appear before the corresponding main release. E.g. if -the variable is set to "-rc", then all "1.0-rcX" tags will appear before -"1.0". If specified multiple times, once per suffix, then the order of -suffixes in the configuration will determine the sorting order of tagnames -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 -"-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 -be sorted according to the suffix which starts at the earliest position in -the tagname. If more than one different matching suffixes start 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 -in multiple config files. - -web.browser:: - Specify a web browser that may be used by some commands. - Currently only linkgit:git-instaweb[1] and linkgit:git-help[1] - may use it. - -worktree.guessRemote:: - With `add`, if no branch argument, and neither of `-b` nor - `-B` nor `--detach` are given, the command defaults to - creating a new branch from HEAD. If `worktree.guessRemote` is - set to true, `worktree add` tries to find a remote-tracking - branch whose name uniquely matches the new branch name. If - such a branch exists, it is checked out and set as "upstream" - for the new branch. If no such match can be found, it falls - back to creating a new branch from the current HEAD. +include::config/feature.txt[] + +include::config/fetch.txt[] + +include::config/format.txt[] + +include::config/filter.txt[] + +include::config/fsck.txt[] + +include::config/gc.txt[] + +include::config/gitcvs.txt[] + +include::config/gitweb.txt[] + +include::config/grep.txt[] + +include::config/gpg.txt[] + +include::config/gui.txt[] + +include::config/guitool.txt[] + +include::config/help.txt[] + +include::config/http.txt[] + +include::config/i18n.txt[] + +include::config/imap.txt[] + +include::config/index.txt[] + +include::config/init.txt[] + +include::config/instaweb.txt[] + +include::config/interactive.txt[] + +include::config/log.txt[] + +include::config/mailinfo.txt[] + +include::config/mailmap.txt[] + +include::config/man.txt[] + +include::config/merge.txt[] + +include::config/mergetool.txt[] + +include::config/notes.txt[] + +include::config/pack.txt[] + +include::config/pager.txt[] + +include::config/pretty.txt[] + +include::config/protocol.txt[] + +include::config/pull.txt[] + +include::config/push.txt[] + +include::config/rebase.txt[] + +include::config/receive.txt[] + +include::config/remote.txt[] + +include::config/remotes.txt[] + +include::config/repack.txt[] + +include::config/rerere.txt[] + +include::config/reset.txt[] + +include::config/sendemail.txt[] + +include::config/sequencer.txt[] + +include::config/showbranch.txt[] + +include::config/splitindex.txt[] + +include::config/ssh.txt[] + +include::config/status.txt[] + +include::config/stash.txt[] + +include::config/submodule.txt[] + +include::config/tag.txt[] + +include::config/tar.txt[] + +include::config/trace2.txt[] + +include::config/transfer.txt[] + +include::config/uploadarchive.txt[] + +include::config/uploadpack.txt[] + +include::config/url.txt[] + +include::config/user.txt[] + +include::config/versionsort.txt[] + +include::config/web.txt[] + +include::config/worktree.txt[] diff --git a/Documentation/config/add.txt b/Documentation/config/add.txt new file mode 100644 index 0000000000..c9f748f81c --- /dev/null +++ b/Documentation/config/add.txt @@ -0,0 +1,12 @@ +add.ignoreErrors:: +add.ignore-errors (deprecated):: + Tells 'git add' to continue adding files when some files cannot be + added due to indexing errors. Equivalent to the `--ignore-errors` + option of linkgit:git-add[1]. `add.ignore-errors` is deprecated, + as it does not follow the usual naming convention for configuration + 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. diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt new file mode 100644 index 0000000000..bdd37c3eaa --- /dev/null +++ b/Documentation/config/advice.txt @@ -0,0 +1,119 @@ +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': ++ +-- + fetchShowForcedUpdates:: + Advice 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', and 'pushNeedsForce' + 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. + pushAlreadyExists:: + Shown when linkgit:git-push[1] rejects an update that + does not qualify for fast-forwarding (e.g., a tag.) + pushFetchFirst:: + Shown when linkgit:git-push[1] rejects an update that + tries to overwrite a remote ref that points at an + object we do not have. + pushNeedsForce:: + Shown when linkgit:git-push[1] rejects an update that + 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. + 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 + source object. + statusAheadBehind:: + Shown when linkgit:git-status[1] computes the ahead/behind + counts for a local ref compared to its remote tracking ref, + and that calculation takes longer than expected. Will not + appear if `status.aheadBehind` is false or the option + `--no-ahead-behind` is given. + statusHints:: + Show directions on how to proceed from the current + state in the output of linkgit:git-status[1], in + 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. + 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. + submoduleAlternateErrorStrategyDie:: + Advice 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. +-- diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt new file mode 100644 index 0000000000..f1ca739d57 --- /dev/null +++ b/Documentation/config/alias.txt @@ -0,0 +1,28 @@ +alias.*:: + Command aliases for the linkgit:git[1] command wrapper - e.g. + after defining `alias.last = cat-file commit HEAD`, the invocation + `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. + 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 +command. It can be a command-line option that will be passed into the +invocation of `git`. In particular, this is useful when used with `-c` +to pass in one-time configurations or `-p` to force pagination. For example, +`loud-rebase = -c commit.verbose=true rebase` can be defined such that +running `git loud-rebase` would be equivalent to +`git -c commit.verbose=true rebase`. Also, `ps = -p status` would be a +helpful alias since `git ps` would paginate the output of `git status` +where the original command does not. ++ +If the alias expansion is prefixed with an exclamation point, +it will be treated as a shell command. For example, defining +`alias.new = !gitk --all --not ORIG_HEAD`, the invocation +`git new` is equivalent to running the shell command +`gitk --all --not ORIG_HEAD`. Note that shell commands will be +executed from the top-level directory of a repository, which may +not necessarily be the current directory. +`GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` +from the original current directory. See linkgit:git-rev-parse[1]. diff --git a/Documentation/config/am.txt b/Documentation/config/am.txt new file mode 100644 index 0000000000..5bcad2efb1 --- /dev/null +++ b/Documentation/config/am.txt @@ -0,0 +1,14 @@ +am.keepcr:: + If true, git-am will call git-mailsplit for patches in mbox format + with parameter `--keep-cr`. In this case git-mailsplit will + not remove `\r` from lines ending with `\r\n`. Can be overridden + by giving `--no-keep-cr` from the command line. + See linkgit:git-am[1], linkgit:git-mailsplit[1]. + +am.threeWay:: + By default, `git am` will fail if the patch does not apply cleanly. When + set to true, this setting tells `git am` to fall back on 3-way merge if + the patch records the identity of blobs it is supposed to apply to and + we have those blobs available locally (equivalent to giving the `--3way` + option from the command line). Defaults to `false`. + See linkgit:git-am[1]. diff --git a/Documentation/config/apply.txt b/Documentation/config/apply.txt new file mode 100644 index 0000000000..8fb8ef763d --- /dev/null +++ b/Documentation/config/apply.txt @@ -0,0 +1,11 @@ +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 + respect all whitespace differences. + See linkgit:git-apply[1]. + +apply.whitespace:: + Tells 'git apply' how to handle whitespaces, in the same way + as the `--whitespace` option. See linkgit:git-apply[1]. diff --git a/Documentation/config/blame.txt b/Documentation/config/blame.txt new file mode 100644 index 0000000000..9468e8599c --- /dev/null +++ b/Documentation/config/blame.txt @@ -0,0 +1,37 @@ +blame.blankBoundary:: + Show blank commit object name for boundary commits in + linkgit:git-blame[1]. This option defaults to false. + +blame.coloring:: + This determines the coloring scheme to be applied to blame + output. It can be 'repeatedLines', 'highlightRecent', + or 'none' which is the default. + +blame.date:: + Specifies the format used to output dates in linkgit:git-blame[1]. + If unset the iso format is used. For supported values, + see the discussion of the `--date` option at linkgit:git-log[1]. + +blame.showEmail:: + Show the author email instead of author name in linkgit:git-blame[1]. + This option defaults to false. + +blame.showRoot:: + Do not treat root commits as boundaries in linkgit:git-blame[1]. + This option defaults to false. + +blame.ignoreRevsFile:: + Ignore revisions listed in the file, one unabbreviated object name per + line, in linkgit:git-blame[1]. Whitespace and comments beginning with + `#` are ignored. This option may be repeated multiple times. Empty + file names will reset the list of ignored revisions. This option will + be handled before the command line option `--ignore-revs-file`. + +blame.markUnblamables:: + Mark lines that were changed by an ignored revision that we could not + attribute to another commit with a '*' in the output of + linkgit:git-blame[1]. + +blame.markIgnoredLines:: + Mark lines that were changed by an ignored revision that we attributed to + another commit with a '?' in the output of linkgit:git-blame[1]. diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt new file mode 100644 index 0000000000..cc5f3249fc --- /dev/null +++ b/Documentation/config/branch.txt @@ -0,0 +1,103 @@ +branch.autoSetupMerge:: + Tells 'git branch', 'git switch' and 'git checkout' to set up new branches + so that linkgit:git-pull[1] will appropriately merge from the + starting point branch. Note that even if this option is not set, + this behavior can be chosen per-branch using the `--track` + and `--no-track` options. The valid settings are: `false` -- no + 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. + +branch.autoSetupRebase:: + When a new branch is created with 'git branch', 'git switch' or 'git checkout' + that tracks another branch, this variable tells Git to set + up pull to rebase instead of merge (see "branch.<name>.rebase"). + When `never`, rebase is never automatically set to true. + When `local`, rebase is set to true for tracked branches of + other local branches. + When `remote`, rebase is set to true for tracked branches of + remote-tracking branches. + When `always`, rebase will be set to true for all tracking + branches. + See "branch.autoSetupMerge" for details on how to set up a + branch to track another branch. + This option defaults to never. + +branch.sort:: + This variable controls the sort ordering of branches when displayed by + linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the + value of this variable will be used as the default. + See linkgit:git-for-each-ref[1] field names for valid values. + +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 + 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. + Additionally, `.` (a period) is the current local repository + (a dot-repository), see `branch.<name>.merge`'s final note below. + +branch.<name>.pushRemote:: + When on branch <name>, it overrides `branch.<name>.remote` for + pushing. It also overrides `remote.pushDefault` for pushing + from branch <name>. When you pull from one place (e.g. your + upstream) and push to another place (e.g. your own publishing + repository), you would want to set `remote.pushDefault` to + specify the remote to push to for all branches, and use this + option to override it for a specific branch. + +branch.<name>.merge:: + Defines, together with branch.<name>.remote, the upstream branch + for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which + branch to merge and can also affect 'git push' (see push.default). + When in branch <name>, it tells 'git fetch' the default + refspec to be marked for merging in FETCH_HEAD. The value is + 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 + '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. + If you wish to setup 'git pull' so that it merges into <name> from + another branch in the local repository, you can point + branch.<name>.merge to the desired branch, and use the relative path + setting `.` (a period) for branch.<name>.remote. + +branch.<name>.mergeOptions:: + Sets default options for merging into branch <name>. The syntax and + supported options are the same as those of linkgit:git-merge[1], but + option values containing whitespace characters are currently not + supported. + +branch.<name>.rebase:: + When true, rebase the branch <name> on top of the fetched branch, + instead of merging the default branch from the default remote when + "git pull" is run. See "pull.rebase" for doing this in a non + branch-specific manner. ++ +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. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +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 + request-pull summary. diff --git a/Documentation/config/browser.txt b/Documentation/config/browser.txt new file mode 100644 index 0000000000..195df207a6 --- /dev/null +++ b/Documentation/config/browser.txt @@ -0,0 +1,9 @@ +browser.<tool>.cmd:: + Specify the command to invoke the specified browser. The + specified command is evaluated in shell with the URLs passed + as arguments. (See linkgit:git-web{litdd}browse[1].) + +browser.<tool>.path:: + Override the path for the given tool that may be used to + browse HTML help (see `-w` option in linkgit:git-help[1]) or a + working repository in gitweb (see linkgit:git-instaweb[1]). diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt new file mode 100644 index 0000000000..6b646813ab --- /dev/null +++ b/Documentation/config/checkout.txt @@ -0,0 +1,18 @@ +checkout.defaultRemote:: + When you run 'git checkout <something>' + or 'git switch <something>' and only have one + remote, it may implicitly fall back on checking out and + tracking e.g. 'origin/<something>'. This stops working as soon + as you have more than one remote with a '<something>' + reference. This setting allows for setting the name of a + preferred remote that should always win when it comes to + disambiguation. The typical use-case is to set this to + `origin`. ++ +Currently this is used by linkgit:git-switch[1] and +linkgit:git-checkout[1] when 'git checkout <something>' +or 'git switch <something>' +will checkout the '<something>' branch on another remote, +and by linkgit:git-worktree[1] when 'git worktree add' refers to a +remote branch. This setting might be used for other checkout-like +commands or functionality in the future. diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.txt new file mode 100644 index 0000000000..a807c925b9 --- /dev/null +++ b/Documentation/config/clean.txt @@ -0,0 +1,3 @@ +clean.requireForce:: + A boolean to make git-clean do nothing unless given -f, + -i or -n. Defaults to true. diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt new file mode 100644 index 0000000000..d5daacb13a --- /dev/null +++ b/Documentation/config/color.txt @@ -0,0 +1,201 @@ +color.advice:: + A boolean to enable/disable color in hints (e.g. when a push + failed, see `advice.*` for a list). May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors + are used only when the error output goes to a terminal. If + unset, then the value of `color.ui` is used (`auto` by default). + +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. ++ +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. ++ +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. + +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. + +color.branch:: + A boolean to enable/disable color in the output of + linkgit:git-branch[1]. May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors are used + only when the output is to a terminal. If unset, then the + value of `color.ui` is used (`auto` by default). + +color.branch.<slot>:: + Use customized color for branch coloration. `<slot>` is one of + `current` (the current branch), `local` (a local branch), + `remote` (a remote-tracking branch in refs/remotes/), + `upstream` (upstream tracking branch), `plain` (other + refs). + +color.diff:: + Whether to use ANSI escape sequences to add color to patches. + If this is set to `always`, linkgit:git-diff[1], + linkgit:git-log[1], and linkgit:git-show[1] will use color + for all patches. If it is set to `true` or `auto`, those + commands will only use color when output is to the terminal. + If unset, then the value of `color.ui` is used (`auto` by + default). ++ +This does not affect linkgit:git-format-patch[1] or the +'git-diff-{asterisk}' plumbing commands. Can be overridden on the +command line with the `--color[=<when>]` option. + +color.diff.<slot>:: + Use customized color for diff colorization. `<slot>` specifies + which part of the patch to use the specified color, and is one + of `context` (context text - `plain` is a historical synonym), + `meta` (metainformation), `frag` + (hunk header), 'func' (function in hunk header), `old` (removed lines), + `new` (added lines), `commit` (commit headers), `whitespace` + (highlighting whitespace errors), `oldMoved` (deleted lines), + `newMoved` (added lines), `oldMovedDimmed`, `oldMovedAlternative`, + `oldMovedAlternativeDimmed`, `newMovedDimmed`, `newMovedAlternative` + `newMovedAlternativeDimmed` (See the '<mode>' + setting of '--color-moved' in linkgit:git-diff[1] for details), + `contextDimmed`, `oldDimmed`, `newDimmed`, `contextBold`, + `oldBold`, and `newBold` (see linkgit:git-range-diff[1] for details). + +color.decorate.<slot>:: + Use customized color for 'git log --decorate' output. `<slot>` is one + of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local + branches, remote-tracking branches, tags, stash and HEAD, respectively + and `grafted` for grafted commits. + +color.grep:: + When set to `always`, always highlight matches. When `false` (or + `never`), never. When set to `true` or `auto`, use color only + when the output is written to the terminal. If unset, then the + value of `color.ui` is used (`auto` by default). + +color.grep.<slot>:: + Use customized color for grep colorization. `<slot>` specifies which + part of the line to use the specified color, and is one of ++ +-- +`context`;; + non-matching text in context lines (when using `-A`, `-B`, or `-C`) +`filename`;; + filename prefix (when not using `-h`) +`function`;; + function name lines (when using `-p`) +`lineNumber`;; + line number prefix (when using `-n`) +`column`;; + column number prefix (when using `--column`) +`match`;; + matching text (same as setting `matchContext` and `matchSelected`) +`matchContext`;; + matching text in context lines +`matchSelected`;; + matching text in selected lines +`selected`;; + non-matching text in selected lines +`separator`;; + separators between fields on a line (`:`, `-`, and `=`) + and between hunks (`--`) +-- + +color.interactive:: + When set to `always`, always use colors for interactive prompts + and displays (such as those used by "git-add --interactive" and + "git-clean --interactive"). When false (or `never`), never. + When set to `true` or `auto`, use colors only when the output is + to the terminal. If unset, then the value of `color.ui` is + used (`auto` by default). + +color.interactive.<slot>:: + Use customized color for 'git add --interactive' and 'git clean + --interactive' output. `<slot>` may be `prompt`, `header`, `help` + or `error`, for four distinct types of normal output from + interactive commands. + +color.pager:: + A boolean to enable/disable colored output when the pager is in + use (default is true). + +color.push:: + A boolean to enable/disable color in push errors. May be set to + `always`, `false` (or `never`) or `auto` (or `true`), in which + case colors are used only when the error output goes to a terminal. + If unset, then the value of `color.ui` is used (`auto` by default). + +color.push.error:: + Use customized color for push errors. + +color.remote:: + If set, keywords at the start of the line are highlighted. The + keywords are "error", "warning", "hint" and "success", and are + matched case-insensitively. May be set to `always`, `false` (or + `never`) or `auto` (or `true`). If unset, then the value of + `color.ui` is used (`auto` by default). + +color.remote.<slot>:: + Use customized color for each remote keyword. `<slot>` may be + `hint`, `warning`, `success` or `error` which match the + corresponding keyword. + +color.showBranch:: + A boolean to enable/disable color in the output of + linkgit:git-show-branch[1]. May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors are used + only when the output is to a terminal. If unset, then the + value of `color.ui` is used (`auto` by default). + +color.status:: + A boolean to enable/disable color in the output of + linkgit:git-status[1]. May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors are used + only when the output is to a terminal. If unset, then the + value of `color.ui` is used (`auto` by default). + +color.status.<slot>:: + Use customized color for status colorization. `<slot>` is + one of `header` (the header text of the status message), + `added` or `updated` (files which are added but not committed), + `changed` (files which are changed but not added in the index), + `untracked` (files which are not tracked by Git), + `branch` (the current branch), + `nobranch` (the color the 'no branch' warning is shown in, defaulting + to red), + `localBranch` or `remoteBranch` (the local and remote branch names, + respectively, when branch and tracking information is displayed in the + status short-format), or + `unmerged` (files which have unmerged changes). + +color.transport:: + A boolean to enable/disable color when pushes are rejected. May be + set to `always`, `false` (or `never`) or `auto` (or `true`), in which + case colors are used only when the error output goes to a terminal. + If unset, then the value of `color.ui` is used (`auto` by default). + +color.transport.rejected:: + Use customized color when a push was rejected. + +color.ui:: + This variable determines the default value for variables such + as `color.diff` and `color.grep` that control the use of color + per command family. Its scope will expand as more commands learn + configuration to set a default for the `--color` option. Set it + to `false` or `never` if you prefer Git commands not to use + color unless enabled explicitly with some other configuration + or the `--color` option. Set it to `always` if you want all + output not intended for machine consumption to use color, to + `true` or `auto` (this is the default since Git 1.8.4) if you + want such output to use color when written to the terminal. diff --git a/Documentation/config/column.txt b/Documentation/config/column.txt new file mode 100644 index 0000000000..76aa2f29dc --- /dev/null +++ b/Documentation/config/column.txt @@ -0,0 +1,55 @@ +column.ui:: + Specify whether supported commands should output in columns. + This variable consists of a list of tokens separated by spaces + or commas: ++ +These options control when the feature should be enabled +(defaults to 'never'): ++ +-- +`always`;; + always show in columns +`never`;; + never show in columns +`auto`;; + show in columns if the output is to the terminal +-- ++ +These options control layout (defaults to 'column'). Setting any +of these implies 'always' if none of 'always', 'never', or 'auto' are +specified. ++ +-- +`column`;; + fill columns before rows +`row`;; + fill rows before columns +`plain`;; + show in one column +-- ++ +Finally, these options can be combined with a layout option (defaults +to 'nodense'): ++ +-- +`dense`;; + make unequal size columns to utilize more space +`nodense`;; + make equal size columns +-- + +column.branch:: + Specify whether to output branch listing in `git branch` in columns. + See `column.ui` for details. + +column.clean:: + Specify the layout when list items in `git clean -i`, which always + shows files and directories in columns. See `column.ui` for details. + +column.status:: + Specify whether to output untracked files in `git status` in columns. + See `column.ui` for details. + +column.tag:: + Specify whether to output tag listing in `git tag` in columns. + See `column.ui` for details. diff --git a/Documentation/config/commit.txt b/Documentation/config/commit.txt new file mode 100644 index 0000000000..2c95573930 --- /dev/null +++ b/Documentation/config/commit.txt @@ -0,0 +1,29 @@ +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 + 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). + +commit.gpgSign:: + + A boolean to specify whether all commits should be GPG signed. + Use of this option when doing operations such as rebase can + result in a large number of commits being signed. It may be + convenient to use an agent to avoid typing your GPG passphrase + several times. + +commit.status:: + A boolean to enable/disable inclusion of status information in the + commit message template when using an editor to prepare the commit + message. Defaults to true. + +commit.template:: + Specify the pathname of a file to use as the template for + new commit messages. + +commit.verbose:: + A boolean or int to specify the level of verbose with `git commit`. + See linkgit:git-commit[1]. diff --git a/Documentation/config/completion.txt b/Documentation/config/completion.txt new file mode 100644 index 0000000000..4d99bf33c9 --- /dev/null +++ b/Documentation/config/completion.txt @@ -0,0 +1,7 @@ +completion.commands:: + This is only used by git-completion.bash to add or remove + commands from the list of completed commands. Normally only + porcelain commands and a few select others are completed. You + can add more commands, separated by space, in this + variable. Prefixing the command with '-' will remove it from + the existing list. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt new file mode 100644 index 0000000000..74619a9c03 --- /dev/null +++ b/Documentation/config/core.txt @@ -0,0 +1,628 @@ +core.fileMode:: + Tells Git if the executable bit of files in the working tree + is to be honored. ++ +Some filesystems lose the executable bit when a file that is +marked as executable is checked out, or checks out a +non-executable file with executable bit on. +linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem +to see if it handles the executable bit correctly +and this variable is automatically set as necessary. ++ +A repository, however, may be on a filesystem that handles +the filemode correctly, and this variable is set to 'true' +when created, but later may be made accessible from another +environment that loses the filemode (e.g. exporting ext4 via +CIFS mount, visiting a Cygwin created repository with +Git for Windows or Eclipse). +In such a case it may be necessary to set this variable to 'false'. +See linkgit:git-update-index[1]. ++ +The default is true (when core.filemode is not specified in the config file). + +core.hideDotFiles:: + (Windows-only) If true, mark newly-created directories and files whose + name starts with a dot as hidden. If 'dotGitOnly', only the `.git/` + directory is hidden, but no other files starting with a dot. The + default mode is 'dotGitOnly'. + +core.ignoreCase:: + Internal variable which enables various workarounds to enable + Git to work better on filesystems that are not case sensitive, + like APFS, HFS+, FAT, NTFS, etc. For example, if a directory listing + finds "makefile" when Git expects "Makefile", Git will assume + it is really the same file, and continue to remember it as + "Makefile". ++ +The default is false, except linkgit:git-clone[1] or linkgit:git-init[1] +will probe and set core.ignoreCase true if appropriate when the repository +is created. ++ +Git relies on the proper configuration of this variable for your operating +and file system. Modifying this value may result in unexpected behavior. + +core.precomposeUnicode:: + This option is only used by Mac OS implementation of Git. + When core.precomposeUnicode=true, Git reverts the unicode decomposition + of filenames done by Mac OS. This is useful when sharing a repository + between Mac OS and Linux or Windows. + (Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). + When false, file names are handled fully transparent by Git, + which is backward compatible with older versions of Git. + +core.protectHFS:: + If set to true, do not allow checkout of paths that would + be considered equivalent to `.git` on an HFS+ filesystem. + Defaults to `true` on Mac OS, and `false` elsewhere. + +core.protectNTFS:: + If set to true, do not allow checkout of paths that would + cause problems with the NTFS filesystem, e.g. conflict with + 8.3 "short" names. + 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]. + +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. + +core.trustctime:: + If false, the ctime differences between the index and the + working tree are ignored; useful when the inode change time + is regularly modified by something outside Git (file system + crawlers and some backup systems). + See linkgit:git-update-index[1]. True by default. + +core.splitIndex:: + If true, the split-index feature of the index will be used. + See linkgit:git-update-index[1]. False by default. + +core.untrackedCache:: + Determines what to do about the untracked cache feature of the + index. It will be kept, if this variable is unset or set to + `keep`. It will automatically be added if set to `true`. And + it will automatically be removed, if set to `false`. Before + setting it to `true`, you should check that mtime is working + properly on your system. + See linkgit:git-update-index[1]. `keep` by default, unless + `feature.manyFiles` is enabled which sets this setting to + `true` by default. + +core.checkStat:: + When missing or is set to `default`, many fields in the stat + structure are checked to detect if a file has been modified + since Git looked at it. When this configuration variable is + set to `minimal`, sub-second part of mtime and ctime, the + uid and gid of the owner of the file, the inode number (and + the device number, if Git was compiled to use it), are + excluded from the check among these fields, leaving only the + whole-second part of mtime (and ctime, if `core.trustCtime` + is set) and the filesize to be checked. ++ +There are implementations of Git that do not leave usable values in +some fields (e.g. JGit); by excluding these fields from the +comparison, the `minimal` mode may help interoperability when the +same repository is used by these other systems at the same time. + +core.quotePath:: + Commands that output paths (e.g. 'ls-files', 'diff'), will + quote "unusual" characters in the pathname by enclosing the + pathname in double-quotes and escaping those characters with + backslashes in the same way C escapes control characters (e.g. + `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with + values larger than 0x80 (e.g. octal `\302\265` for "micro" in + UTF-8). If this variable is set to false, bytes higher than + 0x80 are not considered "unusual" any more. Double-quotes, + backslash and control characters are always escaped regardless + of the setting of this variable. A simple space character is + not considered "unusual". Many commands can output pathnames + completely verbatim using the `-z` option. The default value + is true. + +core.eol:: + Sets the line ending type to use in the working directory for + files that are marked as text (either by having the `text` + attribute set, or by having `text=auto` and Git auto-detecting + the contents as text). + Alternatives are 'lf', 'crlf' and 'native', which uses the platform's + native line ending. The default value is `native`. See + linkgit:gitattributes[5] for more information on end-of-line + conversion. Note that this value is ignored if `core.autocrlf` + is set to `true` or `input`. + +core.safecrlf:: + If true, makes Git check if converting `CRLF` is reversible when + end-of-line conversion is active. Git will verify if a command + modifies a file in the work tree either directly or indirectly. + For example, committing a file followed by checking out the + same file should yield the original file in the work tree. If + this is not the case for the current setting of + `core.autocrlf`, Git will reject the file. The variable can + be set to "warn", in which case Git will only warn about an + irreversible conversion but continue the operation. ++ +CRLF conversion bears a slight chance of corrupting data. +When it is enabled, Git will convert CRLF to LF during commit and LF to +CRLF during checkout. A file that contains a mixture of LF and +CRLF before the commit cannot be recreated by Git. For text +files this is the right thing to do: it corrects line endings +such that we have only LF line endings in the repository. +But for binary files that are accidentally classified as text the +conversion can corrupt data. ++ +If you recognize such corruption early you can easily fix it by +setting the conversion type explicitly in .gitattributes. Right +after committing you still have the original file in your work +tree and this file is not yet corrupted. You can explicitly tell +Git that this file is binary and Git will handle the file +appropriately. ++ +Unfortunately, the desired effect of cleaning up text files with +mixed line endings and the undesired effect of corrupting binary +files cannot be distinguished. In both cases CRLFs are removed +in an irreversible way. For text files this is the right thing +to do because CRLFs are line endings, while for binary files +converting CRLFs corrupts data. ++ +Note, this safety check does not mean that a checkout will generate a +file identical to the original file for a different setting of +`core.eol` and `core.autocrlf`, but only for the current one. For +example, a text file with `LF` would be accepted with `core.eol=lf` +and could later be checked out with `core.eol=crlf`, in which case the +resulting file would contain `CRLF`, although the original file +contained `LF`. However, in both work trees the line endings would be +consistent, that is either all `LF` or all `CRLF`, but never mixed. A +file with mixed line endings would be reported by the `core.safecrlf` +mechanism. + +core.autocrlf:: + Setting this variable to "true" is the same as setting + the `text` attribute to "auto" on all files and core.eol to "crlf". + Set to true if you want to have `CRLF` line endings in your + working directory and the repository has LF line endings. + This variable can be set to 'input', + in which case no output conversion is performed. + +core.checkRoundtripEncoding:: + A comma and/or whitespace separated list of encodings that Git + performs UTF-8 round trip checks on if they are used in an + `working-tree-encoding` attribute (see linkgit:gitattributes[5]). + The default value is `SHIFT-JIS`. + +core.symlinks:: + If false, symbolic links are checked out as small plain files that + contain the link text. linkgit:git-update-index[1] and + linkgit:git-add[1] will not change the recorded type to regular + file. Useful on filesystems like FAT that do not support + symbolic links. ++ +The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] +will probe and set core.symlinks false if appropriate when the repository +is created. + +core.gitProxy:: + A "proxy command" to execute (as 'command host port') instead + of establishing direct connection to the remote server when + using the Git protocol for fetching. If the variable value is + in the "COMMAND for DOMAIN" format, the command is applied only + on hostnames ending with the specified domain string. This variable + may be set multiple times and is matched in the given order; + the first match wins. ++ +Can be overridden by the `GIT_PROXY_COMMAND` environment variable +(which always applies universally, without the special "for" +handling). ++ +The special string `none` can be used as the proxy command to +specify that no proxy be used for a given domain pattern. +This is useful for excluding servers inside a firewall from +proxy use, while defaulting to a common proxy for external domains. + +core.sshCommand:: + If this variable is set, `git fetch` and `git push` will + use the specified command instead of `ssh` when they need to + connect to a remote system. The command is in the same form as + the `GIT_SSH_COMMAND` environment variable and is overridden + when the environment variable is set. + +core.ignoreStat:: + If true, Git will avoid using lstat() calls to detect if files have + changed by setting the "assume-unchanged" bit for those tracked files + which it has updated identically in both the index and working tree. ++ +When files are modified outside of Git, the user will need to stage +the modified files explicitly (e.g. see 'Examples' section in +linkgit:git-update-index[1]). +Git will not normally detect changes to those files. ++ +This is useful on systems where lstat() calls are very slow, such as +CIFS/Microsoft Windows. ++ +False by default. + +core.preferSymlinkRefs:: + Instead of the default "symref" format for HEAD + and other symbolic reference files, use symbolic links. + This is sometimes needed to work with old scripts that + expect HEAD to be a symbolic link. + +core.alternateRefsCommand:: + When advertising tips of available history from an alternate, use the shell to + execute the specified command instead of linkgit:git-for-each-ref[1]. The + first argument is the absolute path of the alternate. Output must contain one + hex object id per line (i.e., the same as produced by `git for-each-ref + --format='%(objectname)'`). ++ +Note that you cannot generally put `git for-each-ref` directly into the config +value, as it does not take a repository path as an argument (but you can wrap +the command above in a shell script). + +core.alternateRefsPrefixes:: + When listing references from an alternate, list only references that begin + with the given prefix. Prefixes match as if they were given as arguments to + linkgit:git-for-each-ref[1]. To list multiple prefixes, separate them with + whitespace. If `core.alternateRefsCommand` is set, setting + `core.alternateRefsPrefixes` has no effect. + +core.bare:: + If true this repository is assumed to be 'bare' and has no + working directory associated with it. If this is the case a + number of commands that require a working directory will be + disabled, such as linkgit:git-add[1] or linkgit:git-merge[1]. ++ +This setting is automatically guessed by linkgit:git-clone[1] or +linkgit:git-init[1] when the repository was created. By default a +repository that ends in "/.git" is assumed to be not bare (bare = +false), while all other repositories are assumed to be bare (bare += true). + +core.worktree:: + Set the path to the root of the working tree. + If `GIT_COMMON_DIR` environment variable is set, core.worktree + is ignored and not used for determining the root of working tree. + This can be overridden by the `GIT_WORK_TREE` environment + variable and the `--work-tree` command-line option. + The value can be an absolute path or relative to the path to + the .git directory, which is either specified by --git-dir + or GIT_DIR, or automatically discovered. + If --git-dir or GIT_DIR is specified but none of + --work-tree, GIT_WORK_TREE and core.worktree is specified, + the current working directory is regarded as the top level + of your working tree. ++ +Note that this variable is honored even when set in a configuration +file in a ".git" subdirectory of a directory and its value differs +from the latter directory (e.g. "/path/to/.git/config" has +core.worktree set to "/different/path"), which is most likely a +misconfiguration. Running Git commands in the "/path/to" directory will +still use "/different/path" as the root of the work tree and can cause +confusion unless you know what you are doing (e.g. you are creating a +read-only snapshot of the same index to a location different from the +repository's usual working tree). + +core.logAllRefUpdates:: + Enable the reflog. Updates to a ref <ref> is logged to the file + "`$GIT_DIR/logs/<ref>`", by appending the new and old + SHA-1, the date/time and the reason of the update, but + only when the file exists. If this configuration + variable is set to `true`, missing "`$GIT_DIR/logs/<ref>`" + file is automatically created for branch heads (i.e. under + `refs/heads/`), remote refs (i.e. under `refs/remotes/`), + note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`. + If it is set to `always`, then a missing reflog is automatically + created for any ref under `refs/`. ++ +This information can be used to determine what commit +was the tip of a branch "2 days ago". ++ +This value is true by default in a repository that has +a working directory associated with it, and false by +default in a bare repository. + +core.repositoryFormatVersion:: + Internal variable identifying the repository format and layout + version. + +core.sharedRepository:: + When 'group' (or 'true'), the repository is made shareable between + several users in a group (making sure all the files and objects are + group-writable). When 'all' (or 'world' or 'everybody'), the + repository will be readable by all users, additionally to being + group-shareable. When 'umask' (or 'false'), Git will use permissions + reported by umask(2). When '0xxx', where '0xxx' is an octal number, + files in the repository will have this mode value. '0xxx' will override + user's umask value (whereas the other options will only override + requested parts of the user's umask value). Examples: '0660' will make + the repo read/write-able for the owner and group, but inaccessible to + others (equivalent to 'group' unless umask is e.g. '0022'). '0640' is a + repository that is group-readable but not group-writable. + See linkgit:git-init[1]. False by default. + +core.warnAmbiguousRefs:: + If true, Git will warn you if the ref name you passed it is ambiguous + and might match multiple refs in the repository. True by default. + +core.compression:: + An integer -1..9, indicating a default compression level. + -1 is the zlib default. 0 means no compression, + and 1..9 are various speed/size tradeoffs, 9 being slowest. + If set, this provides a default to other compression variables, + such as `core.looseCompression` and `pack.compression`. + +core.looseCompression:: + An integer -1..9, indicating the compression level for objects that + are not in a pack file. -1 is the zlib default. 0 means no + compression, and 1..9 are various speed/size tradeoffs, 9 being + slowest. If not set, defaults to core.compression. If that is + not set, defaults to 1 (best speed). + +core.packedGitWindowSize:: + Number of bytes of a pack file to map into memory in a + single mapping operation. Larger window sizes may allow + your system to process a smaller number of large pack files + more quickly. Smaller window sizes will negatively affect + performance due to increased calls to the operating system's + memory manager, but may improve performance when accessing + a large number of large pack files. ++ +Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 +MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should +be reasonable for all users/operating systems. You probably do +not need to adjust this value. ++ +Common unit suffixes of 'k', 'm', or 'g' are supported. + +core.packedGitLimit:: + Maximum number of bytes to map simultaneously into memory + from pack files. If Git needs to access more than this many + bytes at once to complete an operation it will unmap existing + regions to reclaim virtual address space within the process. ++ +Default is 256 MiB on 32 bit platforms and 32 TiB (effectively +unlimited) on 64 bit platforms. +This should be reasonable for all users/operating systems, except on +the largest projects. You probably do not need to adjust this value. ++ +Common unit suffixes of 'k', 'm', or 'g' are supported. + +core.deltaBaseCacheLimit:: + Maximum number of bytes to reserve for caching base objects + that may be referenced by multiple deltified objects. By storing the + entire decompressed base objects in a cache Git is able + to avoid unpacking and decompressing frequently used base + objects multiple times. ++ +Default is 96 MiB on all platforms. This should be reasonable +for all users/operating systems, except on the largest projects. +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. ++ +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. ++ +Common unit suffixes of 'k', 'm', or 'g' are supported. + +core.excludesFile:: + Specifies the pathname to the file that contains patterns to + describe paths that are not meant to be tracked, in addition + to `.gitignore` (per-directory) and `.git/info/exclude`. + Defaults to `$XDG_CONFIG_HOME/git/ignore`. + If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` + is used instead. See linkgit:gitignore[5]. + +core.askPass:: + Some commands (e.g. svn and http interfaces) that interactively + ask for a password can be told to use an external program given + via the value of this variable. Can be overridden by the `GIT_ASKPASS` + environment variable. If not set, fall back to the value of the + `SSH_ASKPASS` environment variable or, failing that, a simple password + prompt. The external program shall be given a suitable prompt as + command-line argument and write the password on its STDOUT. + +core.attributesFile:: + In addition to `.gitattributes` (per-directory) and + `.git/info/attributes`, Git looks into this file for attributes + (see linkgit:gitattributes[5]). Path expansions are made the same + way as for `core.excludesFile`. Its default value is + `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not + set or empty, `$HOME/.config/git/attributes` is used instead. + +core.hooksPath:: + By default Git will look for your hooks in the + `$GIT_DIR/hooks` directory. Set this to different path, + e.g. `/etc/git/hooks`, and Git will try to find your hooks in + that directory, e.g. `/etc/git/hooks/pre-receive` instead of + in `$GIT_DIR/hooks/pre-receive`. ++ +The path can be either absolute or relative. A relative path is +taken as relative to the directory where the hooks are run (see +the "DESCRIPTION" section of linkgit:githooks[5]). ++ +This configuration variable is useful in cases where you'd like to +centrally configure your Git hooks instead of configuring them on a +per-repository basis, or as a more flexible and centralized +alternative to having an `init.templateDir` where you've changed +default hooks. + +core.editor:: + Commands such as `commit` and `tag` that let you edit + messages by launching an editor use the value of this + variable when it is set, and the environment variable + `GIT_EDITOR` is not set. See linkgit:git-var[1]. + +core.commentChar:: + 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 + (default '#'). ++ +If set to "auto", `git-commit` would select a character that is not +the beginning character of any line in existing commit messages. + +core.filesRefLockTimeout:: + The length of time, in milliseconds, to retry when trying to + lock an individual reference. Value 0 means not to retry at + all; -1 means to try indefinitely. Default is 100 (i.e., + retry for 100ms). + +core.packedRefsTimeout:: + The length of time, in milliseconds, to retry when trying to + lock the `packed-refs` file. Value 0 means not to retry at + all; -1 means to try indefinitely. Default is 1000 (i.e., + retry for 1 second). + +core.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 + is the `$GIT_PAGER` environment variable, then `core.pager` + configuration, then `$PAGER`, and then the default chosen at + compile time (usually 'less'). ++ +When the `LESS` environment variable is unset, Git sets it to `FRX` +(if `LESS` environment variable is set, Git does not change it at +all). If you want to selectively override Git's default setting +for `LESS`, you can set `core.pager` to e.g. `less -S`. This will +be passed to the shell by Git, which will translate the final +command to `LESS=FRX less -S`. The environment does not set the +`S` option but the command line does, instructing less to truncate +long lines. Similarly, setting `core.pager` to `less -+F` will +deactivate the `F` option specified by the environment from the +command-line, deactivating the "quit if one screen" behavior of +`less`. One can specifically activate some flags for particular +commands: for example, setting `pager.blame` to `less -S` enables +line truncation only for `git blame`. ++ +Likewise, when the `LV` environment variable is unset, Git sets it +to `-c`. You can override this setting by exporting `LV` with +another value or setting `core.pager` to `lv +c`. + +core.whitespace:: + A comma separated list of common whitespace problems to + notice. 'git diff' will use `color.diff.whitespace` to + highlight them, and 'git apply --whitespace=error' will + consider them as errors. You can prefix `-` to disable + any of them (e.g. `-trailing-space`): ++ +* `blank-at-eol` treats trailing whitespaces at the end of the line + as an error (enabled by default). +* `space-before-tab` treats a space character that appears immediately + before a tab character in the initial indent part of the line as an + error (enabled by default). +* `indent-with-non-tab` treats a line that is indented with space + characters instead of the equivalent tabs as an error (not enabled by + default). +* `tab-in-indent` treats a tab character in the initial indent part of + the line as an error (not enabled by default). +* `blank-at-eof` treats blank lines added at the end of file as an error + (enabled by default). +* `trailing-space` is a short-hand to cover both `blank-at-eol` and + `blank-at-eof`. +* `cr-at-eol` treats a carriage-return at the end of line as + part of the line terminator, i.e. with it, `trailing-space` + does not trigger if the character before such a carriage-return + is not a whitespace (not enabled by default). +* `tabwidth=<n>` tells how many character positions a tab occupies; this + 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.fsyncObjectFiles:: + This boolean will enable 'fsync()' when writing object files. ++ +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"). + +core.preloadIndex:: + Enable parallel index preload for operations like 'git diff' ++ +This can speed up operations like 'git diff' and 'git status' especially +on filesystems like NFS that have weak caching semantics and thus +relatively high IO latencies. When enabled, Git will do the +index comparison to the filesystem data in parallel, allowing +overlapping IO's. Defaults to true. + +core.unsetenvvars:: + Windows-only: comma-separated list of environment variables' + names that need to be unset before spawning any other process. + Defaults to `PERL5LIB` to account for the fact that Git for + Windows insists on using its own Perl interpreter. + +core.restrictinheritedhandles:: + Windows-only: override whether spawned processes inherit only standard + file handles (`stdin`, `stdout` and `stderr`) or all handles. Can be + `auto`, `true` or `false`. Defaults to `auto`, which means `true` on + Windows 7 and later, and `false` on older Windows versions. + +core.createObject:: + You can set this to 'link', in which case a hardlink followed by + a delete of the source are used to make sure that object creation + 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 +check that makes sure that existing object files will not get overwritten. + +core.notesRef:: + When showing commit messages, also show notes which are stored in + the given ref. The ref must be fully qualified. If the given + ref does not exist, it is not an error but means that no + notes should be printed. ++ +This setting defaults to "refs/notes/commits", and it can be overridden by +the `GIT_NOTES_REF` environment variable. See linkgit:git-notes[1]. + +core.commitGraph:: + If true, then git will read the commit-graph file (if it exists) + to parse the graph structure of commits. Defaults to true. See + linkgit:git-commit-graph[1] for more information. + +core.useReplaceRefs:: + If set to `false`, behave as if the `--no-replace-objects` + option was given on the command line. See linkgit:git[1] and + linkgit:git-replace[1] for more information. + +core.multiPackIndex:: + Use the multi-pack-index file to track multiple packfiles using a + single index. See link:technical/multi-pack-index.html[the + multi-pack-index design document]. + +core.sparseCheckout:: + Enable "sparse checkout" feature. See linkgit:git-sparse-checkout[1] + for more information. + +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 + linkgit:git-sparse-checkout[1] for more information. + +core.abbrev:: + Set the length object names are abbreviated to. If + unspecified or set to "auto", an appropriate value is + computed based on the approximate number of packed objects + in your repository, which hopefully is enough for + abbreviated object names to stay unique for some time. + The minimum length is 4. diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt new file mode 100644 index 0000000000..9d01641c28 --- /dev/null +++ b/Documentation/config/credential.txt @@ -0,0 +1,30 @@ +credential.helper:: + Specify an external helper to be called when a username or + password credential is needed; the helper may consult external + storage to avoid prompting the user for the credentials. This is + normally the name of a credential helper with possible + arguments, but may also be an absolute path with arguments or, if + preceded by `!`, shell commands. ++ +Note that multiple helpers may be defined. See linkgit:gitcredentials[7] +for details and examples. + +credential.useHttpPath:: + When acquiring credentials, consider the "path" component of an http + or https URL to be important. Defaults to false. See + linkgit:gitcredentials[7] for more information. + +credential.username:: + If no username is set for a network authentication, use this username + by default. See credential.<context>.* below, and + linkgit:gitcredentials[7]. + +credential.<url>.*:: + Any of the credential.* options above can be applied selectively to + 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. + +credentialCache.ignoreSIGHUP:: + Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting. diff --git a/Documentation/diff-config.txt b/Documentation/config/diff.txt index 77caa66c2f..ff09f1cf73 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/config/diff.txt @@ -10,7 +10,7 @@ diff.autoRefreshIndex:: diff.dirstat:: A comma separated list of `--dirstat` parameters specifying the - default behavior of the `--dirstat` option to linkgit:git-diff[1]` + default behavior of the `--dirstat` option to linkgit:git-diff[1] and friends. The defaults can be overridden on the command line (using `--dirstat=<param1,param2,...>`). The fallback defaults (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. @@ -73,12 +73,13 @@ diff.external:: environment variable. The command is called with parameters as described under "git Diffs" in linkgit:git[1]. Note: if you want to use an external diff program only on a subset of - your files, you might want to use linkgit:gitattributes[5] instead. + your files, you might want to use linkgit:gitattributes[5] instead. diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this affects only 'git diff' Porcelain, and not lower level 'diff' - commands such as 'git diff-files'. 'git checkout' also honors + commands such as 'git diff-files'. 'git checkout' + and 'git switch' also honor this setting when reporting uncommitted changes. Setting it to 'all' disables the submodule summary normally shown by 'git commit' and 'git status' when `status.submoduleSummary` is set unless it is @@ -177,10 +178,18 @@ diff.tool:: Any other value is treated as a custom diff tool and requires that a corresponding difftool.<tool>.cmd variable is defined. -include::mergetools-diff.txt[] +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:: - Set this option to `true` to enable experimental heuristics + Set this option to `false` to disable the default heuristics that shift diff hunk boundaries to make patches easier to read. diff.algorithm:: @@ -208,3 +217,15 @@ diff.wsErrorHighlight:: whitespace errors are colored with `color.diff.whitespace`. The command line option `--ws-error-highlight=<kind>` overrides this setting. + +diff.colorMoved:: + If set to either a valid `<mode>` or a true value, moved lines + in a diff are colored differently, for details of valid modes + see '--color-moved' in linkgit:git-diff[1]. If simply set to + true the default color mode will be used. When set to false, + moved lines are not colored. + +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]. diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt new file mode 100644 index 0000000000..6762594480 --- /dev/null +++ b/Documentation/config/difftool.txt @@ -0,0 +1,14 @@ +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. + The specified command is evaluated in shell with the following + variables available: 'LOCAL' is set to the name of the temporary + 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. + +difftool.prompt:: + Prompt before each invocation of the diff tool. diff --git a/Documentation/config/fastimport.txt b/Documentation/config/fastimport.txt new file mode 100644 index 0000000000..c1166e330d --- /dev/null +++ b/Documentation/config/fastimport.txt @@ -0,0 +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 + 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 new file mode 100644 index 0000000000..4e3a5c0ceb --- /dev/null +++ b/Documentation/config/feature.txt @@ -0,0 +1,34 @@ +feature.*:: + The config settings that start with `feature.` modify the defaults of + a group of other config settings. These groups are created by the Git + developer community as recommended defaults and are subject to change. + In particular, new config options may be added with different defaults. + +feature.experimental:: + Enable config options that are new to Git, and are being considered for + future defaults. Config settings included here may be added or removed + with each release, including minor version updates. These settings may + have unintended interactions since they are so new. Please enable this + setting if you are interested in providing feedback on experimental + features. The new default values are: ++ +* `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by +skipping more commits at a time, reducing the number of round trips. ++ +* `fetch.writeCommitGraph=true` writes a commit-graph after every `git fetch` +command that downloads a pack-file from a remote. Using the `--split` option, +most executions will create a very small commit-graph file on top of the +existing commit-graph file(s). Occasionally, these files will 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`. + +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.version=4` enables path-prefix compression in the index. ++ +* `core.untrackedCache=true` enables the untracked cache. This setting assumes +that mtime is working on your machine. diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt new file mode 100644 index 0000000000..b1a9b1461d --- /dev/null +++ b/Documentation/config/fetch.txt @@ -0,0 +1,94 @@ +fetch.recurseSubmodules:: + This option controls whether `git fetch` (and the underlying fetch + in `git pull`) will recursively fetch into populated submodules. + This option can be set either to a boolean value or to 'on-demand'. + Setting it to a boolean changes the behavior of fetch and pull to + recurse unconditionally into submodules when set to true or to not + recurse at all when set to false. When set to 'on-demand', fetch and + pull will only recurse into a populated submodule when its + superproject retrieves a commit that updates the submodule's + reference. + Defaults to 'on-demand', or to the value of 'submodule.recurse' if set. + +fetch.fsckObjects:: + If it is set to true, git-fetch-pack will check all fetched + objects. See `transfer.fsckObjects` for what's + checked. Defaults to false. If not set, the value of + `transfer.fsckObjects` is used instead. + +fetch.fsck.<msg-id>:: + Acts like `fsck.<msg-id>`, but is used by + linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See + the `fsck.<msg-id>` documentation for details. + +fetch.fsck.skipList:: + Acts like `fsck.skipList`, but is used by + linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See + the `fsck.skipList` documentation for details. + +fetch.unpackLimit:: + If the number of objects fetched over the Git native + transfer is below this + limit, then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. If not set, the value of + `transfer.unpackLimit` is used instead. + +fetch.prune:: + If true, fetch will automatically behave as if the `--prune` + option was given on the command line. See also `remote.<name>.prune` + and the PRUNING section of linkgit:git-fetch[1]. + +fetch.pruneTags:: + If true, fetch will automatically behave as if the + `refs/tags/*:refs/tags/*` refspec was provided when pruning, + if not set already. This allows for setting both this option + and `fetch.prune` to maintain a 1=1 mapping to upstream + refs. See also `remote.<name>.pruneTags` and the PRUNING + section of linkgit:git-fetch[1]. + +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. + +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; 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. ++ +See also the `--negotiation-tip` option for linkgit:git-fetch[1]. + +fetch.showForcedUpdates:: + Set to false to enable `--no-show-forced-updates` in + linkgit:git-fetch[1] and linkgit:git-pull[1] commands. + Defaults to true. + +fetch.parallel:: + Specifies the maximal number of fetch operations to be run in parallel + at a time (submodules, or remotes when the `--multiple` option of + linkgit:git-fetch[1] is in effect). ++ +A value of 0 will give some reasonable default. If unset, it defaults to 1. ++ +For submodules, this setting can be overridden using the `submodule.fetchJobs` +config setting. + +fetch.writeCommitGraph:: + Set to true to write a commit-graph after every `git fetch` command + that downloads a pack-file from a remote. Using the `--split` option, + most executions will create a very small commit-graph file on top of + the existing commit-graph file(s). Occasionally, these files will + 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, unless + `feature.experimental` is true. diff --git a/Documentation/config/filter.txt b/Documentation/config/filter.txt new file mode 100644 index 0000000000..90dfe0ba5a --- /dev/null +++ b/Documentation/config/filter.txt @@ -0,0 +1,9 @@ +filter.<driver>.clean:: + The command which is used to convert the content of a worktree + file to a blob upon checkin. See linkgit:gitattributes[5] for + details. + +filter.<driver>.smudge:: + The command which is used to convert the content of a blob + object to a worktree file upon checkout. See + linkgit:gitattributes[5] for details. diff --git a/Documentation/fmt-merge-msg-config.txt b/Documentation/config/fmt-merge-msg.txt index c73cfa90b7..c73cfa90b7 100644 --- a/Documentation/fmt-merge-msg-config.txt +++ b/Documentation/config/fmt-merge-msg.txt diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt new file mode 100644 index 0000000000..564e8091ba --- /dev/null +++ b/Documentation/config/format.txt @@ -0,0 +1,130 @@ +format.attach:: + Enable multipart/mixed attachments as the default for + '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]. + +format.from:: + Provides the default value for the `--from` option to format-patch. + Accepts a boolean value, or a name and email address. If false, + format-patch defaults to `--no-from`, using commit authors directly in + the "From:" field of patch mails. If true, format-patch defaults to + `--from`, using your committer identity in the "From:" field of patch + mails and including a "From:" field in the body of the patch mail if + different. If set to a non-boolean value, format-patch uses that + value instead of your committer identity. 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 + is more than one patch. It can be enabled or disabled for all + messages by setting it to "true" or "false". See --numbered + option in linkgit:git-format-patch[1]. + +format.headers:: + Additional email headers to include in a patch to be submitted + by mail. See linkgit:git-format-patch[1]. + +format.to:: +format.cc:: + Additional recipients to include in a patch to be submitted + by mail. See the --to and --cc options in + linkgit:git-format-patch[1]. + +format.subjectPrefix:: + The default for format-patch is to output files with the '[PATCH]' + subject prefix. Use this variable to change that prefix. + +format.coverFromDescription:: + The default mode for format-patch to determine which parts of + the cover letter will be populated using the branch's + description. See the `--cover-from-description` option in + linkgit:git-format-patch[1]. + +format.signature:: + The default for format-patch is to output a signature containing + the Git version number. Use this variable to change that default. + Set this variable to the empty string ("") to suppress + signature generation. + +format.signatureFile:: + Works just like format.signature except the contents of the + file specified by this variable will be used as the signature. + +format.suffix:: + The default for format-patch is to output files with the suffix + `.patch`. Use this variable to change that suffix (make sure to + include the dot if you want it). + +format.encodeEmailHeaders:: + Encode email headers that have non-ASCII characters with + "Q-encoding" (described in RFC 2047) for email transmission. + Defaults to true. + +format.pretty:: + The default pretty format for log/show/whatchanged command, + See linkgit:git-log[1], linkgit:git-show[1], + linkgit:git-whatchanged[1]. + +format.thread:: + The default threading style for 'git format-patch'. Can be + a boolean value, or `shallow` or `deep`. `shallow` threading + makes every mail a reply to the head of the series, + where the head is chosen from the cover letter, the + `--in-reply-to`, and the first patch mail, in this order. + `deep` threading makes every mail a reply to the previous one. + A true boolean value is the same as `shallow`, and a false + value disables threading. + +format.signOff:: + A boolean value which lets you enable the `-s/--signoff` option of + format-patch by default. *Note:* Adding the Signed-off-by: line to a + patch should be a conscious act and means that you certify you have + the rights to submit this work under the same open source license. + Please see the 'SubmittingPatches' document for further discussion. + +format.coverLetter:: + A boolean that controls whether to generate a cover-letter when + format-patch is invoked, but in addition can be set to "auto", to + generate a cover-letter only when there's more than one patch. + Default is false. + +format.outputDirectory:: + Set a custom directory to store the resulting files instead of the + current working directory. All directory components will be created. + +format.useAutoBase:: + A boolean value which lets you enable the `--base=auto` option of + format-patch by default. + +format.notes:: + Provides the default value for the `--notes` option to + format-patch. Accepts a boolean value, or a ref which specifies + where to get notes. If false, format-patch defaults to + `--no-notes`. If true, format-patch defaults to `--notes`. If + set to a non-boolean value, format-patch defaults to + `--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 +instead. ++ +This configuration can be specified multiple times in order to allow +multiple notes refs to be included. In that case, it will behave +similarly to multiple `--[no-]notes[=]` options passed in. That is, a +value of `true` will show the default notes, a value of `<ref>` will +also show notes from that notes ref and a value of `false` will negate +previous configurations and not show notes. ++ +For example, ++ +------------ +[format] + notes = true + notes = foo + notes = false + notes = bar +------------ ++ +will only show notes from `refs/notes/bar`. diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt new file mode 100644 index 0000000000..450e8c38e3 --- /dev/null +++ b/Documentation/config/fsck.txt @@ -0,0 +1,67 @@ +fsck.<msg-id>:: + During fsck git may find issues with legacy data which + wouldn't be generated by current versions of git, and which + wouldn't be sent over the wire if `transfer.fsckObjects` was + set. This feature is intended to support working with legacy + repositories containing such data. ++ +Setting `fsck.<msg-id>` will be picked up by linkgit:git-fsck[1], but +to accept pushes of such data set `receive.fsck.<msg-id>` instead, or +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. ++ +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. ++ +When `fsck.<msg-id>` is set, errors can be switched to warnings and +vice versa by configuring the `fsck.<msg-id>` setting where the +`<msg-id>` is the fsck message ID and the value is one of `error`, +`warn` or `ignore`. For convenience, fsck prefixes the error/warning +with the message ID, e.g. "missingEmail: invalid author/committer +line - missing email" means that setting `fsck.missingEmail = ignore` +will hide that issue. ++ +In general, it is better to enumerate existing objects with problems +with `fsck.skipList`, instead of listing the kind of breakages these +problematic objects share to be ignored, as doing the latter will +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. + +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 + 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 +such as invalid committer email addresses. Note: corrupt objects +cannot be skipped with this setting. ++ +Like `fsck.<msg-id>` this variable has corresponding +`receive.fsck.skipList` and `fetch.fsck.skipList` variants. ++ +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. ++ +Older versions of Git (before 2.20) documented that 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 +list. Unless you had a humongous list there was no reason to go out of +your way to pre-sort the list. After Git version 2.20 a hash implementation +is used instead, so there's now no reason to pre-sort the list. diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt new file mode 100644 index 0000000000..00ea0a678e --- /dev/null +++ b/Documentation/config/gc.txt @@ -0,0 +1,136 @@ +gc.aggressiveDepth:: + The depth parameter used in the delta compression + algorithm used by 'git gc --aggressive'. This defaults + to 50, which is the default for the `--depth` option when + `--aggressive` isn't in use. ++ +See the documentation for the `--depth` option in +linkgit:git-repack[1] for more details. + +gc.aggressiveWindow:: + The window size parameter used in the delta compression + algorithm used by 'git gc --aggressive'. This defaults + to 250, which is a much more aggressive window size than + the default `--window` of 10. ++ +See the documentation for the `--window` option in +linkgit:git-repack[1] for more details. + +gc.auto:: + When there are approximately more than this many loose + objects in the repository, `git gc --auto` will pack them. + Some Porcelain commands use this command to perform a + light-weight garbage collection from time to time. The + 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 +otherwise use to determine if there's work to do, such as +`gc.autoPackLimit`. + +gc.autoPackLimit:: + When there are more than this many packs that are not + marked with `*.keep` file in the repository, `git gc + --auto` consolidates them into one larger pack. The + default value is 50. Setting this to 0 disables it. + Setting `gc.auto` to 0 will also disable this. ++ +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 + 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-base-pack` + except that all packs that meet the threshold are kept, not + just the base 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 +will be repacked. After this the number of packs should go below +gc.autoPackLimit and gc.bigPackThreshold should be respected again. ++ +If the amount of memory estimated for `git repack` to run smoothly is +not available and `gc.bigPackThreshold` is not set, the largest pack +will also be excluded (this is the equivalent of running `git gc` with +`--keep-base-pack`). + +gc.writeCommitGraph:: + If true, then gc will rewrite the commit-graph file when + linkgit:git-gc[1] is run. When using `git gc --auto` + the commit-graph will be updated if housekeeping is + required. Default is true. See linkgit:git-commit-graph[1] + for details. + +gc.logExpiry:: + If the file gc.log exists, then `git gc --auto` will print + its content and exit with status zero instead of running + unless that file is more than 'gc.logExpiry' old. Default is + "1.day". See `gc.pruneExpire` for more ways to specify its + value. + +gc.packRefs:: + Running `git pack-refs` in a repository renders it + unclonable by Git versions prior to 1.5.1.2 over dumb + transports such as HTTP. This variable determines whether + 'git gc' runs `git pack-refs`. This can be set to `notbare` + to enable it within all non-bare repos or it can be set to a + boolean value. The default is `true`. + +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]. + +gc.worktreePruneExpire:: + When 'git gc' is run, it calls + 'git worktree prune --expire 3.months.ago'. + This config variable can be used to set a different grace + period. The value "now" may be used to disable the grace + period and prune `$GIT_DIR/worktrees` immediately, or "never" + may be used to suppress pruning. + +gc.reflogExpire:: +gc.<pattern>.reflogExpire:: + 'git reflog expire' removes reflog entries older than + this time; defaults to 90 days. The value "now" expires all + entries immediately, and "never" suppresses expiration + altogether. With "<pattern>" (e.g. + "refs/stash") in the middle the setting applies only to + the refs that match the <pattern>. + +gc.reflogExpireUnreachable:: +gc.<pattern>.reflogExpireUnreachable:: + 'git reflog expire' removes reflog entries older than + this time and are not reachable from the current tip; + defaults to 30 days. The value "now" expires all entries + immediately, and "never" suppresses expiration altogether. + With "<pattern>" (e.g. "refs/stash") + in the middle, the setting applies only to the refs that + match the <pattern>. ++ +These types of entries are generally created as a result of using `git +commit --amend` or `git rebase` and are the commits prior to the amend +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.rerereResolved:: + Records of conflicted merge you resolved earlier are + kept for this many days when 'git rerere gc' is run. + You can also use more human-readable "1.month.ago", etc. + The default is 60 days. See linkgit:git-rerere[1]. + +gc.rerereUnresolved:: + Records of conflicted merge you have not resolved are + kept for this many days when 'git rerere gc' is run. + You can also use more human-readable "1.month.ago", etc. + The default is 15 days. See linkgit:git-rerere[1]. diff --git a/Documentation/config/gitcvs.txt b/Documentation/config/gitcvs.txt new file mode 100644 index 0000000000..02da427fd9 --- /dev/null +++ b/Documentation/config/gitcvs.txt @@ -0,0 +1,67 @@ +gitcvs.commitMsgAnnotation:: + Append this string to each commit message. Set to empty string + to disable this feature. Defaults to "via git-CVS emulator". + +gitcvs.enabled:: + Whether the CVS server interface is enabled for this repository. + See linkgit:git-cvsserver[1]. + +gitcvs.logFile:: + Path to a log file where the CVS server interface well... logs + various stuff. See linkgit:git-cvsserver[1]. + +gitcvs.usecrlfattr:: + If true, the server will look up the end-of-line conversion + attributes for files to determine the `-k` modes to use. If + the attributes force Git to treat a file as text, + the `-k` mode will be left blank so CVS clients will + treat it as text. If they suppress text conversion, the file + will be set with '-kb' mode, which suppresses any newline munging + the client might otherwise do. If the attributes do not allow + the file type to be determined, then `gitcvs.allBinary` is + used. See linkgit:gitattributes[5]. + +gitcvs.allBinary:: + This is used if `gitcvs.usecrlfattr` does not resolve + the correct '-kb' mode to use. If true, all + unresolved files are sent to the client in + mode '-kb'. This causes the client to treat them + as binary files, which suppresses any newline munging it + otherwise might do. Alternatively, if it is set to "guess", + then the contents of the file are examined to decide if + it is binary, similar to `core.autocrlf`. + +gitcvs.dbName:: + Database used by git-cvsserver to cache revision information + derived from the Git repository. The exact meaning depends on the + used database driver, for SQLite (which is the default driver) this + is a filename. Supports variable substitution (see + linkgit:git-cvsserver[1] for details). May not contain semicolons (`;`). + Default: '%Ggitcvs.%m.sqlite' + +gitcvs.dbDriver:: + Used Perl DBI driver. You can specify any available driver + for this here, but it might not work. git-cvsserver is tested + with 'DBD::SQLite', reported to work with 'DBD::Pg', and + reported *not* to work with 'DBD::mysql'. Experimental feature. + May not contain double colons (`:`). Default: 'SQLite'. + See linkgit:git-cvsserver[1]. + +gitcvs.dbUser, gitcvs.dbPass:: + Database user and password. Only useful if setting `gitcvs.dbDriver`, + since SQLite has no concept of database users and/or passwords. + 'gitcvs.dbUser' supports variable substitution (see + linkgit:git-cvsserver[1] for details). + +gitcvs.dbTableNamePrefix:: + Database table name prefix. Prepended to the names of any + database tables used, allowing a single database to be used + for several repositories. Supports variable substitution (see + linkgit:git-cvsserver[1] for details). Any non-alphabetic + characters will be replaced with underscores. + +All gitcvs variables except for `gitcvs.usecrlfattr` and +`gitcvs.allBinary` can also be specified as +'gitcvs.<access_method>.<varname>' (where 'access_method' +is one of "ext" and "pserver") to make them apply only for the given +access method. diff --git a/Documentation/config/gitweb.txt b/Documentation/config/gitweb.txt new file mode 100644 index 0000000000..1b51475108 --- /dev/null +++ b/Documentation/config/gitweb.txt @@ -0,0 +1,16 @@ +gitweb.category:: +gitweb.description:: +gitweb.owner:: +gitweb.url:: + See linkgit:gitweb[1] for description. + +gitweb.avatar:: +gitweb.blame:: +gitweb.grep:: +gitweb.highlight:: +gitweb.patches:: +gitweb.pickaxe:: +gitweb.remote_heads:: +gitweb.showSizes:: +gitweb.snapshot:: + See linkgit:gitweb.conf[5] for description. diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt new file mode 100644 index 0000000000..d94025cb36 --- /dev/null +++ b/Documentation/config/gpg.txt @@ -0,0 +1,35 @@ +gpg.program:: + Use this custom program instead of "`gpg`" found on `$PATH` when + making or verifying a PGP signature. The program must support the + 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 + 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". + +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". + +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 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, + in increasing order of significance: ++ +* `undefined` +* `never` +* `marginal` +* `fully` +* `ultimate` diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt new file mode 100644 index 0000000000..44abe45a7c --- /dev/null +++ b/Documentation/config/grep.txt @@ -0,0 +1,24 @@ +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. + See `grep.threads` in linkgit:git-grep[1] for more information. + +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. diff --git a/Documentation/config/gui.txt b/Documentation/config/gui.txt new file mode 100644 index 0000000000..d30831a130 --- /dev/null +++ b/Documentation/config/gui.txt @@ -0,0 +1,57 @@ +gui.commitMsgWidth:: + Defines how wide the commit message window is in the + linkgit:git-gui[1]. "75" is the default. + +gui.diffContext:: + Specifies how many context lines should be used in calls to diff + made by the linkgit:git-gui[1]. The default is "5". + +gui.displayUntracked:: + Determines if linkgit:git-gui[1] shows untracked files + in the file list. The default is "true". + +gui.encoding:: + Specifies the default 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]). + If this option is not set, the tools default to the + locale encoding. + +gui.matchTrackingBranch:: + Determines if new branches created with linkgit:git-gui[1] should + default to tracking remote branches with matching names or + not. Default: "false". + +gui.newBranchTemplate:: + Is used as suggested name when creating new branches using the + linkgit:git-gui[1]. + +gui.pruneDuringFetch:: + "true" if linkgit:git-gui[1] should prune remote-tracking branches when + performing a fetch. The default value is "false". + +gui.trustmtime:: + Determines if linkgit:git-gui[1] should trust the file modification + timestamp or not. By default the timestamps are not trusted. + +gui.spellingDictionary:: + Specifies the dictionary used for spell checking commit messages in + the linkgit:git-gui[1]. When set to "none" spell checking is turned + off. + +gui.fastCopyBlame:: + If true, 'git gui blame' uses `-C` instead of `-C -C` for original + location detection. It makes blame significantly faster on huge + repositories at the expense of less thorough copy detection. + +gui.copyBlameThreshold:: + Specifies the threshold to use in 'git gui blame' original location + detection, measured in alphanumeric characters. See the + linkgit:git-blame[1] manual for more information on copy detection. + +gui.blamehistoryctx:: + Specifies the radius of history context in days to show in + linkgit:gitk[1] for the selected commit, when the `Show History + Context` menu item is invoked from 'git gui blame'. If this + variable is set to zero, the whole history is shown. diff --git a/Documentation/config/guitool.txt b/Documentation/config/guitool.txt new file mode 100644 index 0000000000..43fb9466ff --- /dev/null +++ b/Documentation/config/guitool.txt @@ -0,0 +1,50 @@ +guitool.<name>.cmd:: + Specifies the shell command line to execute when the corresponding item + of the linkgit:git-gui[1] `Tools` menu is invoked. This option is + mandatory for every tool. The command is executed from the root of + the working directory, and in the environment it receives the name of + the tool as `GIT_GUITOOL`, the name of the currently selected file as + 'FILENAME', and the name of the current branch as 'CUR_BRANCH' (if + the head is detached, 'CUR_BRANCH' is empty). + +guitool.<name>.needsFile:: + Run the tool only if a diff is selected in the GUI. It guarantees + that 'FILENAME' is not empty. + +guitool.<name>.noConsole:: + Run the command silently, without creating a window to display its + output. + +guitool.<name>.noRescan:: + Don't rescan the working directory for changes after the tool + finishes execution. + +guitool.<name>.confirm:: + Show a confirmation dialog before actually running the tool. + +guitool.<name>.argPrompt:: + Request a string argument from the user, and pass it to the tool + through the `ARGS` environment variable. Since requesting an + argument implies confirmation, the 'confirm' option has no effect + if this is enabled. If the option is set to 'true', 'yes', or '1', + the dialog uses a built-in generic prompt; otherwise the exact + value of the variable is used. + +guitool.<name>.revPrompt:: + Request a single valid revision from the user, and set the + `REVISION` environment variable. In other aspects this option + is similar to 'argPrompt', and can be used together with it. + +guitool.<name>.revUnmerged:: + Show only unmerged branches in the 'revPrompt' subdialog. + This is useful for tools similar to merge or rebase, but not + for things like checkout or reset. + +guitool.<name>.title:: + Specifies the title to use for the prompt dialog. The default + is the tool name. + +guitool.<name>.prompt:: + Specifies the general prompt string to display at the top of + the dialog, before subsections for 'argPrompt' and 'revPrompt'. + The default value includes the actual command. diff --git a/Documentation/config/help.txt b/Documentation/config/help.txt new file mode 100644 index 0000000000..224bbf5a28 --- /dev/null +++ b/Documentation/config/help.txt @@ -0,0 +1,23 @@ +help.browser:: + Specify the browser that will be used to display help in the + 'web' format. See linkgit:git-help[1]. + +help.format:: + Override the default help format used by linkgit:git-help[1]. + Values 'man', 'info', 'web' and 'html' are supported. 'man' is + the default. 'web' and 'html' are the same. + +help.autoCorrect:: + Automatically correct and execute mistyped commands after + waiting for the given number of deciseconds (0.1 sec). If more + than one command can be deduced from the entered text, nothing + will be executed. If the value of this option is negative, + the corrected command will be executed immediately. If the + value is 0 - the command will be just shown but not executed. + This is the default. + +help.htmlPath:: + Specify the path where the HTML documentation resides. File system paths + and URLs are supported. HTML pages will be prefixed with this path when + help is displayed in the 'web' format. This defaults to the documentation + path of your Git installation. diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt new file mode 100644 index 0000000000..3968fbb697 --- /dev/null +++ b/Documentation/config/http.txt @@ -0,0 +1,309 @@ +http.proxy:: + Override the HTTP proxy, normally configured using the 'http_proxy', + 'https_proxy', and 'all_proxy' environment variables (see `curl(1)`). In + addition to the syntax understood by curl, it is possible to specify a + proxy string with a user name but no password, in which case git will + attempt to acquire one in the same way it does for other credentials. See + linkgit:gitcredentials[7] for more information. The syntax thus is + '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden + on a per-remote basis; see remote.<name>.proxy + +http.proxyAuthMethod:: + Set the method with which to authenticate against the HTTP proxy. This + only takes effect if the configured proxy string contains a user name part + (i.e. is of the form 'user@host' or 'user@host:port'). This can be + overridden on a per-remote basis; see `remote.<name>.proxyAuthMethod`. + Both can be overridden by the `GIT_HTTP_PROXY_AUTHMETHOD` environment + variable. Possible values are: ++ +-- +* `anyauth` - Automatically pick a suitable authentication method. It is + assumed that the proxy answers an unauthenticated request with a 407 + status code and one or more Proxy-authenticate headers with supported + authentication methods. This is the default. +* `basic` - HTTP Basic authentication +* `digest` - HTTP Digest authentication; this prevents the password from being + transmitted to the proxy in clear text +* `negotiate` - GSS-Negotiate authentication (compare the --negotiate option + of `curl(1)`) +* `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) +-- + +http.proxySSLCert:: + The pathname of a file that stores a client certificate to use to authenticate + with an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CERT` environment + variable. + +http.proxySSLKey:: + The pathname of a file that stores a private key to use to authenticate with + an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_KEY` environment + variable. + +http.proxySSLCertPasswordProtected:: + Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL + will prompt the user, possibly many times, if the certificate or private key + is encrypted. Can be overriden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` + environment variable. + +http.proxySSLCAInfo:: + Pathname to the file containing the certificate bundle that should be used to + verify the proxy with when using an HTTPS proxy. Can be overriden by the + `GIT_PROXY_SSL_CAINFO` environment variable. + +http.emptyAuth:: + Attempt authentication without seeking a username or password. This + can be used to attempt GSS-Negotiate authentication without specifying + a username in the URL, as libcurl normally requires a username for + authentication. + +http.delegation:: + Control GSSAPI credential delegation. The delegation is disabled + by default in libcurl since version 7.21.7. Set parameter to tell + the server what it is allowed to delegate when it comes to user + credentials. Used with GSS/kerberos. Possible values are: ++ +-- +* `none` - Don't allow any delegation. +* `policy` - Delegates if and only if the OK-AS-DELEGATE flag is set in the + Kerberos service ticket, which is a matter of realm policy. +* `always` - Unconditionally allow the server to delegate. +-- + + +http.extraHeader:: + Pass an additional HTTP header when communicating with a server. If + more than one such entry exists, all of them are added as extra + headers. To allow overriding the settings inherited from the system + config, an empty value will reset the extra headers to the empty list. + +http.cookieFile:: + The pathname of a file containing previously stored cookie lines, + which should be used + in the Git http session, if they match the server. The file format + of the file to read cookies from should be plain HTTP headers or + the Netscape/Mozilla cookie file format (see `curl(1)`). + NOTE that the file specified with http.cookieFile is used only as + input unless http.saveCookies is set. + +http.saveCookies:: + If set, store cookies received during requests to the file specified by + http.cookieFile. Has no effect if http.cookieFile is unset. + +http.version:: + Use the specified HTTP protocol version when communicating with a server. + If you want to force the default. The available and default version depend + on libcurl. Currently the possible values of + this option are: + + - HTTP/2 + - HTTP/1.1 + +http.sslVersion:: + The SSL version to use when negotiating an SSL connection, if you + want to force the default. The available and default version + depend on whether libcurl was built against NSS or OpenSSL and the + particular configuration of the crypto library in use. Internally + this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl + documentation for more details on the format of this option and + for the ssl version supported. Currently the possible values of + this option are: + + - sslv2 + - sslv3 + - tlsv1 + - tlsv1.0 + - tlsv1.1 + - tlsv1.2 + - tlsv1.3 + ++ +Can be overridden by the `GIT_SSL_VERSION` environment variable. +To force git to use libcurl's default ssl version and ignore any +explicit http.sslversion option, set `GIT_SSL_VERSION` to the +empty string. + +http.sslCipherList:: + A list of SSL ciphers to use when negotiating an SSL connection. + The available ciphers depend on whether libcurl was built against + NSS or OpenSSL and the particular configuration of the crypto + library in use. Internally this sets the 'CURLOPT_SSL_CIPHER_LIST' + option; see the libcurl documentation for more details on the format + of this list. ++ +Can be overridden by the `GIT_SSL_CIPHER_LIST` environment variable. +To force git to use libcurl's default cipher list and ignore any +explicit http.sslCipherList option, set `GIT_SSL_CIPHER_LIST` to the +empty string. + +http.sslVerify:: + Whether to verify the SSL certificate when fetching or pushing + over HTTPS. Defaults to true. Can be overridden by the + `GIT_SSL_NO_VERIFY` environment variable. + +http.sslCert:: + File containing the SSL certificate when fetching or pushing + over HTTPS. Can be overridden by the `GIT_SSL_CERT` environment + variable. + +http.sslKey:: + File containing the SSL private key when fetching or pushing + over HTTPS. Can be overridden by the `GIT_SSL_KEY` environment + variable. + +http.sslCertPasswordProtected:: + Enable Git's password prompt for the SSL certificate. Otherwise + OpenSSL will prompt the user, possibly many times, if the + certificate or private key is encrypted. Can be overridden by the + `GIT_SSL_CERT_PASSWORD_PROTECTED` environment variable. + +http.sslCAInfo:: + File containing the certificates to verify the peer with when + fetching or pushing over HTTPS. Can be overridden by the + `GIT_SSL_CAINFO` environment variable. + +http.sslCAPath:: + Path containing files with the CA certificates to verify the peer + with when fetching or pushing over HTTPS. Can be overridden + by the `GIT_SSL_CAPATH` environment variable. + +http.sslBackend:: + Name of the SSL backend to use (e.g. "openssl" or "schannel"). + This option is ignored if cURL lacks support for choosing the SSL + backend at runtime. + +http.schannelCheckRevoke:: + Used to enforce or disable certificate revocation checks in cURL + when http.sslBackend is set to "schannel". Defaults to `true` if + unset. Only necessary to disable this if Git consistently errors + and the message is about checking the revocation status of a + certificate. This option is ignored if cURL lacks support for + setting the relevant SSL option at runtime. + +http.schannelUseSSLCAInfo:: + As of cURL v7.60.0, the Secure Channel backend can use the + certificate bundle provided via `http.sslCAInfo`, but that would + override the Windows Certificate Store. Since this is not desirable + by default, Git will tell cURL not to use that bundle by default + when the `schannel` backend was configured via `http.sslBackend`, + unless `http.schannelUseSSLCAInfo` overrides this behavior. + +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 + public key. See also libcurl 'CURLOPT_PINNEDPUBLICKEY'. git will + exit with an error if this option is set but not supported by + cURL. + +http.sslTry:: + Attempt to use AUTH SSL/TLS and encrypted data transfers + when connecting via regular FTP protocol. This might be needed + if the FTP server requires it for security reasons or you wish + to connect securely whenever remote FTP server supports it. + Default is false since it might trigger certificate verification + errors on misconfigured servers. + +http.maxRequests:: + How many HTTP requests to launch in parallel. Can be overridden + by the `GIT_HTTP_MAX_REQUESTS` environment variable. Default is 5. + +http.minSessions:: + The number of curl sessions (counted across slots) to be kept across + requests. They will not be ended with curl_easy_cleanup() until + http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this + value will be capped at 1. Defaults to 1. + +http.postBuffer:: + Maximum size in bytes of the buffer used by smart HTTP + transports when POSTing data to the remote system. + For requests larger than this buffer size, HTTP/1.1 and + Transfer-Encoding: chunked is used to avoid creating a + massive pack file locally. Default is 1 MiB, which is + sufficient for most requests. ++ +Note that raising this limit is only effective for disabling chunked +transfer encoding and therefore should be used only where the remote +server or a proxy only supports HTTP/1.0 or is noncompliant with the +HTTP standard. Raising this is not, in general, an effective solution +for most push problems, but can increase memory consumption +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. + 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 + 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. + 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 + of common USER_AGENT strings (but not including those like git/1.7.1). + Can be overridden by the `GIT_HTTP_USER_AGENT` environment variable. + +http.followRedirects:: + Whether git should follow HTTP redirects. If set to `true`, git + will transparently follow any redirect issued by a server it + encounters. If set to `false`, git will treat all redirects as + errors. If set to `initial`, git will follow redirects only for + the initial request to a remote, but not for subsequent + follow-up HTTP requests. Since git uses the redirected URL as + the base for the follow-up requests, this is generally + sufficient. The default is `initial`. + +http.<url>.*:: + Any of the http.* options above can be applied selectively to some URLs. + For a config key to match a URL, each element of the config key is + compared to that of the URL, in the following order: ++ +-- +. Scheme (e.g., `https` in `https://example.com/`). This field + must match exactly between the config key and the URL. + +. Host/domain name (e.g., `example.com` in `https://example.com/`). + This field must match between the config key and the URL. It is + possible to specify a `*` as part of the host name to match all subdomains + at this level. `https://*.example.com/` for example would match + `https://foo.example.com/`, but not `https://foo.bar.example.com/`. + +. Port number (e.g., `8080` in `http://example.com:8080/`). + This field must match exactly between the config key and the URL. + Omitted port numbers are automatically converted to the correct + default for the scheme before matching. + +. Path (e.g., `repo.git` in `https://example.com/repo.git`). The + path field of the config key must match the path field of the URL + either exactly or as a prefix of slash-delimited path elements. This means + a config key with path `foo/` matches URL path `foo/bar`. A prefix can only + match on a slash (`/`) boundary. Longer matches take precedence (so a config + key with path `foo/bar` is a better match to URL path `foo/bar` than a config + key with just path `foo/`). + +. User name (e.g., `user` in `https://user@example.com/repo.git`). If + the config key has a user name it must match the user name in the + URL exactly. If the config key does not have a user name, that + config key will match a URL with any user name (including none), + but at a lower precedence than a config key with a user name. +-- ++ +The list above is ordered by decreasing precedence; a URL that matches +a config key's path is preferred to one that matches its user name. For example, +if the URL is `https://user@example.com/foo/bar` a config key match of +`https://example.com/foo` will be preferred over a config key match of +`https://user@example.com`. ++ +All URLs are normalized before attempting any matching (the password part, +if embedded in the URL, is always ignored for matching purposes) so that +equivalent URLs that are simply spelled differently will match properly. +Environment variable settings always override any matches. The URLs that are +matched against are those given directly to Git commands. This means any URLs +visited as a result of a redirection do not participate in matching. diff --git a/Documentation/config/i18n.txt b/Documentation/config/i18n.txt new file mode 100644 index 0000000000..cc25621731 --- /dev/null +++ b/Documentation/config/i18n.txt @@ -0,0 +1,10 @@ +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 + porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'. + +i18n.logOutputEncoding:: + Character encoding the commit messages are converted to when + running 'git log' and friends. diff --git a/Documentation/config/imap.txt b/Documentation/config/imap.txt new file mode 100644 index 0000000000..06166fb5c0 --- /dev/null +++ b/Documentation/config/imap.txt @@ -0,0 +1,44 @@ +imap.folder:: + The folder to drop the mails into, which is typically the Drafts + folder. For example: "INBOX.Drafts", "INBOX/Drafts" or + "[Gmail]/Drafts". Required. + +imap.tunnel:: + Command used to setup 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. + +imap.host:: + A URL identifying the server. Use an `imap://` prefix for non-secure + connections and an `imaps://` prefix for secure connections. + Ignored when imap.tunnel is set, but required otherwise. + +imap.user:: + The username to use when logging in to the server. + +imap.pass:: + The password to use when logging in to the server. + +imap.port:: + An integer port number to connect to on the server. + Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. + Ignored when imap.tunnel is set. + +imap.sslverify:: + A boolean to enable/disable verification of the server certificate + used by the SSL/TLS connection. Default is `true`. Ignored when + imap.tunnel is set. + +imap.preformattedHTML:: + A boolean to enable/disable the use of html encoding when sending + a patch. An html encoded patch will be bracketed with <pre> + and have a content type of text/html. Ironically, enabling this + option causes Thunderbird to send the patch as a plain/text, + format=fixed email. Default is `false`. + +imap.authMethod:: + Specify authenticate method for authentication with 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 + then 'git imap-send' uses the basic IMAP plaintext LOGIN command. diff --git a/Documentation/config/index.txt b/Documentation/config/index.txt new file mode 100644 index 0000000000..7cb50b37e9 --- /dev/null +++ b/Documentation/config/index.txt @@ -0,0 +1,27 @@ +index.recordEndOfIndexEntries:: + Specifies whether the index file should include an "End Of Index + Entry" section. This reduces index load time on multiprocessor + machines but produces a message "ignoring EOIE extension" when + reading the index using Git versions before 2.20. Defaults to + 'true' if index.threads has been explicitly enabled, 'false' + otherwise. + +index.recordOffsetTable:: + Specifies whether the index file should include an "Index Entry + Offset Table" section. This reduces index load time on + multiprocessor machines but produces a message "ignoring IEOT + extension" when reading the index using Git versions before 2.20. + Defaults to 'true' if index.threads has been explicitly enabled, + 'false' otherwise. + +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 + '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. diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt new file mode 100644 index 0000000000..46fa8c6a08 --- /dev/null +++ b/Documentation/config/init.txt @@ -0,0 +1,3 @@ +init.templateDir:: + Specify the directory from which templates will be copied. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) diff --git a/Documentation/config/instaweb.txt b/Documentation/config/instaweb.txt new file mode 100644 index 0000000000..50cb2f7d62 --- /dev/null +++ b/Documentation/config/instaweb.txt @@ -0,0 +1,20 @@ +instaweb.browser:: + Specify the program that will be used to browse your working + repository in gitweb. See linkgit:git-instaweb[1]. + +instaweb.httpd:: + The HTTP daemon command-line to start gitweb on your working + repository. See linkgit:git-instaweb[1]. + +instaweb.local:: + If true the web server started by linkgit:git-instaweb[1] will + be bound to the local IP (127.0.0.1). + +instaweb.modulePath:: + The default module path for linkgit:git-instaweb[1] to use + instead of /usr/lib/apache2/modules. Only used if httpd + is Apache. + +instaweb.port:: + The port number to bind the gitweb httpd to. See + linkgit:git-instaweb[1]. diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt new file mode 100644 index 0000000000..a2d3c7ec44 --- /dev/null +++ b/Documentation/config/interactive.txt @@ -0,0 +1,17 @@ +interactive.singleKey:: + In interactive commands, allow the user to provide one-letter + input with a single key (i.e., without hitting enter). + 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. + +interactive.diffFilter:: + When an interactive command (such as `git add --patch`) shows + a colorized diff, git will pipe the diff through the shell + command defined by this configuration variable. The command may + mark up the diff further for human consumption, provided that it + retains a one-to-one correspondence with the lines in the + original diff. Defaults to disabled (no filtering). diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt new file mode 100644 index 0000000000..208d5fdcaa --- /dev/null +++ b/Documentation/config/log.txt @@ -0,0 +1,50 @@ +log.abbrevCommit:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may + override this option with `--no-abbrev-commit`. + +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. + +log.decorate:: + Print out the ref names of any commits that are shown by the log + command. If 'short' is specified, the ref name prefixes 'refs/heads/', + 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is + specified, the full ref name (including prefix) will be printed. + If 'auto' is specified, then if the output is going to a terminal, + the ref names are shown as if 'short' were given, otherwise no ref + names are shown. This is the same as the `--decorate` option + of the `git log`. + +log.excludeDecoration:: + Exclude the specified patterns from the log decorations. This is + similar to the `--decorate-refs-exclude` command-line option, but + the config option can be overridden by the `--decorate-refs` + option. + +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.graphColors:: + A list of colors, separated by commas, that can be used to draw + history lines in `git log --graph`. + +log.showRoot:: + If true, the initial commit will be shown as a big creation event. + This is equivalent to a diff against an empty tree. + Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which + normally hide the root commit will now show it. True by default. + +log.showSignature:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `--show-signature`. + +log.mailmap:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise + assume `--no-use-mailmap`. True by default. diff --git a/Documentation/config/mailinfo.txt b/Documentation/config/mailinfo.txt new file mode 100644 index 0000000000..3854d4ae37 --- /dev/null +++ b/Documentation/config/mailinfo.txt @@ -0,0 +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 + removes everything from the message body before a scissors + line (i.e. consisting mainly of ">8", "8<" and "-"). diff --git a/Documentation/config/mailmap.txt b/Documentation/config/mailmap.txt new file mode 100644 index 0000000000..48cbc30722 --- /dev/null +++ b/Documentation/config/mailmap.txt @@ -0,0 +1,15 @@ +mailmap.file:: + The location of an augmenting mailmap file. The default + mailmap, located in the root of the repository, is loaded + first, then the mailmap file pointed to by this variable. + The location of the mailmap file may be in a repository + subdirectory, or somewhere outside of the repository itself. + See linkgit:git-shortlog[1] and linkgit:git-blame[1]. + +mailmap.blob:: + Like `mailmap.file`, but consider the value as a reference to a + blob in the repository. If both `mailmap.file` and + `mailmap.blob` are given, both are parsed, with entries from + `mailmap.file` taking precedence. In a bare repository, this + defaults to `HEAD:.mailmap`. In a non-bare repository, it + defaults to empty. diff --git a/Documentation/config/man.txt b/Documentation/config/man.txt new file mode 100644 index 0000000000..a727d987a8 --- /dev/null +++ b/Documentation/config/man.txt @@ -0,0 +1,12 @@ +man.viewer:: + Specify the programs that may be used to display help in the + 'man' format. See linkgit:git-help[1]. + +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].) + +man.<tool>.path:: + Override the path for the given tool that may be used to + display help in the 'man' format. See linkgit:git-help[1]. diff --git a/Documentation/merge-config.txt b/Documentation/config/merge.txt index 662c2713ca..cb2ed58907 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/config/merge.txt @@ -30,7 +30,7 @@ merge.verifySignatures:: If true, this is equivalent to the --verify-signatures command line option. See linkgit:git-merge[1] for details. -include::fmt-merge-msg-config.txt[] +include::fmt-merge-msg.txt[] merge.renameLimit:: The number of files to consider when performing rename detection @@ -39,9 +39,22 @@ merge.renameLimit:: is turned off. merge.renames:: - Whether and how Git detects renames. If set to "false", - rename detection is disabled. If set to "true", basic rename - detection is enabled. Defaults to the value of diff.renames. + Whether Git detects renames. If set to "false", rename detection + is disabled. If set to "true", basic rename detection is enabled. + Defaults to the value of diff.renames. + +merge.directoryRenames:: + Whether Git detects directory renames, affecting what happens at + merge time to new files added to a directory on one side of + history when that directory was renamed on the other side of + history. If merge.directoryRenames is set to "false", directory + rename detection is disabled, meaning that such new files will be + left behind in the old directory. If set to "true", directory + rename detection is enabled, meaning that such new files will be + moved into the new directory. If set to "conflict", a conflict + will be reported for such paths. If merge.renames is false, + merge.directoryRenames is ignored and treated as false. Defaults + to "conflict". merge.renormalize:: Tell Git that canonical representation of files in the @@ -57,13 +70,29 @@ merge.stat:: Whether to print the diffstat between ORIG_HEAD and the merge result at the end of the merge. True by default. +merge.autoStash:: + When set to true, automatically create a temporary stash entry + before the operation begins, and apply it after the operation + ends. This means that you can run merge on a dirty worktree. + However, use with care: the final stash application after a + successful merge might result in non-trivial conflicts. + This option can be overridden by the `--no-autostash` and + `--autostash` options of linkgit:git-merge[1]. + Defaults to false. + merge.tool:: Controls which merge tool is used by linkgit:git-mergetool[1]. The list below shows the valid built-in values. Any other value is treated as a custom merge tool and requires that a corresponding mergetool.<tool>.cmd variable is defined. -include::mergetools-merge.txt[] +merge.guitool:: + Controls which merge tool is used by linkgit:git-mergetool[1] when the + -g/--gui flag is specified. The list below shows the valid built-in values. + Any other value is treated as a custom merge tool and requires that a + corresponding mergetool.<guitool>.cmd variable is defined. + +include::../mergetools-merge.txt[] merge.verbosity:: Controls the amount of output shown by the recursive merge diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt new file mode 100644 index 0000000000..09ed31dbfa --- /dev/null +++ b/Documentation/config/mergetool.txt @@ -0,0 +1,53 @@ +mergetool.<tool>.path:: + Override the path for the given tool. This is useful in case + your tool is not in the PATH. + +mergetool.<tool>.cmd:: + Specify the command to invoke the specified merge tool. The + specified command is evaluated in shell with the following + variables available: 'BASE' is the name of a temporary file + containing the common base of the files to be merged, if available; + 'LOCAL' is the name of a temporary file containing the contents of + the file on the current branch; 'REMOTE' is the name of a temporary + file containing the contents of the file from the branch being + merged; 'MERGED' contains the name of the file to which the merge + tool should write the results of a successful merge. + +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 + indicate the success of the merge. + +mergetool.meld.hasOutput:: + Older versions of `meld` do not support the `--output` option. + Git will attempt to detect whether `meld` supports `--output` + by inspecting the output of `meld --help`. Configuring + `mergetool.meld.hasOutput` will make Git skip these checks and + use the configured value instead. Setting `mergetool.meld.hasOutput` + to `true` tells Git to unconditionally use the `--output` option, + and `false` avoids using `--output`. + +mergetool.keepBackup:: + After performing a merge, the original file with conflict markers + can be saved as a file with a `.orig` extension. If this variable + is set to `false` then this file is not preserved. Defaults to + `true` (i.e. keep the backup files). + +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 + exited. Defaults to `false`. + +mergetool.writeToTemp:: + Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of + conflicting files in the worktree by default. Git will attempt + to use a temporary directory for these files when set `true`. + Defaults to `false`. + +mergetool.prompt:: + Prompt before each invocation of the merge resolution program. diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt new file mode 100644 index 0000000000..aeef56d49a --- /dev/null +++ b/Documentation/config/notes.txt @@ -0,0 +1,59 @@ +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 of linkgit:git-notes[1] for more information on each strategy. + +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 in + 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. ++ +This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` +environment variable, which must be a colon separated list of refs or +globs. ++ +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. + +notes.rewriteMode:: + When copying notes during a rewrite (see the + "notes.rewrite.<command>" option), determines 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. 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. ++ +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. diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt new file mode 100644 index 0000000000..837f1b1679 --- /dev/null +++ b/Documentation/config/pack.txt @@ -0,0 +1,135 @@ +pack.window:: + The size of the window used by linkgit:git-pack-objects[1] when no + window size is given on the command line. Defaults to 10. + +pack.depth:: + The maximum delta depth used by linkgit:git-pack-objects[1] when no + maximum depth is given on the command line. Defaults to 50. + Maximum value is 4095. + +pack.windowMemory:: + The maximum size of memory that is consumed by each thread + in linkgit:git-pack-objects[1] for pack window memory when + no limit is given on the command line. The value can be + suffixed with "k", "m", or "g". When left unconfigured (or + set explicitly to 0), there will be no limit. + +pack.compression:: + An integer -1..9, indicating the compression level for objects + in a pack file. -1 is the zlib default. 0 means no + compression, and 1..9 are various speed/size tradeoffs, 9 being + slowest. If not set, defaults to core.compression. If that is + not set, defaults to -1, the zlib default, which is "a default + compromise between speed and compression (currently equivalent + to level 6)." ++ +Note that changing the compression level will not automatically recompress +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. + +pack.island:: + An extended regular expression configuring a set of delta + islands. See "DELTA ISLANDS" in linkgit:git-pack-objects[1] + for details. + +pack.islandCore:: + Specify an island name which gets to have its objects be + packed first. This creates a kind of pseudo-pack at the front + of one pack, so that the objects from the specified island are + hopefully faster to copy into any pack that should be served + to a user requesting these objects. In practice this means + that the island specified should likely correspond to what is + the most commonly cloned in the repo. See also "DELTA ISLANDS" + in linkgit:git-pack-objects[1]. + +pack.deltaCacheSize:: + The maximum memory in bytes used for caching deltas in + linkgit:git-pack-objects[1] before writing them out to a pack. + This cache is used to speed up the writing object phase by not + having to recompute the final delta result once the best match + for all objects is found. Repacking large repositories on machines + which are tight with memory might be badly impacted by this though, + especially if this cache pushes the system into swapping. + A value of 0 means no limit. The smallest size of 1 byte may be + used to virtually disable this cache. Defaults to 256 MiB. + +pack.deltaCacheLimit:: + The maximum size of a delta, that is cached in + linkgit:git-pack-objects[1]. This cache is used to speed up the + writing object phase by not having to recompute the final delta + result once the best match for all objects is found. + Defaults to 1000. Maximum value is 65535. + +pack.threads:: + Specifies the number of threads to spawn when searching for best + delta matches. This requires that linkgit:git-pack-objects[1] + be compiled with pthreads otherwise this option is ignored with a + 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 + and set the number of threads accordingly. + +pack.indexVersion:: + Specify the default pack index version. Valid values are 1 for + legacy pack index used by Git versions prior to 1.5.2, and 2 for + 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 + 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") +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, +you can use linkgit:git-index-pack[1] on the *.pack file to regenerate +the `*.idx` file. + +pack.packSizeLimit:: + The maximum size of a pack. This setting only affects + packing to a file when repacking, i.e. the git:// protocol + is unaffected. It can be overridden by the `--max-pack-size` + option of linkgit:git-repack[1]. Reaching this limit results + in the creation of multiple packfiles; which in turn prevents + bitmaps from being created. + The minimum size allowed is limited to 1 MiB. + The default is unlimited. + Common unit suffixes of 'k', 'm', or 'g' are + supported. + +pack.useBitmaps:: + When true, git will use pack bitmaps (if available) when packing + to stdout (e.g., during the server side of a fetch). Defaults to + true. You should not generally need to turn this off unless + you are debugging pack bitmaps. + +pack.useSparse:: + When true, git will default to using the '--sparse' option in + 'git pack-objects' when the '--revs' option is present. This + algorithm only walks trees that appear in paths that introduce new + objects. This can have significant performance benefits when + computing a pack to send a small change. However, it is possible + that extra objects are added to the pack-file if the included + commits contain certain types of direct renames. Default is + `true`. + +pack.writeBitmaps (deprecated):: + This is a deprecated synonym for `repack.writeBitmaps`. + +pack.writeBitmapHashCache:: + When true, git will include a "hash cache" section in the bitmap + index (if one is written). This cache can be used to feed git's + delta heuristics, potentially leading to better deltas between + bitmapped and non-bitmapped objects (e.g., when serving a fetch + 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. diff --git a/Documentation/config/pager.txt b/Documentation/config/pager.txt new file mode 100644 index 0000000000..d3731cf66c --- /dev/null +++ b/Documentation/config/pager.txt @@ -0,0 +1,8 @@ +pager.<cmd>:: + If the value is boolean, turns on or off pagination of the + output of a particular Git subcommand when writing to a tty. + Otherwise, turns on pagination for the subcommand using the + pager specified by the value of `pager.<cmd>`. If `--paginate` + or `--no-pager` is specified on the command line, it takes + precedence over this option. To disable pagination for all + commands, set `core.pager` or `GIT_PAGER` to `cat`. diff --git a/Documentation/config/pretty.txt b/Documentation/config/pretty.txt new file mode 100644 index 0000000000..063c6b63d9 --- /dev/null +++ b/Documentation/config/pretty.txt @@ -0,0 +1,9 @@ +pretty.<name>:: + Alias for a --pretty= format string, as specified in + linkgit:git-log[1]. Any aliases defined here can be used just + as the built-in pretty formats could. For example, + running `git config pretty.changelog "format:* %H %s"` + would cause the invocation `git log --pretty=changelog` + to be equivalent to running `git log "--pretty=format:* %H %s"`. + Note that an alias with the same name as a built-in format + will be silently ignored. diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt new file mode 100644 index 0000000000..0b40141613 --- /dev/null +++ b/Documentation/config/protocol.txt @@ -0,0 +1,63 @@ +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 + 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: ++ +-- + +* `always` - protocol is always able to be used. + +* `never` - protocol is never able to be used. + +* `user` - protocol is only able to be used when `GIT_PROTOCOL_FROM_USER` is + either unset or has a value of 1. This policy should be used when you want a + protocol to be directly usable by the user but don't want it used by commands which + execute clone/fetch/push commands without user input, e.g. recursive + submodule initialization. + +-- + +protocol.<name>.allow:: + Set a policy to be used by protocol `<name>` with clone/fetch/push + commands. See `protocol.allow` above for the available policies. ++ +The protocol names currently used by git are: ++ +-- + - `file`: any local file-based path (including `file://` URLs, + or local paths) + + - `git`: the anonymous git protocol over a direct TCP + connection (or proxy, if configured) + + - `ssh`: git over ssh (including `host:path` syntax, + `ssh://`, etc). + + - `http`: git over http, both "smart http" and "dumb http". + Note that this does _not_ include `https`; if you want to configure + both, you must do so individually. + + - any external helpers are named by their protocol (e.g., use + `hg` to allow the `git-remote-hg` helper) +-- + +protocol.version:: + If set, clients will attempt to communicate with a server + using the specified protocol version. If the server does + not support it, communication falls back to version 0. + If unset, the default is `0`. + Supported versions: ++ +-- + +* `0` - the original wire protocol. + +* `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]. + +-- diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.txt new file mode 100644 index 0000000000..5404830609 --- /dev/null +++ b/Documentation/config/pull.txt @@ -0,0 +1,37 @@ +pull.ff:: + By default, Git does not create an extra merge commit when merging + a commit that is a descendant of the current commit. Instead, the + tip of the current branch is fast-forwarded. When set to `false`, + this variable tells Git to create an extra merge commit in such + a case (equivalent to giving the `--no-ff` option from the command + line). When set to `only`, only such fast-forward merges are + allowed (equivalent to giving the `--ff-only` option from the + command line). This setting overrides `merge.ff` when pulling. + +pull.rebase:: + When true, rebase branches on top of the fetched branch, instead + of merging the default branch from the default remote when "git + pull" is run. See "branch.<name>.rebase" for setting this on a + per-branch basis. ++ +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. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). + +pull.octopus:: + The default merge strategy to use when pulling multiple branches + at once. + +pull.twohead:: + The default merge strategy to use when pulling a single branch. diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt new file mode 100644 index 0000000000..f5e5b38c68 --- /dev/null +++ b/Documentation/config/push.txt @@ -0,0 +1,116 @@ +push.default:: + Defines the action `git push` should take if no refspec is + given (whether from the command-line, config, or elsewhere). + Different values are well-suited for + specific workflows; for instance, in a purely central workflow + (i.e. the fetch source is equal to the push destination), + `upstream` is probably what you want. Possible values are: ++ +-- + +* `nothing` - do not push anything (error out) unless a refspec is + given. This is primarily meant for people who want to + avoid mistakes by always being explicit. + +* `current` - push the current branch to update a branch with the same + name on the receiving end. Works in both central and non-central + workflows. + +* `upstream` - push the current branch back to the branch whose + changes are usually integrated into the current branch (which is + called `@{upstream}`). This mode only makes sense if you are + pushing to the same repository you would normally pull from + (i.e. central workflow). + +* `tracking` - This is a deprecated synonym for `upstream`. + +* `simple` - in centralized workflow, work like `upstream` with an + added safety to refuse to push if the upstream branch's name is + different from the local one. ++ +When pushing to a remote that is different from the remote you normally +pull from, work as `current`. This is the safest option and is suited +for beginners. ++ +This mode has become the default in Git 2.0. + +* `matching` - push all branches having the same name on both ends. + This makes the repository you are pushing to remember the set of + branches that will be pushed out (e.g. if you always push 'maint' + and 'master' there and no other branches, the repository you push + to will have these two branches, and your local 'maint' and + 'master' will be pushed there). ++ +To use this mode effectively, you have to make sure _all_ the +branches you would push out are ready to be pushed out before +running 'git push', as the whole point of this mode is to allow you +to push all of the branches in one go. If you usually finish work +on only one branch and push out the result, while other branches are +unfinished, this mode is not for you. Also this mode is not +suitable for pushing into a shared central repository, as other +people may add new branches there, or update the tip of existing +branches outside your control. ++ +This used to be the default, but not since Git 2.0 (`simple` is the +new default). + +-- + +push.followTags:: + If set to true enable `--follow-tags` option by default. You + may override this configuration at time of push by specifying + `--no-follow-tags`. + +push.gpgSign:: + May be set to a boolean value, or the string 'if-asked'. A true + value causes all pushes to be GPG signed, as if `--signed` is + passed to linkgit:git-push[1]. The string 'if-asked' causes + pushes to be signed if the server supports it, as if + `--signed=if-asked` is passed to 'git push'. A false value may + override a value from a lower-priority config file. An explicit + command-line flag always overrides this config option. + +push.pushOption:: + When no `--push-option=<option>` argument is given from the + command line, `git push` behaves as if each <value> of + this variable is given as `--push-option=<value>`. ++ +This is a multi-valued variable, and an empty value can be used in a +higher priority configuration file (e.g. `.git/config` in a +repository) to clear the values inherited from a lower priority +configuration files (e.g. `$HOME/.gitconfig`). ++ +---- + +Example: + +/etc/gitconfig + push.pushoption = a + push.pushoption = b + +~/.gitconfig + push.pushoption = c + +repo/.git/config + push.pushoption = + push.pushoption = b + +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'. + If not set, 'no' is used by default, unless 'submodule.recurse' is + set (in which case a 'true' value means 'on-demand'). diff --git a/Documentation/rebase-config.txt b/Documentation/config/rebase.txt index 42e1ba7575..7f7a07d22f 100644 --- a/Documentation/rebase-config.txt +++ b/Documentation/config/rebase.txt @@ -1,3 +1,16 @@ +rebase.useBuiltin:: + Unused configuration variable. Used in Git versions 2.20 and + 2.21 as an escape hatch to enable the legacy shellscript + implementation of rebase. 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. + +rebase.backend:: + Default backend to use for rebasing. Possible choices are + 'apply' or 'merge'. In the future, if the merge backend gains + all remaining capabilities of the apply backend, this setting + may become unused. + rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. @@ -50,3 +63,8 @@ instead of: ------------------------------------------- + Defaults to false. + +rebase.rescheduleFailedExec:: + Automatically reschedule `exec` commands that failed. This only makes + sense in interactive mode (or when an `--exec` option was provided). + This is the same as specifying the `--reschedule-failed-exec` option. diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt new file mode 100644 index 0000000000..65f78aac37 --- /dev/null +++ b/Documentation/config/receive.txt @@ -0,0 +1,123 @@ +receive.advertiseAtomic:: + By default, git-receive-pack will advertise the atomic push + capability to its clients. If you don't want to advertise this + capability, set this variable to false. + +receive.advertisePushOptions:: + When set to true, git-receive-pack will advertise the push options + capability to its clients. False by default. + +receive.autogc:: + By default, git-receive-pack will run "git-gc --auto" after + receiving data from git-push and updating refs. You can stop + it by setting this variable to false. + +receive.certNonceSeed:: + By setting this variable to a string, `git receive-pack` + will accept a `git push --signed` and verifies 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 + "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 + hooks (instead of what the receive-pack asked the sending + side to include). This may allow writing checks in + `pre-receive` and `post-receive` a bit easier. Instead of + checking `GIT_PUSH_CERT_NONCE_SLOP` environment variable + that records by how many seconds the nonce is stale to + decide if they want to accept the certificate, they only + can check `GIT_PUSH_CERT_NONCE_STATUS` is `OK`. + +receive.fsckObjects:: + If it is set to true, git-receive-pack will check all received + objects. See `transfer.fsckObjects` for what's checked. + Defaults to false. If not set, the value of + `transfer.fsckObjects` is used instead. + +receive.fsck.<msg-id>:: + Acts like `fsck.<msg-id>`, but is used by + linkgit:git-receive-pack[1] instead of + linkgit:git-fsck[1]. See the `fsck.<msg-id>` documentation for + details. + +receive.fsck.skipList:: + Acts like `fsck.skipList`, but is used by + linkgit:git-receive-pack[1] instead of + linkgit:git-fsck[1]. See the `fsck.skipList` documentation for + details. + +receive.keepAlive:: + After receiving the pack from the client, `receive-pack` may + produce no output (if `--quiet` was specified) while processing + the pack, causing some networks to drop the TCP connection. + With this option set, if `receive-pack` does not transmit + any data in this phase for `receive.keepAlive` seconds, it will + send a short keepalive packet. The default is 5 seconds; set + to 0 to disable keepalives entirely. + +receive.unpackLimit:: + If the number of objects received in a push is below this + limit then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. If not set, the value of + `transfer.unpackLimit` is used instead. + +receive.maxInputSize:: + If the size of the incoming pack stream is larger than this + limit, then git-receive-pack will error out, instead of + accepting the pack file. If not set or set to 0, then the size + is unlimited. + +receive.denyDeletes:: + If set to true, git-receive-pack will deny a ref update that deletes + the ref. Use this to prevent such a ref deletion via a push. + +receive.denyDeleteCurrent:: + If set to true, git-receive-pack will deny a ref update that + deletes the currently checked out branch of a non-bare repository. + +receive.denyCurrentBranch:: + If set to true or "refuse", git-receive-pack will deny a ref update + to the currently checked out branch of a non-bare repository. + Such a push is potentially dangerous because it brings the HEAD + out of sync with the index and working tree. If set to "warn", + print a warning of such a push to stderr, but allow the push to + proceed. If set to false or "ignore", allow such pushes with no + message. Defaults to "refuse". ++ +Another option is "updateInstead" which will update the working +tree if pushing into the current branch. This option is +intended for synchronizing working directories when one side is not easily +accessible via interactive ssh (e.g. a live web site, hence the requirement +that the working directory be clean). This mode also comes in handy when +developing inside a VM to test and fix code on different Operating Systems. ++ +By default, "updateInstead" will refuse the push if the working tree or +the index have any difference from the HEAD, but the `push-to-checkout` +hook can be used to customize this. See linkgit:githooks[5]. + +receive.denyNonFastForwards:: + If set to true, git-receive-pack will deny a ref update which is + not a fast-forward. Use this to prevent such an update via a push, + even if that push is forced. This configuration variable is + set when initializing a shared repository. + +receive.hideRefs:: + This variable is the same as `transfer.hideRefs`, but applies + only to `receive-pack` (and so affects pushes, but not fetches). + An attempt to update or delete a hidden ref by `git push` is + rejected. + +receive.updateServerInfo:: + If set to true, git-receive-pack will run git-update-server-info + after receiving data from git-push and updating refs. + +receive.shallowUpdate:: + If set to true, .git/shallow can be updated when new refs + require new shallow roots. Otherwise those refs are rejected. diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt new file mode 100644 index 0000000000..a8e6437a90 --- /dev/null +++ b/Documentation/config/remote.txt @@ -0,0 +1,86 @@ +remote.pushDefault:: + The remote to push to by default. Overrides + `branch.<name>.remote` for all branches, and is overridden by + `branch.<name>.pushRemote` for specific branches. + +remote.<name>.url:: + The URL of a remote repository. See linkgit:git-fetch[1] or + linkgit:git-push[1]. + +remote.<name>.pushurl:: + The push URL of a remote repository. See linkgit:git-push[1]. + +remote.<name>.proxy:: + For remotes that require curl (http, https and ftp), the URL to + the proxy to use for that remote. Set to the empty string to + disable proxying for that remote. + +remote.<name>.proxyAuthMethod:: + For remotes that require curl (http, https and ftp), the method to use for + authenticating against the proxy in use (probably set in + `remote.<name>.proxy`). See `http.proxyAuthMethod`. + +remote.<name>.fetch:: + The default set of "refspec" for linkgit:git-fetch[1]. See + linkgit:git-fetch[1]. + +remote.<name>.push:: + The default set of "refspec" for linkgit:git-push[1]. See + linkgit:git-push[1]. + +remote.<name>.mirror:: + If true, pushing to this remote will automatically behave + as if the `--mirror` option was given on the command line. + +remote.<name>.skipDefaultUpdate:: + If true, this remote will be skipped by default when updating + using linkgit:git-fetch[1] or the `update` subcommand of + linkgit:git-remote[1]. + +remote.<name>.skipFetchAll:: + If true, this remote will be skipped by default when updating + using linkgit:git-fetch[1] or the `update` subcommand of + linkgit:git-remote[1]. + +remote.<name>.receivepack:: + The default program to execute on the remote side when pushing. See + option --receive-pack of linkgit:git-push[1]. + +remote.<name>.uploadpack:: + The default program to execute on the remote side when fetching. See + option --upload-pack of linkgit:git-fetch-pack[1]. + +remote.<name>.tagOpt:: + Setting this value to --no-tags disables automatic tag following when + fetching from remote <name>. Setting it to --tags will fetch every + tag from remote <name>, even if they are not reachable from remote + branch heads. Passing these flags directly to linkgit:git-fetch[1] can + override this setting. See options --tags and --no-tags of + linkgit:git-fetch[1]. + +remote.<name>.vcs:: + Setting this to a value <vcs> will cause Git to interact with + the remote with the git-remote-<vcs> helper. + +remote.<name>.prune:: + When set to true, fetching from this remote by default will also + remove any remote-tracking references that no longer exist on the + remote (as if the `--prune` option was given on the command line). + Overrides `fetch.prune` settings, if any. + +remote.<name>.pruneTags:: + When set to true, fetching from this remote by default will also + remove any local tags that no longer exist on the remote if pruning + is activated in general via `remote.<name>.prune`, `fetch.prune` or + `--prune`. Overrides `fetch.pruneTags` settings, if any. ++ +See also `remote.<name>.prune` and the PRUNING section of +linkgit:git-fetch[1]. + +remote.<name>.promisor:: + When set to true, this remote will be used to fetch promisor + objects. + +remote.<name>.partialclonefilter:: + The filter that will be applied when fetching from this + promisor remote. diff --git a/Documentation/config/remotes.txt b/Documentation/config/remotes.txt new file mode 100644 index 0000000000..4cfe03221e --- /dev/null +++ b/Documentation/config/remotes.txt @@ -0,0 +1,3 @@ +remotes.<group>:: + The list of remotes which are fetched by "git remote update + <group>". See linkgit:git-remote[1]. diff --git a/Documentation/config/repack.txt b/Documentation/config/repack.txt new file mode 100644 index 0000000000..9c413e177e --- /dev/null +++ b/Documentation/config/repack.txt @@ -0,0 +1,27 @@ +repack.useDeltaBaseOffset:: + By default, linkgit:git-repack[1] creates packs that use + delta-base offset. If you need to share your repository with + Git older than version 1.4.4, either directly or via a dumb + protocol such as http, then you need to set this option to + "false" and repack. Access from old Git versions over the + native protocol are unaffected by this option. + +repack.packKeptObjects:: + If set to true, makes `git repack` act as if + `--pack-kept-objects` was passed. See linkgit:git-repack[1] for + details. Defaults to `false` normally, but `true` if a bitmap + index is being written (either via `--write-bitmap-index` or + `repack.writeBitmaps`). + +repack.useDeltaIslands:: + If set to true, makes `git repack` act as if `--delta-islands` + was passed. Defaults to `false`. + +repack.writeBitmaps:: + When true, git will write a bitmap index when packing all + objects to disk (e.g., when `git repack -a` is run). This + index can speed up the "counting objects" phase of subsequent + packs created for clones and fetches, at the cost of some disk + 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. diff --git a/Documentation/config/rerere.txt b/Documentation/config/rerere.txt new file mode 100644 index 0000000000..40abdf6a6b --- /dev/null +++ b/Documentation/config/rerere.txt @@ -0,0 +1,12 @@ +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. + +rerere.enabled:: + Activate recording of resolved conflicts, so that identical + conflict hunks can be resolved automatically, should they be + encountered again. By default, linkgit:git-rerere[1] is + enabled if there is an `rr-cache` directory under the + `$GIT_DIR`, e.g. if "rerere" was previously used in the + repository. diff --git a/Documentation/config/reset.txt b/Documentation/config/reset.txt new file mode 100644 index 0000000000..63b7c45aac --- /dev/null +++ b/Documentation/config/reset.txt @@ -0,0 +1,2 @@ +reset.quiet:: + When set to true, 'git reset' will default to the '--quiet' option. diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt new file mode 100644 index 0000000000..0006faf800 --- /dev/null +++ b/Documentation/config/sendemail.txt @@ -0,0 +1,63 @@ +sendemail.identity:: + A configuration identity. When given, causes values in the + 'sendemail.<identity>' subsection to take precedence over + values in the 'sendemail' section. The default identity is + the value of `sendemail.identity`. + +sendemail.smtpEncryption:: + See linkgit:git-send-email[1] for description. Note that this + setting is not subject to the 'identity' mechanism. + +sendemail.smtpssl (deprecated):: + Deprecated alias for 'sendemail.smtpEncryption = ssl'. + +sendemail.smtpsslcertpath:: + Path to ca-certificates (either a directory or a single file). + Set it to an empty string to disable certificate verification. + +sendemail.<identity>.*:: + Identity-specific versions of the 'sendemail.*' parameters + found below, taking precedence over those when this + identity is selected, through either the command-line or + `sendemail.identity`. + +sendemail.aliasesFile:: +sendemail.aliasFileType:: +sendemail.annotate:: +sendemail.bcc:: +sendemail.cc:: +sendemail.ccCmd:: +sendemail.chainReplyTo:: +sendemail.confirm:: +sendemail.envelopeSender:: +sendemail.from:: +sendemail.multiEdit:: +sendemail.signedoffbycc:: +sendemail.smtpPass:: +sendemail.suppresscc:: +sendemail.suppressFrom:: +sendemail.to:: +sendemail.tocmd:: +sendemail.smtpDomain:: +sendemail.smtpServer:: +sendemail.smtpServerPort:: +sendemail.smtpServerOption:: +sendemail.smtpUser:: +sendemail.thread:: +sendemail.transferEncoding:: +sendemail.validate:: +sendemail.xmailer:: + See linkgit:git-send-email[1] for description. + +sendemail.signedoffcc (deprecated):: + Deprecated alias for `sendemail.signedoffbycc`. + +sendemail.smtpBatchSize:: + Number of messages to be sent per connection, after that a relogin + will happen. If the value is 0 or undefined, send all messages in + one connection. + See also the `--batch-size` option of linkgit:git-send-email[1]. + +sendemail.smtpReloginDelay:: + Seconds wait before reconnecting to smtp server. + See also the `--relogin-delay` option of linkgit:git-send-email[1]. diff --git a/Documentation/config/sequencer.txt b/Documentation/config/sequencer.txt new file mode 100644 index 0000000000..b48d532a96 --- /dev/null +++ b/Documentation/config/sequencer.txt @@ -0,0 +1,5 @@ +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. diff --git a/Documentation/config/showbranch.txt b/Documentation/config/showbranch.txt new file mode 100644 index 0000000000..e79ecd9ee9 --- /dev/null +++ b/Documentation/config/showbranch.txt @@ -0,0 +1,3 @@ +showBranch.default:: + The default set of branches for linkgit:git-show-branch[1]. + See linkgit:git-show-branch[1]. diff --git a/Documentation/config/splitindex.txt b/Documentation/config/splitindex.txt new file mode 100644 index 0000000000..afdb186df8 --- /dev/null +++ b/Documentation/config/splitindex.txt @@ -0,0 +1,24 @@ +splitIndex.maxPercentChange:: + When the split index feature is used, this specifies the + 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 + shared index is never 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]. + +splitIndex.sharedIndexExpire:: + When the split index feature is used, shared index files that + were not modified since the time this variable specifies will + be removed when a new shared index file is created. The value + "now" expires all entries immediately, and "never" suppresses + expiration altogether. + The default value is "2.weeks.ago". + Note that a shared index file is considered modified (for the + purpose of expiration) each time a new split-index file is + either created based on it or read from it. + See linkgit:git-update-index[1]. diff --git a/Documentation/config/ssh.txt b/Documentation/config/ssh.txt new file mode 100644 index 0000000000..2ca4bf93e1 --- /dev/null +++ b/Documentation/config/ssh.txt @@ -0,0 +1,35 @@ +ssh.variant:: + By default, Git determines the command line arguments to use + based on the basename of the configured SSH command (configured + using the environment variable `GIT_SSH` or `GIT_SSH_COMMAND` or + the config setting `core.sshCommand`). If the basename is + unrecognized, Git will attempt to detect support of OpenSSH + options by first invoking the configured SSH command with the + `-G` (print configuration) option and will subsequently use + OpenSSH options (if that is successful) or no options besides + the host and remote command (if it fails). ++ +The config variable `ssh.variant` can be set to override this detection. +Valid values are `ssh` (to use OpenSSH options), `plink`, `putty`, +`tortoiseplink`, `simple` (no options except the host and remote command). +The default auto-detection can be explicitly requested using the value +`auto`. Any other value is treated as `ssh`. This setting can also be +overridden via the environment variable `GIT_SSH_VARIANT`. ++ +The current command-line parameters used for each variant are as +follows: ++ +-- + +* `ssh` - [-p port] [-4] [-6] [-o option] [username@]host command + +* `simple` - [username@]host command + +* `plink` or `putty` - [-P port] [-4] [-6] [username@]host command + +* `tortoiseplink` - [-P port] [-4] [-6] -batch [username@]host command + +-- ++ +Except for the `simple` variant, command-line parameters are likely to +change as git gains new features. diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt new file mode 100644 index 0000000000..00eb35434e --- /dev/null +++ b/Documentation/config/stash.txt @@ -0,0 +1,16 @@ +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.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]. + +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]. diff --git a/Documentation/config/status.txt b/Documentation/config/status.txt new file mode 100644 index 0000000000..0fc704ab80 --- /dev/null +++ b/Documentation/config/status.txt @@ -0,0 +1,77 @@ +status.relativePaths:: + By default, linkgit:git-status[1] shows paths relative to the + current directory. Setting this variable to `false` shows paths + relative to the repository root (this was the default for Git + prior to v1.5.4). + +status.short:: + Set to true to enable --short by default in linkgit:git-status[1]. + The option --no-short takes precedence over this variable. + +status.branch:: + Set to true to enable --branch by default in linkgit:git-status[1]. + The option --no-branch takes precedence over this variable. + +status.aheadBehind:: + Set to true to enable `--ahead-behind` and false to enable + `--no-ahead-behind` by default in linkgit:git-status[1] for + non-porcelain status formats. Defaults to true. + +status.displayCommentPrefix:: + If set to true, linkgit:git-status[1] will insert a comment + prefix before each output line (starting with + `core.commentChar`, i.e. `#` by default). This was the + behavior of linkgit:git-status[1] in Git 1.8.4 and previous. + Defaults to false. + +status.renameLimit:: + The number of files to consider when performing rename detection + in linkgit:git-status[1] and linkgit:git-commit[1]. Defaults to + the value of diff.renameLimit. + +status.renames:: + Whether and how Git detects renames in linkgit:git-status[1] and + linkgit:git-commit[1] . If set to "false", rename detection is + disabled. If set to "true", basic rename detection is enabled. + If set to "copies" or "copy", Git will detect copies, as well. + Defaults to the value of diff.renames. + +status.showStash:: + If set to true, linkgit:git-status[1] will display the number of + entries currently stashed away. + Defaults to false. + +status.showUntrackedFiles:: + By default, linkgit:git-status[1] and linkgit:git-commit[1] show + files which are not currently tracked by Git. Directories which + 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 + the untracked files. Possible values are: ++ +-- +* `no` - Show no untracked files. +* `normal` - Show untracked files and directories. +* `all` - Show also individual files in untracked directories. +-- ++ +If this variable is not specified, it defaults to 'normal'. +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 + 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 + that the summary output command will be suppressed for all + submodules when `diff.ignoreSubmodules` is set to 'all' or only + for those submodules where `submodule.<name>.ignore=all`. The only + exception to that rule is that status and commit will show staged + submodule changes. To + also view the summary for ignored submodules you can either use + the --ignore-submodules=dirty command-line option or the 'git + submodule summary' command, which shows a similar output but does + not honor these settings. diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt new file mode 100644 index 0000000000..d7a63c8c12 --- /dev/null +++ b/Documentation/config/submodule.txt @@ -0,0 +1,92 @@ +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 + 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. + +submodule.<name>.update:: + The method by which a submodule is updated by 'git submodule update', + which is the only affected command, others such as + 'git checkout --recurse-submodules' are unaffected. It exists for + historical reasons, when 'git submodule' was the only command to + interact with submodules; settings like `submodule.active` + and `pull.rebase` are more specific. It is populated by + `git submodule init` from the linkgit:gitmodules[5] file. + See description of 'update' command in linkgit:git-submodule[1]. + +submodule.<name>.branch:: + The remote branch name for a submodule, used by `git submodule + update --remote`. Set this option to override the value found in + the `.gitmodules` file. See linkgit:git-submodule[1] and + linkgit:gitmodules[5] for details. + +submodule.<name>.fetchRecurseSubmodules:: + This option can be used to control recursive fetching of this + submodule. It can be overridden by using the --[no-]recurse-submodules + command-line option to "git fetch" and "git pull". + This setting will override that from in the linkgit:gitmodules[5] + file. + +submodule.<name>.ignore:: + Defines under what circumstances "git status" and the diff family show + 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 + 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. + Using "none" (the default when this option is not set) also shows + submodules that have untracked files in their work tree as changed. + This setting overrides any setting made in .gitmodules for this submodule, + both settings can be overridden on the command line by using the + "--ignore-submodules" option. The 'git submodule' commands are not + affected by this setting. + +submodule.<name>.active:: + Boolean value indicating if the submodule is of interest to git + commands. This config option takes precedence over the + submodule.active config option. See linkgit:gitsubmodules[7] for + details. + +submodule.active:: + A repeated field which contains a pathspec used to match against a + submodule's path to determine if the submodule is of interest to git + 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`. + 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. + A positive integer allows up to that number of submodules fetched + in parallel. A value of 0 will give some reasonable default. + If unset, it defaults to 1. + +submodule.alternateLocation:: + Specifies how the submodules obtain alternates when submodules are + cloned. Possible values are `no`, `superproject`. + By default `no` is assumed, which doesn't add references. When the + value is set to `superproject` the submodule to be cloned computes + its alternates location relative to the superprojects alternate. + +submodule.alternateErrorStrategy:: + Specifies how to treat errors with the alternates for a submodule + as computed via `submodule.alternateLocation`. Possible values are + `ignore`, `info`, `die`. Default is `die`. Note that if set to `ignore` + or `info`, and if there is an error with the computed alternate, the + clone proceeds as if no alternate was specified. diff --git a/Documentation/config/tag.txt b/Documentation/config/tag.txt new file mode 100644 index 0000000000..5062a057ff --- /dev/null +++ b/Documentation/config/tag.txt @@ -0,0 +1,17 @@ +tag.forceSignAnnotated:: + A boolean to specify whether annotated tags created should be GPG signed. + If `--annotate` is specified on the command line, it takes + precedence over this option. + +tag.sort:: + This variable controls the sort ordering of tags when displayed by + linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the + value of this variable will be used as the default. + +tag.gpgSign:: + A boolean to specify whether all tags should be GPG signed. + Use of this option when running in an automated script can + result in a large number of tags being signed. It is therefore + convenient to use an agent to avoid typing your gpg passphrase + several times. Note that this option doesn't affect tag signing + behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options. diff --git a/Documentation/config/tar.txt b/Documentation/config/tar.txt new file mode 100644 index 0000000000..de8ff48ea9 --- /dev/null +++ b/Documentation/config/tar.txt @@ -0,0 +1,6 @@ +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) and + linkgit:git-archive[1]. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt new file mode 100644 index 0000000000..01d3afd8a8 --- /dev/null +++ b/Documentation/config/trace2.txt @@ -0,0 +1,71 @@ +Trace2 config settings are only read from the system and global +config files; repository local and worktree config files and `-c` +command line arguments are not respected. + +trace2.normalTarget:: + This variable controls the normal target destination. + It may be overridden by the `GIT_TRACE2` environment variable. + The following table shows possible values. + +trace2.perfTarget:: + This variable controls the performance target destination. + It may be overridden by the `GIT_TRACE2_PERF` environment variable. + The following table shows possible values. + +trace2.eventTarget:: + This variable controls the event target destination. + It may be overridden by the `GIT_TRACE2_EVENT` environment variable. + The following table shows possible values. ++ +include::../trace2-target-values.txt[] + +trace2.normalBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from normal output. May be overridden by the + `GIT_TRACE2_BRIEF` environment variable. Defaults to false. + +trace2.perfBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from PERF output. May be overridden by the + `GIT_TRACE2_PERF_BRIEF` environment variable. Defaults to false. + +trace2.eventBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from event output. May be overridden by the + `GIT_TRACE2_EVENT_BRIEF` environment variable. Defaults to false. + +trace2.eventNesting:: + Integer. Specifies desired depth of nested regions in the + event output. Regions deeper than this value will be + omitted. May be overridden by the `GIT_TRACE2_EVENT_NESTING` + environment variable. Defaults to 2. + +trace2.configParams:: + A comma-separated list of patterns of "important" config + settings that should be recorded in the trace2 output. + For example, `core.*,remote.*.url` would cause the trace2 + output to contain events listing each configured remote. + May be overridden by the `GIT_TRACE2_CONFIG_PARAMS` environment + variable. Unset by default. + +trace2.envVars:: + A comma-separated list of "important" environment variables that should + be recorded in the trace2 output. For example, + `GIT_HTTP_USER_AGENT,GIT_CONFIG` would cause the trace2 output to + contain events listing the overrides for HTTP user agent and the + location of the Git configuration file (assuming any are set). May be + overriden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by + default. + +trace2.destinationDebug:: + Boolean. When true Git will print error messages when a + trace target destination cannot be opened for writing. + By default, these errors are suppressed and tracing is + silently disabled. May be overridden by the + `GIT_TRACE2_DST_DEBUG` environment variable. + +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 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 new file mode 100644 index 0000000000..f5b6245270 --- /dev/null +++ b/Documentation/config/transfer.txt @@ -0,0 +1,71 @@ +transfer.fsckObjects:: + When `fetch.fsckObjects` or `receive.fsckObjects` are + not set, the value of this variable is used instead. + Defaults to false. ++ +When set, the fetch or receive will abort in the case of a malformed +object or a link to a nonexistent object. In addition, various other +issues are checked for, including legacy issues (see `fsck.<msg-id>`), +and potential security issues like the existence of a `.GIT` directory +or a malicious `.gitmodules` file (see the release notes for v2.2.1 +and v2.17.1 for details). Other sanity and security checks may be +added in future releases. ++ +On the receiving side, failing fsckObjects will make those objects +unreachable, see "QUARANTINE ENVIRONMENT" in +linkgit:git-receive-pack[1]. On the fetch side, malformed objects will +instead be left unreferenced in the repository. ++ +Due to the non-quarantine nature of the `fetch.fsckObjects` +implementation it cannot be relied upon to leave the object store +clean like `receive.fsckObjects` can. ++ +As objects are unpacked they're written to the object store, so there +can be cases where malicious objects get introduced even though the +"fetch" failed, only to have a subsequent "fetch" succeed because only +new incoming objects are checked, not those that have already been +written to the object store. That difference in behavior should not be +relied upon. In the future, such objects may be quarantined for +"fetch" as well. ++ +For now, the paranoid need to find some way to emulate the quarantine +environment if they'd like the same protection as "push". E.g. in the +case of an internal mirror do the mirroring in two steps, one to fetch +the untrusted objects, and then do a second "push" (which will use the +quarantine) to another internal repo, and have internal clients +consume this pushed-to repository, or embargo internal fetches and +only allow them once a full "fsck" has run (and no new fetches have +happened in the meantime). + +transfer.hideRefs:: + String(s) `receive-pack` and `upload-pack` use to decide which + refs to omit from their initial advertisements. Use more than + one definition to specify multiple prefix strings. A ref that is + under the hierarchies listed in the value of this variable is + excluded, and is hidden when responding to `git push` or `git + fetch`. See `receive.hideRefs` and `uploadpack.hideRefs` for + program-specific versions of this config. ++ +You may also include a `!` in front of the ref name to negate the entry, +explicitly exposing it, even if an earlier entry marked it as hidden. +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. +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. ++ +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 +linkgit:gitnamespaces[7] man page; it's best to keep private data in a +separate repository. + +transfer.unpackLimit:: + When `fetch.unpackLimit` or `receive.unpackLimit` are + not set, the value of this variable is used instead. + The default value is 100. diff --git a/Documentation/config/uploadarchive.txt b/Documentation/config/uploadarchive.txt new file mode 100644 index 0000000000..e0698e8c1d --- /dev/null +++ b/Documentation/config/uploadarchive.txt @@ -0,0 +1,6 @@ +uploadarchive.allowUnreachable:: + If true, allow clients to use `git archive --remote` to request + any tree, whether reachable from the ref tips or not. See the + discussion in the "SECURITY" section of + linkgit:git-upload-archive[1] for more details. Defaults to + `false`. diff --git a/Documentation/config/uploadpack.txt b/Documentation/config/uploadpack.txt new file mode 100644 index 0000000000..ed1c835695 --- /dev/null +++ b/Documentation/config/uploadpack.txt @@ -0,0 +1,65 @@ +uploadpack.hideRefs:: + This variable is the same as `transfer.hideRefs`, but applies + only to `upload-pack` (and so affects only fetches, not pushes). + An attempt to fetch a hidden ref by `git fetch` will fail. See + also `uploadpack.allowTipSHA1InWant`. + +uploadpack.allowTipSHA1InWant:: + When `uploadpack.hideRefs` is in effect, allow `upload-pack` + to accept a fetch request that asks for an object at the tip + of a hidden ref (by default, such a request is rejected). + See also `uploadpack.hideRefs`. Even if this is false, a client + may be able to steal objects via the techniques described in the + "SECURITY" section of the linkgit:gitnamespaces[7] man page; it's + best to keep private data in a separate repository. + +uploadpack.allowReachableSHA1InWant:: + Allow `upload-pack` to accept a fetch request that asks for an + object that is reachable from any ref tip. However, note that + calculating object reachability is computationally expensive. + Defaults to `false`. Even if this is false, a client may be able + to steal objects via the techniques described in the "SECURITY" + section of the linkgit:gitnamespaces[7] man page; it's best to + keep private data in a separate repository. + +uploadpack.allowAnySHA1InWant:: + Allow `upload-pack` to accept a fetch request that asks for any + object at all. + Defaults to `false`. + +uploadpack.keepAlive:: + When `upload-pack` has started `pack-objects`, there may be a + quiet period while `pack-objects` prepares the pack. Normally + it would output progress information, but if `--quiet` was used + for the fetch, `pack-objects` will output nothing at all until + the pack data begins. Some clients and networks may consider + the server to be hung and give up. Setting this option instructs + `upload-pack` to send an empty keepalive packet every + `uploadpack.keepAlive` seconds. Setting this option to 0 + disables keepalive packets entirely. The default is 5 seconds. + +uploadpack.packObjectsHook:: + If this option is set, when `upload-pack` would run + `git pack-objects` to create a packfile for a client, it will + run this shell command instead. The `pack-objects` command and + arguments it _would_ have run (including the `git pack-objects` + at the beginning) are appended to the shell command. The stdin + and stdout of the hook are treated as if `pack-objects` itself + was run. I.e., `upload-pack` will feed input intended for + `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). + +uploadpack.allowFilter:: + If this option is set, `upload-pack` will support partial + clone and partial fetch object filtering. + +uploadpack.allowRefInWant:: + If this option is set, `upload-pack` will support the `ref-in-want` + feature of the protocol version 2 `fetch` command. This feature + is intended for the benefit of load-balanced servers which may + not have the same view of what OIDs their refs point to due to + replication delay. diff --git a/Documentation/config/url.txt b/Documentation/config/url.txt new file mode 100644 index 0000000000..e5566c371d --- /dev/null +++ b/Documentation/config/url.txt @@ -0,0 +1,30 @@ +url.<base>.insteadOf:: + Any URL that starts with this value will be rewritten to + start, instead, with <base>. In cases where some site serves a + large number of repositories, and serves them with multiple + access methods, and some users need to use different access + methods, this feature allows people to specify any of the + equivalent URLs and have Git automatically rewrite the URL to + the best alternative for the particular user, even for a + never-before-seen repository on the site. When more than one + insteadOf strings match a given URL, the longest match is used. ++ +Note that any protocol restrictions will be applied to the rewritten +URL. If the rewrite changes the URL to use a custom protocol or remote +helper, you may need to adjust the `protocol.*.allow` config to permit +the request. In particular, protocols you expect to use for submodules +must be set to `always` rather than the default of `user`. See the +description of `protocol.allow` above. + +url.<base>.pushInsteadOf:: + Any URL that starts with this value will not be pushed to; + instead, it will be rewritten to start with <base>, and the + resulting URL will be pushed to. In cases where some site serves + a large number of repositories, and serves them with multiple + access methods, some of which do not allow push, this feature + allows people to specify a pull-only URL and have Git + automatically use an appropriate URL to push, even for a + never-before-seen repository on the site. When more than one + pushInsteadOf strings match a given URL, the longest match is + used. If a remote has an explicit pushurl, Git will ignore this + setting for that remote. diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt new file mode 100644 index 0000000000..59aec7c3ae --- /dev/null +++ b/Documentation/config/user.txt @@ -0,0 +1,38 @@ +user.name:: +user.email:: +author.name:: +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 + objects. + If you need the `author` or `committer` to be different, the + `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`, + `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, + `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 +environment variables section of linkgit:git[1] for more information on +these settings and the `credential.username` option if you're looking +for authentication credentials instead. + +user.useConfigOnly:: + Instruct Git to avoid trying to guess defaults for `user.email` + and `user.name`, and instead retrieve the values only from the + configuration. For example, if you have multiple email addresses + and would like to use a different one for each repository, then + with this configuration option set to `true` in the global config + along with a name, Git will prompt you to set up an email before + making new commits in a newly cloned repository. + Defaults to `false`. + +user.signingKey:: + If linkgit:git-tag[1] or linkgit:git-commit[1] is not selecting the + key you want it to automatically when creating a signed tag or + 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. diff --git a/Documentation/config/versionsort.txt b/Documentation/config/versionsort.txt new file mode 100644 index 0000000000..6c7cc054fa --- /dev/null +++ b/Documentation/config/versionsort.txt @@ -0,0 +1,33 @@ +versionsort.prereleaseSuffix (deprecated):: + Deprecated alias for `versionsort.suffix`. Ignored if + `versionsort.suffix` is set. + +versionsort.suffix:: + Even when version sort is used in linkgit:git-tag[1], tagnames + with the same base version but different suffixes are still sorted + lexicographically, resulting e.g. in prerelease tags appearing + after the main release (e.g. "1.0-rc1" after "1.0"). This + variable can be specified to determine the sorting order of tags + with different suffixes. ++ +By specifying a single suffix in this variable, any tagname containing +that suffix will appear before the corresponding main release. E.g. if +the variable is set to "-rc", then all "1.0-rcX" tags will appear before +"1.0". If specified multiple times, once per suffix, then the order of +suffixes in the configuration will determine the sorting order of tagnames +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 +"-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 +be sorted according to the suffix which starts at the earliest position in +the tagname. If more than one different matching suffixes start 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 +in multiple config files. diff --git a/Documentation/config/web.txt b/Documentation/config/web.txt new file mode 100644 index 0000000000..beec8d1303 --- /dev/null +++ b/Documentation/config/web.txt @@ -0,0 +1,4 @@ +web.browser:: + Specify a web browser that may be used by some commands. + Currently only linkgit:git-instaweb[1] and linkgit:git-help[1] + may use it. diff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.txt new file mode 100644 index 0000000000..048e349482 --- /dev/null +++ b/Documentation/config/worktree.txt @@ -0,0 +1,9 @@ +worktree.guessRemote:: + If no branch is specified and neither `-b` nor `-B` nor + `--detach` is used, then `git worktree add` defaults to + creating a new branch from HEAD. If `worktree.guessRemote` is + set to true, `worktree add` tries to find a remote-tracking + branch whose name uniquely matches the new branch name. If + such a branch exists, it is checked out and set as "upstream" + for the new branch. If no such match can be found, it falls + back to creating a new branch from the current HEAD. diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index 6926e0a4c8..f1097fac69 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -20,7 +20,9 @@ RFC 2822:: ISO 8601:: Time and date specified by the ISO 8601 standard, for example `2005-04-07T22:13:13`. The parser accepts a space instead of the - `T` character as well. + `T` character as well. Fractional parts of a second will be ignored, + for example `2005-04-07T22:13:13.019` will be treated as + `2005-04-07T22:13:13`. + NOTE: In addition, the date part is accepted in the following formats: `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 706916c94c..fbbd410a84 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -26,12 +26,12 @@ line per changed file. An output line is formatted this way: ------------------------------------------------ -in-place edit :100644 100644 bcd1234... 0123456... M file0 -copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2 -rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3 -create :000000 100644 0000000... 1234567... A file4 -delete :100644 000000 1234567... 0000000... D file5 -unmerged :000000 000000 0000000... 0000000... U file6 +in-place edit :100644 100644 bcd1234 0123456 M file0 +copy-edit :100644 100644 abcd123 1234567 C68 file1 file2 +rename-edit :100644 100644 abcd123 1234567 R86 file1 file3 +create :000000 100644 0000000 1234567 A file4 +delete :100644 000000 1234567 0000000 D file5 +unmerged :000000 000000 0000000 0000000 U file6 ------------------------------------------------ That is, from the left to the right: @@ -61,7 +61,7 @@ Possible status letters are: - R: renaming of a file - T: change in the type of the file - U: file is unmerged (you must complete the merge before it can -be committed) + be committed) - X: "unknown" change type (most probably a bug, please report it) Status letters C and R are always followed by a score (denoting the @@ -75,7 +75,7 @@ and it is out of sync with the index. Example: ------------------------------------------------ -:100644 100644 5be4a4...... 000000...... M file.c +:100644 100644 5be4a4a 0000000 M file.c ------------------------------------------------ Without the `-z` option, pathnames with "unusual" characters are @@ -95,12 +95,26 @@ from the format described above in the following way: . there are more "src" modes and "src" sha1 . status is concatenated status characters for each parent . no optional "score" number -. single path, only for "dst" +. tab-separated pathname(s) of the file -Example: +For `-c` and `--cc`, only the destination or final path is shown even +if the file was renamed on any side of history. With +`--combined-all-paths`, the name of the path in each parent is shown +followed by the name of the path in the merge commit. + +Examples for `-c` and `--cc` without `--combined-all-paths`: +------------------------------------------------ +::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c +::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh +::100644 100644 100644 e07d6c5 9042e82 ee91881 RR phooey.c +------------------------------------------------ + +Examples when `--combined-all-paths` added to either `-c` or `--cc`: ------------------------------------------------ -::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM describe.c +::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c desc.c desc.c +::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM foo.sh bar.sh bar.sh +::100644 100644 100644 e07d6c5 9042e82 ee91881 RR fooey.c fuey.c phooey.c ------------------------------------------------ Note that 'combined diff' lists only files which were modified from diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 231105cff4..e8ed6470fb 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -1,11 +1,15 @@ -Generating patches with -p --------------------------- - -When "git-diff-index", "git-diff-tree", or "git-diff-files" are run -with a `-p` option, "git diff" without the `--raw` option, or -"git log" with the "-p" option, they -do not produce the output described above; instead they produce a -patch file. You can customize the creation of such patches via the +Generating patch text with -p +----------------------------- + +Running +linkgit:git-diff[1], +linkgit:git-log[1], +linkgit:git-show[1], +linkgit:git-diff-index[1], +linkgit:git-diff-tree[1], or +linkgit:git-diff-files[1] +with the `-p` option produces patch text. +You can customize the creation of patch text via the `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables. What the -p option produces is slightly different from the traditional @@ -49,7 +53,7 @@ similarity index value of 100% is thus reserved for two equal files, while 100% dissimilarity means that no line from the old file made it into the new one. + -The index line includes the SHA-1 checksum before and after the change. +The index line includes the blob object names before and after the change. The <mode> is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode. @@ -70,7 +74,7 @@ separate lines indicate the old and the new mode. rename to a -combined diff format +Combined diff format -------------------- Any diff-generating command can take the `-c` or `--cc` option to @@ -80,7 +84,7 @@ linkgit:git-show[1]. Note also that you can give the `-m` option to any of these commands to force generation of diffs with individual parents of a merge. -A 'combined diff' format looks like this: +A "combined diff" format looks like this: ------------ diff --combined describe.c @@ -113,11 +117,11 @@ index fabadb8,cc95eb0..4866510 ------------ 1. It is preceded with a "git diff" header, that looks like - this (when `-c` option is used): + this (when the `-c` option is used): diff --combined file + -or like this (when `--cc` option is used): +or like this (when the `--cc` option is used): diff --cc file @@ -143,11 +147,24 @@ copying detection) are designed to work with diff of two Similar to two-line header for 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 + + --- a/file + --- a/file + --- a/file + +++ b/file ++ +This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents. 4. Chunk header format is modified to prevent people from accidentally feeding it to `patch -p1`. Combined diff format was created for review of merge commit changes, and was not - meant for apply. The change is similar to the change in the + meant to be applied. The change is similar to the change in the extended 'index' header: @@@ <from-file-range> <from-file-range> <to-file-range> @@@ diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 0378cd574e..bb31f0c42b 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -36,11 +36,21 @@ endif::git-format-patch[] -U<n>:: --unified=<n>:: Generate diffs with <n> lines of context instead of - the usual three. + the usual three. Implies `--patch`. ifndef::git-format-patch[] Implies `-p`. endif::git-format-patch[] +--output=<file>:: + Output to a specific file instead of stdout. + +--output-indicator-new=<char>:: +--output-indicator-old=<char>:: +--output-indicator-context=<char>:: + Specify the character used to indicate new, old or context + lines in the generated patch. Normally they are '+', '-' and + ' ' respectively. + ifndef::git-format-patch[] --raw:: ifndef::git-log[] @@ -148,6 +158,7 @@ These parameters can also be set individually with `--stat-width=<width>`, number of modified files, as well as number of added and deleted lines. +-X[<param1,param2,...>]:: --dirstat[=<param1,param2,...>]:: Output the distribution of relative amount of changes for each sub-directory. The behavior of `--dirstat` can be customized by @@ -192,6 +203,12 @@ directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: `--dirstat=files,10,cumulative`. +--cumulative:: + Synonym for --dirstat=cumulative + +--dirstat-by-file[=<param1,param2>...]:: + Synonym for --dirstat=files,param1,param2... + --summary:: Output a condensed summary of extended header information such as creations, renames and mode changes. @@ -293,8 +310,12 @@ dimmed-zebra:: `dimmed_zebra` is a deprecated synonym. -- +--no-color-moved:: + Turn off move detection. This can be used to override configuration + settings. It is the same as `--color-moved=no`. + --color-moved-ws=<modes>:: - This configures how white spaces are ignored when performing the + This configures how whitespace is ignored when performing the move detection for `--color-moved`. ifdef::git-diff[] It can be set by the `diff.colorMovedWS` configuration setting. @@ -302,6 +323,8 @@ endif::git-diff[] These modes can be given as a comma separated list: + -- +no:: + Do not ignore whitespace when performing move detection. ignore-space-at-eol:: Ignore changes in whitespace at EOL. ignore-space-change:: @@ -312,12 +335,17 @@ ignore-all-space:: Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none. allow-indentation-change:: - Initially ignore any white spaces in the move detection, then + Initially ignore any whitespace in the move detection, then group the moved code blocks only into a block if the change in whitespace is the same per line. This is incompatible with the other modes. -- +--no-color-moved-ws:: + Do not ignore whitespace when performing move detection. This can be + used to override configuration settings. It is the same as + `--color-moved-ws=no`. + --word-diff[=<mode>]:: Show a word diff, using the <mode> to delimit changed words. By default, words are delimited by whitespace; see @@ -375,6 +403,9 @@ endif::git-format-patch[] Turn off rename detection, even when the configuration file gives the default to do so. +--[no-]rename-empty:: + Whether to use empty blobs as rename source. + ifndef::git-format-patch[] --check:: Warn if changes introduce conflict markers or whitespace errors. @@ -405,7 +436,7 @@ endif::git-format-patch[] --binary:: In addition to `--full-index`, output a binary diff that - can be applied with `git-apply`. + can be applied with `git-apply`. Implies `--patch`. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object @@ -524,6 +555,8 @@ struct), and want to know the history of that block since it first came into being: use the feature iteratively to feed the interesting block in the preimage back into `-S`, and keep going until you get the very first version of the block. ++ +Binary files are searched as well. -G<regex>:: Look for differences whose patch text contains added/removed @@ -534,15 +567,18 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and file: + ---- -+ return !regexec(regexp, two->ptr, 1, ®match, 0); ++ return frotz(nitfol, two->ptr, 1, 0); ... -- hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); +- hit = frotz(nitfol, mf2.ptr, 1, 0); ---- + -While `git log -G"regexec\(regexp"` will show this commit, `git log --S"regexec\(regexp" --pickaxe-regex` will not (because the number of +While `git log -G"frotz\(nitfol"` will show this commit, `git log +-S"frotz\(nitfol" --pickaxe-regex` will not (because the number of occurrences of that string did not change). + +Unless `--text` is supplied patches of binary files without a textconv +filter will be ignored. ++ See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more information. diff --git a/Documentation/doc-diff b/Documentation/doc-diff index f483fe427c..1694300e50 100755 --- a/Documentation/doc-diff +++ b/Documentation/doc-diff @@ -1,23 +1,62 @@ #!/bin/sh +# +# Build two documentation trees and diff the resulting formatted output. +# Compared to a source diff, this can reveal mistakes in the formatting. +# For example: +# +# ./doc-diff origin/master HEAD +# +# would show the differences introduced by a branch based on master. OPTIONS_SPEC="\ doc-diff [options] <from> <to> [-- <diff-options>] +doc-diff (-c|--clean) -- -j=n parallel argument to pass to make -f force rebuild; do not rely on cached results +j=n parallel argument to pass to make +f force rebuild; do not rely on cached results +c,clean cleanup temporary working files +from-asciidoc use asciidoc with the 'from'-commit +from-asciidoctor use asciidoctor with the 'from'-commit +asciidoc use asciidoc with both commits +to-asciidoc use asciidoc with the 'to'-commit +to-asciidoctor use asciidoctor with the 'to'-commit +asciidoctor use asciidoctor with both commits +cut-footer cut away footer " SUBDIRECTORY_OK=1 . "$(git --exec-path)/git-sh-setup" parallel= force= +clean= +from_program= +to_program= +cut_footer= while test $# -gt 0 do case "$1" in -j) parallel=$2; shift ;; + -c|--clean) + clean=t ;; -f) force=t ;; + --from-asciidoctor) + from_program=-asciidoctor ;; + --to-asciidoctor) + to_program=-asciidoctor ;; + --asciidoctor) + from_program=-asciidoctor + to_program=-asciidoctor ;; + --from-asciidoc) + from_program=-asciidoc ;; + --to-asciidoc) + to_program=-asciidoc ;; + --asciidoc) + from_program=-asciidoc + to_program=-asciidoc ;; + --cut-footer) + cut_footer=-cut-footer ;; --) shift; break ;; *) @@ -26,6 +65,16 @@ do shift done +tmp="$(git rev-parse --show-toplevel)/Documentation/tmp-doc-diff" || exit 1 + +if test -n "$clean" +then + test $# -eq 0 || usage + git worktree remove --force "$tmp/worktree" 2>/dev/null + rm -rf "$tmp" + exit 0 +fi + if test -z "$parallel" then parallel=$(getconf _NPROCESSORS_ONLN 2>/dev/null) @@ -42,9 +91,6 @@ to=$1; shift from_oid=$(git rev-parse --verify "$from") || exit 1 to_oid=$(git rev-parse --verify "$to") || exit 1 -cd_to_toplevel -tmp=Documentation/tmp-doc-diff - if test -n "$force" then rm -rf "$tmp" @@ -54,27 +100,43 @@ fi # results that don't differ between the two trees. if ! test -d "$tmp/worktree" then - git worktree add --detach "$tmp/worktree" "$from" && + git worktree add -f --detach "$tmp/worktree" "$from" && dots=$(echo "$tmp/worktree" | sed 's#[^/]*#..#g') && ln -s "$dots/config.mak" "$tmp/worktree/config.mak" fi +construct_makemanflags () { + if test "$1" = "-asciidoc" + then + echo USE_ASCIIDOCTOR= + elif test "$1" = "-asciidoctor" + then + echo USE_ASCIIDOCTOR=YesPlease + fi +} + +from_makemanflags=$(construct_makemanflags "$from_program") && +to_makemanflags=$(construct_makemanflags "$to_program") && + +from_dir=$from_oid$from_program$cut_footer && +to_dir=$to_oid$to_program$cut_footer && + # generate_render_makefile <srcdir> <dstdir> generate_render_makefile () { find "$1" -type f | while read src do dst=$2/${src#$1/} - printf 'all:: %s\n' "$dst" + printf 'all: %s\n' "$dst" printf '%s: %s\n' "$dst" "$src" printf '\t@echo >&2 " RENDER $(notdir $@)" && \\\n' printf '\tmkdir -p $(dir $@) && \\\n' - printf '\tMANWIDTH=80 man -l $< >$@+ && \\\n' + printf '\tMANWIDTH=80 man $< >$@+ && \\\n' printf '\tmv $@+ $@\n' done } -# render_tree <dirname> <committish> +# render_tree <committish_oid> <directory_name> <makemanflags> render_tree () { # Skip install-man entirely if we already have an installed directory. # We can't rely on make here, since "install-man" unconditionally @@ -82,28 +144,43 @@ render_tree () { # we then can't rely on during the render step). We use "mv" to make # sure we don't get confused by a previous run that failed partway # through. - if ! test -d "$tmp/installed/$1" + oid=$1 && + dname=$2 && + makemanflags=$3 && + if ! test -d "$tmp/installed/$dname" then - git -C "$tmp/worktree" checkout "$2" && + git -C "$tmp/worktree" checkout --detach "$oid" && make -j$parallel -C "$tmp/worktree" \ + $makemanflags \ GIT_VERSION=omitted \ SOURCE_DATE_EPOCH=0 \ - DESTDIR="$PWD/$tmp/installed/$1+" \ + DESTDIR="$tmp/installed/$dname+" \ install-man && - mv "$tmp/installed/$1+" "$tmp/installed/$1" + mv "$tmp/installed/$dname+" "$tmp/installed/$dname" fi && # As with "installed" above, we skip the render if it's already been # done. So using make here is primarily just about running in # parallel. - if ! test -d "$tmp/rendered/$1" + if ! test -d "$tmp/rendered/$dname" then - generate_render_makefile "$tmp/installed/$1" "$tmp/rendered/$1+" | + generate_render_makefile "$tmp/installed/$dname" \ + "$tmp/rendered/$dname+" | make -j$parallel -f - && - mv "$tmp/rendered/$1+" "$tmp/rendered/$1" + mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname" + + if test "$cut_footer" = "-cut-footer" + then + for f in $(find "$tmp/rendered/$dname" -type f) + do + head -n -2 "$f" | sed -e '${/^$/d}' >"$f+" && + mv "$f+" "$f" || + return 1 + done + fi fi } -render_tree $from_oid "$from" && -render_tree $to_oid "$to" && -git -C $tmp/rendered diff --no-index "$@" $from_oid $to_oid +render_tree $from_oid $from_dir $from_makemanflags && +render_tree $to_oid $to_dir $to_makemanflags && +git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 8bc36af4b1..6e2a160a47 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -61,18 +61,21 @@ this option multiple times, one for each matching ref name. See also the `fetch.negotiationAlgorithm` configuration variable documented in linkgit:git-config[1]. -ifndef::git-pull[] --dry-run:: Show what would be done, without making any changes. -endif::git-pull[] -f:: --force:: - When 'git fetch' is used with `<rbranch>:<lbranch>` - refspec, it refuses to update the local branch - `<lbranch>` unless the remote branch `<rbranch>` it - fetches is a descendant of `<lbranch>`. This option - overrides that check. + 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] + documentation. +endif::git-pull[] +ifndef::git-pull[] + in the `<refspec>` part below. +endif::git-pull[] + This option overrides that check. -k:: --keep:: @@ -83,6 +86,15 @@ ifndef::git-pull[] Allow several <repository> and <group> arguments to be specified. No <refspec>s may be specified. +--[no-]auto-gc:: + Run `git gc --auto` at the end to perform garbage collection + if needed. This is enabled by default. + +--[no-]write-commit-graph:: + Write a commit-graph after fetching. This overrides the config + setting `fetch.writeCommitGraph`. +endif::git-pull[] + -p:: --prune:: Before fetching, remove any remote-tracking references that no @@ -94,6 +106,7 @@ ifndef::git-pull[] was cloned with the --mirror option), then they are also subject to pruning. Supplying `--prune-tags` is a shorthand for providing the tag refspec. +ifndef::git-pull[] + See the PRUNING section below for more details. @@ -120,13 +133,15 @@ endif::git-pull[] behavior for a remote may be specified with the remote.<name>.tagOpt setting. See linkgit:git-config[1]. -ifndef::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 refs to remote-tracking branches, instead of the values of `remote.*.fetch` configuration variables for the remote - repository. See section on "Configured Remote-tracking + repository. Providing an empty `<refspec>` to the + `--refmap` option causes Git to ignore the configured + refspecs and rely entirely on the refspecs supplied as + command-line arguments. See section on "Configured Remote-tracking Branches" for details. -t:: @@ -138,6 +153,7 @@ ifndef::git-pull[] is used (though tags may be pruned anyway if they are also the destination of an explicit refspec; see `--prune`). +ifndef::git-pull[] --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 @@ -147,19 +163,36 @@ ifndef::git-pull[] 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. + clone. By default, 'on-demand' is used, unless + `fetch.recurseSubmodules` is set (see linkgit:git-config[1]). +endif::git-pull[] -j:: --jobs=<n>:: - Number of parallel children to be used for fetching submodules. - Each will fetch from different submodules, such that fetching many - submodules will be faster. By default submodules will be fetched - one at a time. + Number of parallel children to be used for all forms of fetching. ++ +If the `--multiple` option was specified, the different remotes will be fetched +in parallel. If multiple submodules are fetched, they will be fetched in +parallel. To control them independently, use the config settings +`fetch.parallel` and `submodule.fetchJobs` (see linkgit:git-config[1]). ++ +Typically, parallel recursive and multi-remote fetches will be faster. By +default fetches are performed sequentially, not in parallel. +ifndef::git-pull[] --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as using the `--recurse-submodules=no` option). +endif::git-pull[] + +--set-upstream:: + If the remote is fetched successfully, pull and add upstream + (tracking) reference, used by argument-less + linkgit:git-pull[1] and other commands. For more information, + see `branch.<name>.merge` and `branch.<name>.remote` in + linkgit:git-config[1]. +ifndef::git-pull[] --submodule-prefix=<path>:: Prepend <path> to paths printed in informative messages such as "Fetching submodule foo". This option is used @@ -172,7 +205,6 @@ ifndef::git-pull[] recursion (such as settings in linkgit:gitmodules[5] and linkgit:git-config[1]) override this option, as does specifying --[no-]recurse-submodules directly. -endif::git-pull[] -u:: --update-head-ok:: @@ -182,6 +214,7 @@ endif::git-pull[] to communicate with 'git fetch', and unless you are implementing your own Porcelain you are not supposed to use it. +endif::git-pull[] --upload-pack <upload-pack>:: When given, and the repository to fetch from is handled @@ -211,10 +244,24 @@ endif::git-pull[] --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. + character. The server's handling of server options, including + unknown ones, is server-specific. When multiple `--server-option=<option>` are given, they are all sent to the other side in the order listed on the command line. +--show-forced-updates:: + By default, git checks if a branch is force-updated during + fetch. This can be disabled through fetch.showForcedUpdates, but + the --show-forced-updates option guarantees this check occurs. + See linkgit:git-config[1]. + +--no-show-forced-updates:: + By default, git checks if a branch is force-updated during + fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates + to false to skip this check for performance reasons. If used during + 'git-pull' the --ff-only option will still check for forced updates + before attempting a fast-forward update. See linkgit:git-config[1]. + -4:: --ipv4:: Use IPv4 addresses only, ignoring IPv6 addresses. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 45652fe4a6..be5e3ac54b 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -11,7 +11,8 @@ SYNOPSIS 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] - [--chmod=(+|-)x] [--] [<pathspec>...] + [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...] DESCRIPTION ----------- @@ -58,9 +59,9 @@ OPTIONS specifying `dir` will record not just a file `dir/file1` modified in the working tree, a file `dir/file2` added to the working tree, but also a file `dir/file3` removed from - the working tree. Note that older versions of Git used + the working tree). Note that older versions of Git used to ignore removed files; use `--no-all` option if you want - to add modified or new files but ignore removed ones. + to add modified or new files but ignore removed ones. + For more details about the <pathspec> syntax, see the 'pathspec' entry in linkgit:gitglossary[7]. @@ -124,7 +125,7 @@ subdirectories). --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 - entry. This adds, modifies, and removes index entries to + entry. This adds, modifies, and removes index entries to match the working tree. + If no <pathspec> is given when `-A` option is used, all @@ -187,26 +188,30 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. bit is only changed in the index, the files on disk are left unchanged. +--pathspec-from-file=<file>:: + 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 + global `--literal-pathspecs`. + +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). + \--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). -CONFIGURATION -------------- - -The optional configuration variable `core.excludesFile` indicates a path to a -file containing patterns of file names to exclude from git-add, similar to -$GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitignore[5]. - - EXAMPLES -------- * Adds content from all `*.txt` files under `Documentation` directory -and its subdirectories: + and its subdirectories: + ------------ $ git add Documentation/\*.txt diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 6f6c34b0f4..38c0852139 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -16,7 +16,7 @@ SYNOPSIS [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [(<mbox> | <Maildir>)...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch) +'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)]) DESCRIPTION ----------- @@ -99,6 +99,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. + --ignore-space-change:: --ignore-whitespace:: --whitespace=<option>:: @@ -143,9 +148,12 @@ default. You can use `--no-utf8` to override this. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. --continue:: -r:: @@ -171,9 +179,11 @@ default. You can use `--no-utf8` to override this. Abort the patching operation but keep HEAD and the index untouched. ---show-current-patch:: - Show the patch being applied when "git am" is stopped because - of conflicts. +--show-current-patch[=(diff|raw)]:: + Show the message at which `git am` has stopped due to + conflicts. If `raw` is specified, show the raw contents of + the e-mail message; if `diff`, show the diff portion only. + Defaults to `raw`. DISCUSSION ---------- @@ -185,8 +195,8 @@ the commit, after stripping common prefix "[PATCH <anything>]". The "Subject: " line is supposed to concisely describe what the commit is about in one line of text. -"From: " and "Subject: " lines starting the body override the respective -commit author name and title values taken from the headers. +"From: ", "Date: ", and "Subject: " lines starting the body override the +respective commit author name and title values taken from the headers. The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index ea70653369..a595a0ffee 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -3,7 +3,7 @@ git-archimport(1) NAME ---- -git-archimport - Import an Arch repository into Git +git-archimport - Import a GNU Arch repository into Git SYNOPSIS @@ -14,7 +14,8 @@ SYNOPSIS DESCRIPTION ----------- -Imports a project from one or more Arch repositories. It will follow branches +Imports a project from one or more GNU Arch repositories. +It will follow branches 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 diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 0f9ef2f25e..3ba49e85b7 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -158,7 +158,7 @@ Test suites are very nice. But when they are used alone, they are supposed to be used so that all the tests are checked after each commit. This means that they are not very efficient, because many tests are run for no interesting result, and they suffer from -combinational explosion. +combinatorial explosion. In fact the problem is that big software often has many different configuration options and that each test case should pass for each @@ -633,11 +633,11 @@ and so at step 3) we compute f(X). Let's take the following graph as an example: ------------- - G-H-I-J - / \ + G-H-I-J + / \ A-B-C-D-E-F O - \ / - K-L-M-N + \ / + K-L-M-N ------------- If we compute the following non optimal function on it: @@ -649,25 +649,25 @@ g(X) = min(number_of_ancestors(X), number_of_descendants(X)) we get: ------------- - 4 3 2 1 - G-H-I-J + 4 3 2 1 + G-H-I-J 1 2 3 4 5 6/ \0 A-B-C-D-E-F O - \ / - K-L-M-N - 4 3 2 1 + \ / + K-L-M-N + 4 3 2 1 ------------- but with the algorithm used by git bisect we get: ------------- - 7 7 6 5 - G-H-I-J + 7 7 6 5 + G-H-I-J 1 2 3 4 5 6/ \0 A-B-C-D-E-F O - \ / - K-L-M-N - 7 7 6 5 + \ / + K-L-M-N + 7 7 6 5 ------------- So we chose G, H, K or L as the best bisection point, which is better @@ -773,7 +773,7 @@ forked of the main branch at a commit named "D" like this: ------------- A-B-C-D-E-F-G <--main \ - H-I-J <--dev + H-I-J <--dev ------------- The commit "D" is called a "merge base" for branch "main" and "dev" @@ -1350,9 +1350,9 @@ 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.] - [[[3]]] https://en.wikipedia.org/wiki/Software_maintenance['Software maintenance'. Wikipedia.] -- [[[4]]] https://public-inbox.org/git/7vps5xsbwp.fsf_-_@assigned-by-dhcp.cox.net/[Junio C Hamano. 'Automated bisect success story'.] +- [[[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.] - [[[6]]] https://lwn.net/Articles/277872/[Jonathan Corbet. 'Bisection divides users and developers'. LWN.net.] -- [[[7]]] http://marc.info/?l=linux-kernel&m=119702753411680&w=2[Ingo Molnar. 'Re: BUG 2.6.23-rc3 can't see sd partitions on Alpha'. Linux-kernel mailing list.] +- [[[7]]] https://lore.kernel.org/lkml/20071207113734.GA14598@elte.hu/[Ingo Molnar. 'Re: BUG 2.6.23-rc3 can't see sd partitions on Alpha'. Linux-kernel mailing list.] - [[[8]]] https://www.kernel.org/pub/software/scm/git/docs/git-bisect.html[Junio C Hamano and the git-list. 'git-bisect(1) Manual Page'. Linux Kernel Archives.] - [[[9]]] https://github.com/Ealdwulf/bbchop[Ealdwulf. 'bbchop'. GitHub.] diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 4b45d837a7..7586c5a843 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -413,7 +413,7 @@ $ cat ~/test.sh # tweak the working tree by merging the hot-fix branch # and then attempt a build -if git merge --no-commit hot-fix && +if git merge --no-commit --no-ff hot-fix && make then # run project specific test and report its status diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 16323eb80e..7e81541996 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -10,6 +10,7 @@ SYNOPSIS [verse] '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> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 1072ca0eb6..135206ff4a 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,13 +8,15 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git branch' [--color[=<when>] | --no-color] [-r | -a] - [--list] [-v [--abbrev=<length> | --no-abbrev]] +'git branch' [--color[=<when>] | --no-color] [--show-current] + [-v [--abbrev=<length> | --no-abbrev]] [--column[=<options>] | --no-column] [--sort=<key>] [(--merged | --no-merged) [<commit>]] [--contains [<commit]] [--no-contains [<commit>]] - [--points-at <object>] [--format=<format>] [<pattern>...] -'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] + [--points-at <object>] [--format=<format>] + [(-r | --remotes) | (-a | --all)] + [--list] [<pattern>...] +'git branch' [--track | --no-track] [-f] <branchname> [<start-point>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> @@ -26,13 +28,19 @@ DESCRIPTION ----------- If `--list` is given, or if there are no non-option arguments, existing -branches are listed; the current branch will be highlighted with an -asterisk. Option `-r` causes the remote-tracking branches to be listed, -and option `-a` shows both local and remote branches. If a `<pattern>` +branches are listed; the current branch will be highlighted in green and +marked with an asterisk. Any branches checked out in linked worktrees will +be highlighted in cyan and marked with a plus sign. Option `-r` causes the +remote-tracking branches to be listed, +and option `-a` shows both local and remote branches. + +If a `<pattern>` is given, it is used as a shell wildcard to restrict the output to matching branches. If multiple patterns are given, a branch is shown if -it matches any of the patterns. Note that when providing a -`<pattern>`, you must use `--list`; otherwise the command is interpreted +it matches any of the patterns. + +Note that when providing a +`<pattern>`, you must use `--list`; otherwise the command may be interpreted as branch creation. With `--contains`, shows only the branches that contain the named commit @@ -45,10 +53,14 @@ argument is missing it defaults to `HEAD` (i.e. the tip of the current branch). The command's second form creates a new branch head named <branchname> -which points to the current `HEAD`, or <start-point> if given. +which points to the current `HEAD`, or <start-point> if given. As a +special case, for <start-point>, 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`. Note that this will create the new branch, but it will not switch the -working tree to it; use "git checkout <newbranch>" to switch to the +working tree to it; use "git switch <newbranch>" to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the @@ -100,8 +112,6 @@ OPTIONS The negated form `--no-create-reflog` only overrides an earlier `--create-reflog`, but currently does not negate the setting of `core.logAllRefUpdates`. -+ -The `-l` option is a deprecated synonym for `--create-reflog`. -f:: --force:: @@ -151,19 +161,22 @@ This option is only applicable in non-verbose mode. -r:: --remotes:: List or delete (if used with -d) the remote-tracking branches. + Combine with `--list` to match the optional pattern(s). -a:: --all:: List both remote-tracking branches and local branches. + Combine with `--list` to match optional pattern(s). +-l:: --list:: List branches. With optional `<pattern>...`, e.g. `git branch --list 'maint-*'`, list only the branches that match the pattern(s). -+ -This should not be confused with `git branch -l <branchname>`, -which creates a branch named `<branchname>` with a reflog. -See `--create-reflog` above for details. + +--show-current:: + Print the name of the current branch. In detached HEAD state, + nothing is printed. -v:: -vv:: @@ -171,8 +184,10 @@ See `--create-reflog` above for details. When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print - the name of the upstream branch, as well (see also `git remote - show <remote>`). + the path of the linked worktree (if any) and the name of the upstream + branch, as well (see also `git remote show <remote>`). Note that the + current worktree's HEAD will not have its path printed (it will always + be your current directory). -q:: --quiet:: @@ -199,7 +214,7 @@ See `--create-reflog` above for details. + 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 checkout` and `git branch` to always behave as if `--no-track` +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. @@ -268,10 +283,11 @@ start-point is either a local or remote-tracking branch. order of the value. You may use the --sort=<key> option 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 sorting based on the + for-each-ref`. Sort order defaults to the value configured for the + `branch.sort` variable if 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. + finally remote-tracking branches. See linkgit:git-config[1]. --points-at <object>:: @@ -297,11 +313,11 @@ Start development from a known tag:: $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 $ cd my2.6 $ git branch my2.6.14 v2.6.14 <1> -$ git checkout my2.6.14 +$ git switch my2.6.14 ------------ + <1> This step and the next one could be combined into a single step with -"checkout -b my2.6.14 v2.6.14". + "checkout -b my2.6.14 v2.6.14". Delete an unneeded branch:: + @@ -313,18 +329,30 @@ $ git branch -D test <2> ------------ + <1> Delete the remote-tracking branches "todo", "html" and "man". The next -'fetch' or 'pull' will create them again unless you configure them not to. -See linkgit:git-fetch[1]. + 'fetch' or 'pull' will create them again unless you configure them not to. + See linkgit:git-fetch[1]. <2> Delete the "test" branch even if the "master" branch (or whichever branch -is currently checked out) does not have all commits from the test branch. + is currently checked out) does not have all commits from the test branch. + +Listing branches from a specific remote:: ++ +------------ +$ git branch -r -l '<remote>/<pattern>' <1> +$ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2> +------------ ++ +<1> Using `-a` would conflate <remote> with any local branches you happen to + have been prefixed with the same <remote> pattern. +<2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1] +Patterns will normally need quoting. NOTES ----- -If you are creating a branch that you want to checkout immediately, it is -easier to use the git checkout command with its `-b` option to create -a branch and check it out with a single command. +If you are creating a branch that you want to switch to immediately, +it is easier to use the "git switch" command with its `-c` option to +do the same thing with a single command. The options `--contains`, `--no-contains`, `--merged` and `--no-merged` serve four related but different purposes: diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt new file mode 100644 index 0000000000..9edad66a63 --- /dev/null +++ b/Documentation/git-bugreport.txt @@ -0,0 +1,53 @@ +git-bugreport(1) +================ + +NAME +---- +git-bugreport - Collect information for user to file a bug report + +SYNOPSIS +-------- +[verse] +'git bugreport' [(-o | --output-directory) <path>] [(-s | --suffix) <format>] + +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. + +The following information is requested from the user: + + - Reproduction steps + - Expected behavior + - Actual behavior + +The following information is captured automatically: + + - 'git version --build-options' + - uname sysname, release, version, and machine strings + - Compiler-specific info string + - A list of enabled hooks + +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 +the kind of information listed above when manually asking for help. + +OPTIONS +------- +-o <path>:: +--output-directory <path>:: + Place the resulting bug report file in `<path>` instead of the root of + the Git repository. + +-s <format>:: +--suffix <format>:: + Specify an alternate suffix for the bugreport name, to create a file + named 'git-bugreport-<formatted suffix>'. This should take the form of a + strftime(3) format string; the current local time will be used. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 7d6c9dcd17..d34b0964be 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,8 +9,8 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'git bundle' create <file> <git-rev-list-args> -'git bundle' verify <file> +'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] <file> <git-rev-list-args> +'git bundle' verify [-q | --quiet] <file> 'git bundle' list-heads <file> [<refname>...] 'git bundle' unbundle <file> [<refname>...] @@ -20,11 +20,14 @@ 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. This command provides support for -'git fetch' and 'git pull' to operate by packaging objects and references -in an archive at the originating machine, then importing those into -another repository using 'git fetch' and 'git pull' -after moving the archive by some means (e.g., by sneakernet). As no +ssh, http) cannot be used. + +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). + +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 @@ -33,9 +36,11 @@ destination repository. OPTIONS ------- -create <file>:: +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. + '<git-rev-list-args>' arguments to define the bundle contents. + 'options' contains the options specific to the 'git bundle create' + subcommand. verify <file>:: Used to check that a bundle file is valid and will apply @@ -75,6 +80,33 @@ unbundle <file>:: necessarily everything in the pack (in this case, 'git bundle' acts like 'git fetch-pack'). +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + 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. + +-q:: +--quiet:: + This flag makes the command not to report its progress + on the standard error stream. + SPECIFYING REFERENCES --------------------- @@ -92,6 +124,14 @@ 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>`. + EXAMPLES -------- diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 74013335a1..8eca671b82 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -23,8 +23,8 @@ 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 white -space, so that the appropriate drivers can be determined. +list the object names followed by the path name, separated by a single +whitespace, so that the appropriate drivers can be determined. OPTIONS ------- @@ -79,7 +79,7 @@ OPTIONS 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 white space. See the + also need to specify the path, separated by whitespace. See the section `BATCH OUTPUT` below for details. --batch-check:: @@ -87,7 +87,7 @@ OPTIONS 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 white space. See the + need to specify the path, separated by whitespace. See the section `BATCH OUTPUT` below for details. --batch-all-objects:: @@ -252,6 +252,12 @@ the repository, then `cat-file` will ignore any custom format and print: <object> SP missing LF ------------ +If a name is specified that might refer to more than one object (an ambiguous short sha), then `cat-file` will ignore any custom format and print: + +------------ +<object> SP ambiguous LF +------------ + If --follow-symlinks is used, and a symlink in the repository points outside the repository, then `cat-file` will ignore any custom format and print: diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 3c0578217b..84f41a8e82 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -32,7 +32,7 @@ OPTIONS instead of from the command-line. -z:: - The output format is modified to be machine-parseable. + 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. diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 8b42cb3fb2..0c3924a63d 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -30,16 +30,22 @@ OPTIONS valid with a single pathname. -v, --verbose:: - Also output details about the matching pattern (if any) - for each given pathname. For precedence rules within and - between exclude sources, see linkgit:gitignore[5]. + 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 '!' + then it is a negated pattern and matching it means the path is + NOT excluded.) ++ +For precedence rules within and between exclude sources, see +linkgit:gitignore[5]. --stdin:: Read pathnames from the standard input, one per line, instead of from the command-line. -z:: - The output format is modified to be machine-parseable (see + The output format is modified to be machine-parsable (see below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index d9de992585..ee6a4144fb 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -88,7 +88,8 @@ but it is explicitly forbidden at the beginning of a branch name). When run with `--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 checkout" operation. This option should be +was checked out using "git switch" or "git checkout" operation. +This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name. As an exception note that, the ``previous checkout operation'' might result diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 9db02928c4..5b697eee1b 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -12,42 +12,33 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] --detach [<branch>] 'git checkout' [-q] [-f] [-m] [--detach] <commit> 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... -'git checkout' [<tree-ish>] [--] <pathspec>... -'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...] +'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' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] DESCRIPTION ----------- Updates files in the working tree to match the version in the index -or the specified tree. If no paths are given, 'git checkout' will +or the specified tree. If no pathspec was given, 'git checkout' will also update `HEAD` to set the specified branch as the current branch. -'git checkout' <branch>:: - To prepare for working on <branch>, switch to it by updating +'git checkout' [<branch>]:: + To prepare for working on `<branch>`, switch to it by updating the index and the files in the working tree, and by pointing - HEAD at the branch. Local modifications to the files in the + `HEAD` at the branch. Local modifications to the files in the working tree are kept, so that they can be committed to the - <branch>. + `<branch>`. + -If <branch> is not found but there does exist a tracking branch in -exactly one remote (call it <remote>) with a matching name, treat as -equivalent to +If `<branch>` is not found but there does exist a tracking branch in +exactly one remote (call it `<remote>`) with a matching name and +`--no-guess` is not specified, treat as equivalent to + ------------ $ git checkout -b <branch> --track <remote>/<branch> ------------ + -If the branch exists in multiple remotes and one of them is named by -the `checkout.defaultRemote` configuration variable, we'll use that -one for the purposes of disambiguation, even if the `<branch>` isn't -unique across all remotes. Set it to -e.g. `checkout.defaultRemote=origin` to always checkout remote -branches from there if `<branch>` is ambiguous but exists on the -'origin' remote. See also `checkout.defaultRemote` in -linkgit:git-config[1]. -+ -You could omit <branch>, in which case the command degenerates to +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. @@ -61,7 +52,7 @@ 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 + ------------ @@ -75,26 +66,27 @@ successful. 'git checkout' --detach [<branch>]:: 'git checkout' [--detach] <commit>:: - Prepare to work on top of <commit>, by detaching HEAD at it + Prepare to work on top of `<commit>`, by detaching `HEAD` at it (see "DETACHED HEAD" section), and updating the index and the files in the working tree. Local modifications to the files in the working tree are kept, so that the resulting working tree will be the state recorded in the commit plus the local modifications. + -When the <commit> argument is a branch name, the `--detach` option can -be used to detach HEAD at the tip of the branch (`git checkout -<branch>` would check out that branch without detaching HEAD). +When the `<commit>` argument is a branch name, the `--detach` option can +be used to detach `HEAD` at the tip of the branch (`git checkout +<branch>` would check out that branch without detaching `HEAD`). + -Omitting <branch> detaches HEAD at the tip of the current branch. +Omitting `<branch>` detaches `HEAD` at the tip of the current branch. -'git checkout' [<tree-ish>] [--] <pathspec>...:: +'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]:: - Overwrite paths in the working tree by replacing with the - contents in the index or in the <tree-ish> (most often a - commit). When a <tree-ish> is given, the paths that - match the <pathspec> are updated both in the index and in - the working tree. + Overwrite the contents of the files that match the pathspec. + When the `<tree-ish>` (most often a commit) is not given, + overwrite working tree with the contents in the index. + When the `<tree-ish>` is given, overwrite both the index and + the working tree with the contents at the `<tree-ish>`. + The index may contain unmerged entries because of a previous failed merge. By default, if you try to check out such an entry from the index, the @@ -105,12 +97,10 @@ using `--ours` or `--theirs`. With `-m`, changes made to the working tree file can be discarded to re-create the original conflicted merge result. 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]:: - This is similar to the "check out paths to the working tree - from either the index or from a tree-ish" mode described - above, but lets you use the interactive interface to show - the "diff" output and choose which hunks to use in the - result. See below for the description of `--patch` option. - + This is similar to the previous mode, but lets you use the + interactive interface to show the "diff" output and choose which + hunks to use in the result. See below for the description of + `--patch` option. OPTIONS ------- @@ -118,7 +108,8 @@ OPTIONS --quiet:: Quiet, suppress feedback messages. ---[no-]progress:: +--progress:: +--no-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 enables progress reporting even if not @@ -127,7 +118,7 @@ OPTIONS -f:: --force:: When switching branches, proceed even if the index or the - working tree differs from HEAD. This is used to throw away + working tree differs from `HEAD`. This is used to throw away local changes. + When checking out paths from the index, do not fail upon unmerged @@ -154,12 +145,12 @@ on your side branch as `theirs` (i.e. "one contributor's work on top of it"). -b <new_branch>:: - Create a new branch named <new_branch> and start it at - <start_point>; see linkgit:git-branch[1] for details. + Create a new branch named `<new_branch>` and start it at + `<start_point>`; 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 + 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. @@ -172,15 +163,36 @@ If no `-b` option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of the refspec configured for the corresponding remote, and then stripping the initial part up to the "*". -This would tell us to use "hack" as the local branch when branching -off of "origin/hack" (or "remotes/origin/hack", or even -"refs/remotes/origin/hack"). If the given name has no slash, or the above +This would tell us to use `hack` as the local branch when branching +off of `origin/hack` (or `remotes/origin/hack`, or even +`refs/remotes/origin/hack`). If the given name has no slash, or the above guessing results in an empty name, the guessing is aborted. You can explicitly give a name with `-b` in such a case. --no-track:: Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is true. + `branch.autoSetupMerge` configuration variable is true. + +--guess:: +--no-guess:: + If `<branch>` is not found but there does exist a tracking + branch in exactly one remote (call it `<remote>`) with a + matching name, treat as equivalent to ++ +------------ +$ git checkout -b <branch> --track <remote>/<branch> +------------ ++ +If the branch exists in multiple remotes and one of them is named by +the `checkout.defaultRemote` configuration variable, we'll use that +one for the purposes of disambiguation, even if the `<branch>` isn't +unique across all remotes. Set it to +e.g. `checkout.defaultRemote=origin` to always checkout remote +branches from there if `<branch>` is ambiguous but exists on the +'origin' remote. See also `checkout.defaultRemote` in +linkgit:git-config[1]. ++ +Use `--no-guess` to disable this. -l:: Create the new branch's reflog; see linkgit:git-branch[1] for @@ -189,21 +201,21 @@ explicitly give a name with `-b` in such a case. --detach:: Rather than checking out a branch to work on it, check out a commit for inspection and discardable experiments. - This is the default behavior of "git checkout <commit>" when - <commit> is not a branch name. See the "DETACHED HEAD" section + This is the default behavior of `git checkout <commit>` when + `<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 + Create a new 'orphan' 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 commit -a" to make the root commit. +`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 without exposing its full history. You might want to do this to publish @@ -212,17 +224,17 @@ 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. +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 working tree, by copying them from elsewhere, extracting a tarball, etc. --ignore-skip-worktree-bits:: In sparse checkout mode, `git checkout -- <paths>` would - update only entries matched by <paths> and sparse patterns - in $GIT_DIR/info/sparse-checkout. This option ignores - the sparse patterns and adds back any files in <paths>. + update only entries matched by `<paths>` and sparse patterns + in `$GIT_DIR/info/sparse-checkout`. This option ignores + the sparse patterns and adds back any files in `<paths>`. -m:: --merge:: @@ -242,24 +254,29 @@ 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. ++ +When switching branches with `--merge`, staged changes may be lost. --conflict=<style>:: - The same as --merge option above, but changes the way the + 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.conflictStyle` configuration variable. Possible values are "merge" (default) and "diff3" (in addition to what is shown by "merge" style, shows the original contents). -p:: --patch:: Interactively select hunks in the difference between the - <tree-ish> (or the index, if unspecified) and the working + `<tree-ish>` (or the index, if unspecified) and the working tree. The chosen hunks are then applied in reverse to the - working tree (and if a <tree-ish> was specified, the index). + working tree (and if a `<tree-ish>` was specified, the index). + This means that you can use `git checkout -p` to selectively discard edits from your current working tree. See the ``Interactive Mode'' section of linkgit:git-add[1] to learn how to operate the `--patch` mode. ++ +Note that this option uses the no overlay mode by default (see also +`--overlay`), and currently doesn't support overlay mode. --ignore-other-worktrees:: `git checkout` refuses when the wanted ref is already checked @@ -267,27 +284,55 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. out anyway. In other words, the ref can be held by more than one worktree. ---[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized +--overwrite-ignore:: +--no-overwrite-ignore:: + Silently overwrite ignored files when switching branches. This + is the default behavior. Use `--no-overwrite-ignore` to abort + the operation when the new branch contains ignored files. + +--recurse-submodules:: +--no-recurse-submodules:: + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout - will fail unless `-f` is used. If nothing (or --no-recurse-submodules) - is used, the work trees of submodules will not be updated. - Just like linkgit:git-submodule[1], this will detach the - submodules HEAD. + will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) + is used, submodules working trees will not be updated. + Just like linkgit:git-submodule[1], this will detach `HEAD` of the + submodule. + +--overlay:: +--no-overlay:: + In the default overlay mode, `git checkout` never + removes files from the index or the working tree. When + specifying `--no-overlay`, files that appear in the index and + working tree, but not in `<tree-ish>` are removed, to make them + match `<tree-ish>` exactly. + +--pathspec-from-file=<file>:: + 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 + global `--literal-pathspecs`. + +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that branch is checked out. Otherwise, if it refers to a valid - commit, your HEAD becomes "detached" and you are no longer on + commit, your `HEAD` becomes "detached" and you are no longer on any branch (see below for details). + -You can use the `"@{-N}"` syntax to refer to the N-th last +You can use the `@{-N}` syntax to refer to the N-th last branch/commit checked out using "git checkout" operation. You may -also specify `-` which is synonymous to `"@{-1}`. +also specify `-` which is synonymous to `@{-1}`. + -As a special case, you may use `"A...B"` as a shortcut for the +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`. @@ -296,24 +341,34 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. <start_point>:: The name of a commit at which to start the new branch; see - linkgit:git-branch[1] for details. Defaults to HEAD. + linkgit:git-branch[1] for details. Defaults to `HEAD`. ++ +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`. <tree-ish>:: Tree to checkout from (when paths are given). If not specified, the index will be used. +\--:: + Do not interpret any more arguments as options. +<pathspec>...:: + Limits the paths affected by the operation. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. DETACHED HEAD ------------- -HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each +`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each branch refers to a specific commit. Let's look at a repo with three -commits, one of them tagged, and with branch 'master' checked out: +commits, one of them tagged, and with branch `master` checked out: ------------ - HEAD (refers to branch 'master') - | - v + HEAD (refers to branch 'master') + | + v a---b---c branch 'master' (refers to commit 'c') ^ | @@ -321,17 +376,17 @@ a---b---c branch 'master' (refers to commit 'c') ------------ When a commit is created in this state, the branch is updated to refer to -the new commit. Specifically, 'git commit' creates a new commit 'd', whose -parent is commit 'c', and then updates branch 'master' to refer to new -commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers -to commit 'd': +the new commit. Specifically, 'git commit' creates a new commit `d`, whose +parent is commit `c`, and then updates branch `master` to refer to new +commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers +to commit `d`: ------------ $ edit; git add; git commit - HEAD (refers to branch 'master') - | - v + HEAD (refers to branch 'master') + | + v a---b---c---d branch 'master' (refers to commit 'd') ^ | @@ -341,7 +396,7 @@ a---b---c---d branch 'master' (refers to commit 'd') It is sometimes useful to be able to checkout a commit that is not at the tip of any named branch, or even to create a new commit that is not referenced by a named branch. Let's look at what happens when we -checkout commit 'b' (here we show two ways this may be done): +checkout commit `b` (here we show two ways this may be done): ------------ $ git checkout v2.0 # or @@ -356,9 +411,9 @@ a---b---c---d branch 'master' (refers to commit 'd') tag 'v2.0' (refers to commit 'b') ------------ -Notice that regardless of which checkout command we use, HEAD now refers -directly to commit 'b'. This is known as being in detached HEAD state. -It means simply that HEAD refers to a specific commit, as opposed to +Notice that regardless of which checkout command we use, `HEAD` now refers +directly to commit `b`. This is known as being in detached `HEAD` state. +It means simply that `HEAD` refers to a specific commit, as opposed to referring to a named branch. Let's see what happens when we create a commit: ------------ @@ -375,7 +430,7 @@ a---b---c---d branch 'master' (refers to commit 'd') tag 'v2.0' (refers to commit 'b') ------------ -There is now a new commit 'e', but it is referenced only by HEAD. We can +There is now a new commit `e`, but it is referenced only by `HEAD`. We can of course add yet another commit in this state: ------------ @@ -393,12 +448,12 @@ a---b---c---d branch 'master' (refers to commit 'd') ------------ In fact, we can perform all the normal Git operations. But, let's look -at what happens when we then checkout master: +at what happens when we then checkout `master`: ------------ $ git checkout master - HEAD (refers to branch 'master') + HEAD (refers to branch 'master') e---f | / v a---b---c---d branch 'master' (refers to commit 'd') @@ -408,9 +463,9 @@ a---b---c---d branch 'master' (refers to commit 'd') ------------ It is important to realize that at this point nothing refers to commit -'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted +`f`. Eventually commit `f` (and by extension commit `e`) will be deleted by the routine Git garbage collection process, unless we create a reference -before that happens. If we have not yet moved away from commit 'f', +before that happens. If we have not yet moved away from commit `f`, any of these will create a reference to it: ------------ @@ -419,19 +474,19 @@ $ 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. +<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. +<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. +<3> creates a new tag `foo`, which refers to commit `f`, + leaving `HEAD` detached. -If we have moved away from commit 'f', then we must first recover its object +If we have moved away from commit `f`, then we must first recover its object name (typically by using git reflog), and then we can create a reference to -it. For example, to see the last two commits to which HEAD referred, we +it. For example, to see the last two commits to which `HEAD` referred, we can use either of these commands: ------------ @@ -442,12 +497,12 @@ $ git log -g -2 HEAD ARGUMENT DISAMBIGUATION ----------------------- -When there is only one argument given and it is not `--` (e.g. "git -checkout abc"), and when the argument is both a valid `<tree-ish>` -(e.g. a branch "abc" exists) and a valid `<pathspec>` (e.g. a file +When there is only one argument given and it is not `--` (e.g. `git +checkout abc`), and when the argument is both a valid `<tree-ish>` +(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file or a directory whose name is "abc" exists), Git would usually ask you to disambiguate. Because checking out a branch is so common an -operation, however, "git checkout abc" takes "abc" as a `<tree-ish>` +operation, however, `git checkout abc` takes "abc" as a `<tree-ish>` in such a situation. Use `git checkout -- <pathspec>` if you want to checkout these paths out of the index. @@ -455,8 +510,8 @@ 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. + the `Makefile` to two revisions back, deletes `hello.c` by + mistake, and gets it back from the index. + ------------ $ git checkout master <1> @@ -467,7 +522,7 @@ $ git checkout hello.c <3> + <1> switch branch <2> take a file out of another commit -<3> restore hello.c from the index +<3> restore `hello.c` from the index + If you want to check out _all_ C source files out of the index, you can say @@ -490,13 +545,13 @@ $ git checkout -- hello.c ------------ . After working in the wrong branch, switching to the correct -branch would be done using: + branch would be done using: + ------------ $ git checkout mytopic ------------ + -However, your "wrong" branch and correct "mytopic" branch may +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: + @@ -518,7 +573,7 @@ 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: + the `-m` option, you would see something like this: + ------------ $ git checkout -m mytopic @@ -537,6 +592,11 @@ $ edit frotz $ git add frotz ------------ +SEE ALSO +-------- +linkgit:git-switch[1], +linkgit:git-restore[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index d35d771fc8..75feeef08a 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -10,9 +10,7 @@ SYNOPSIS [verse] 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] [-S[<keyid>]] <commit>... -'git cherry-pick' --continue -'git cherry-pick' --quit -'git cherry-pick' --abort +'git cherry-pick' (--continue | --skip | --abort | --quit) DESCRIPTION ----------- @@ -57,6 +55,13 @@ OPTIONS With this option, 'git cherry-pick' will let you edit the commit message prior to committing. +--cleanup=<mode>:: + This option determines how the commit message will be cleaned up before + being passed on to the commit machinery. See linkgit:git-commit[1] for more + details. In particular, if the '<mode>' is given a value of `scissors`, + scissors will be appended to `MERGE_MSG` before being passed on in the case + of a conflict. + -x:: When recording the commit, append a line that says "(cherry picked from commit ...)" to the original commit @@ -104,9 +109,12 @@ effect to your index in a row. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. --ff:: If the current HEAD is the same as the parent of the @@ -148,6 +156,11 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[] @@ -213,16 +226,16 @@ $ git reset --merge ORIG_HEAD <3> $ git cherry-pick -Xpatience topic^ <4> ------------ <1> apply the change that would be shown by `git show topic^`. -In this example, the patch does not apply cleanly, so -information about the conflict is written to the index and -working tree and no new commit results. + In this example, the patch does not apply cleanly, so + information about the conflict is written to the index and + working tree and no new commit results. <2> summarize changes to be reconciled <3> cancel the cherry-pick. In other words, return to the -pre-cherry-pick state, preserving any local modifications you had in -the working tree. + pre-cherry-pick state, preserving any local modifications + you had in the working tree. <4> try to apply the change introduced by `topic^` again, -spending extra time to avoid mistakes based on incorrectly matching -context lines. + spending extra time to avoid mistakes based on incorrectly + matching context lines. SEE ALSO -------- diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 03056dad0d..a7f309dff5 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -26,18 +26,20 @@ are affected. OPTIONS ------- -d:: - Remove untracked directories in addition to untracked files. - If an untracked directory is managed by a different Git - repository, it is not removed by default. Use -f option twice - if you really want to remove such a directory. + Normally, when no <path> 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 + files matching the specified paths (with exceptions for nested + git directories mentioned under `--force`) will be removed. -f:: --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, -n or -i. Git will refuse to delete directories - with .git sub directory or file unless a second -f - is given. + unless given -f or -i. Git will refuse to modify untracked + nested git repositories (directories with a .git subdirectory) + unless a second -f is given. -i:: --interactive:: @@ -55,16 +57,15 @@ OPTIONS -e <pattern>:: --exclude=<pattern>:: - In addition to those found in .gitignore (per directory) and - $GIT_DIR/info/exclude, also consider these patterns to be in the - set of the ignore rules in effect. + Use the given exclude pattern in addition to the standard ignore rules + (see linkgit:gitignore[5]). -x:: - Don't use the standard ignore rules read from .gitignore (per - directory) and $GIT_DIR/info/exclude, but do still use the ignore - rules given with `-e` options. This allows removing all untracked + Don't use the standard ignore rules (see linkgit:gitignore[5]), but + still use the ignore rules given with `-e` options from the command + line. This allows removing all untracked files, including build products. This can be used (possibly in - conjunction with 'git reset') to create a pristine + conjunction with 'git restore' or 'git reset') to create a pristine working directory to test a clean build. -X:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index a55536f0bf..08d6045c4a 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -15,14 +15,16 @@ SYNOPSIS [--dissociate] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] [--no-tags] [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules] - [--jobs <n>] [--] <repository> [<directory>] + [--[no-]remote-submodules] [--jobs <n>] [--sparse] + [--filter=<filter>] [--] <repository> + [<directory>] DESCRIPTION ----------- Clones a repository into a newly created directory, creates remote-tracking branches for each branch in the cloned repository -(visible using `git branch -r`), and creates and checks out an +(visible using `git branch --remotes`), and creates and checks out an initial branch that is forked from the cloned repository's currently active branch. @@ -40,8 +42,8 @@ configuration variables. OPTIONS ------- ---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 @@ -62,8 +64,8 @@ Git transport instead. directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository. ---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 @@ -80,13 +82,13 @@ which automatically call `git gc --auto`. (See linkgit:git-gc[1].) If these objects are removed and were referenced by the cloned repository, then the cloned repository will become corrupt. + -Note that running `git repack` without the `-l` option in a repository -cloned with `-s` will copy objects from the source repository into a pack -in the cloned repository, removing the disk space savings of `clone -s`. -It is safe, however, to run `git gc`, which uses the `-l` option by +Note that running `git repack` without the `--local` option in a repository +cloned with `--shared` will copy objects from the source repository into a pack +in the cloned repository, removing the disk space savings of `clone --shared`. +It is safe, however, to run `git gc`, which uses the `--local` option by default. + -If you want to break the dependency of a repository cloned with `-s` on +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. @@ -115,31 +117,39 @@ objects from the source repository into a pack in the cloned repository. same repository, and this option can be used to stop the borrowing. ---quiet:: -q:: +--quiet:: Operate quietly. Progress is not reported to the standard error stream. ---verbose:: -v:: +--verbose:: Run verbosely. Does not affect the reporting of progress status to the standard error stream. --progress:: Progress status is reported on the standard error stream - by default when it is attached to a terminal, unless -q + 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. ---no-checkout:: +--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 + sent to the other side in the order listed on the command line. + -n:: +--no-checkout:: No checkout of HEAD is performed after the clone is complete. --bare:: Make a 'bare' Git repository. That is, instead of creating `<directory>` and placing the administrative files in `<directory>/.git`, make the `<directory>` - itself the `$GIT_DIR`. This obviously implies the `-n` + 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 to corresponding local branch heads, without mapping @@ -147,6 +157,22 @@ 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. + +--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 + 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 + the `--filter` option in linkgit:git-rev-list[1]. + --mirror:: Set up a mirror of the source repository. This implies `--bare`. Compared to `--bare`, `--mirror` not only maps local branches of the @@ -155,13 +181,13 @@ 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. ---origin <name>:: -o <name>:: +--origin <name>:: Instead of using the remote name `origin` to keep track of the upstream repository, use `<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 instead. In a non-bare repository, this is the branch that will @@ -169,8 +195,8 @@ objects from the source repository into a pack in the cloned repository. `--branch` can also take tags and detaches the HEAD at that commit in the resulting repository. ---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. @@ -179,8 +205,8 @@ objects from the source repository into a pack in the cloned repository. Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) ---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 @@ -189,6 +215,12 @@ objects from the source repository into a pack in the cloned repository. values are given for the same key, each value will be written to the config file. This makes it safe, for example, to add additional fetch refspecs to the origin remote. ++ +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 +corresponding `--mirror` and `--no-tags` options instead. --depth <depth>:: Create a 'shallow' clone with a history truncated to the @@ -246,6 +278,12 @@ or `--mirror` is given) --[no-]shallow-submodules:: All submodules which are cloned will be shallow with a depth of 1. +--[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>:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index 03d18465d4..f58e9c43e6 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -13,7 +13,10 @@ SYNOPSIS DESCRIPTION ----------- -This command formats its input into multiple columns. +This command formats the lines of its standard input into a table with +multiple columns. Each input line occupies one cell of the table. It +is used internally by other git commands to format output into +columns. OPTIONS ------- @@ -23,7 +26,7 @@ OPTIONS --mode=<mode>:: Specify layout mode. See configuration variable column.ui for option - syntax. + syntax in linkgit:git-config[1]. --raw-mode=<n>:: Same as --mode but take mode encoded as a number. This is mainly used @@ -43,6 +46,34 @@ OPTIONS --padding=<N>:: The number of spaces between columns. One space by default. +EXAMPLES +-------- + +Format data by columns: +------------ +$ seq 1 24 | git column --mode=column --padding=5 +1 4 7 10 13 16 19 22 +2 5 8 11 14 17 20 23 +3 6 9 12 15 18 21 24 +------------ + +Format data by rows: +------------ +$ seq 1 21 | git column --mode=row --padding=5 +1 2 3 4 5 6 7 +8 9 10 11 12 13 14 +15 16 17 18 19 20 21 +------------ + +List some tags in a table with unequal column widths: +------------ +$ git tag --list 'v2.4.*' --column=row,dense +v2.4.0 v2.4.0-rc0 v2.4.0-rc1 v2.4.0-rc2 v2.4.0-rc3 +v2.4.1 v2.4.10 v2.4.11 v2.4.12 v2.4.2 +v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7 +v2.4.8 v2.4.9 +------------ + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index dececb79d7..a3d996787b 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -3,38 +3,43 @@ git-commit-graph(1) NAME ---- -git-commit-graph - Write and verify Git commit graph files +git-commit-graph - Write and verify Git commit-graph files SYNOPSIS -------- [verse] -'git commit-graph read' [--object-dir <dir>] -'git commit-graph verify' [--object-dir <dir>] -'git commit-graph write' <options> [--object-dir <dir>] +'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress] +'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress] DESCRIPTION ----------- -Manage the serialized commit graph file. +Manage the serialized commit-graph file. OPTIONS ------- --object-dir:: - Use given directory for the location of packfiles and commit graph + Use given directory for the location of packfiles and commit-graph file. This parameter exists to specify the location of an alternate - that only has the objects directory, not a full .git directory. The - commit graph file is expected to be at <dir>/info/commit-graph and - the packfiles are expected to be in <dir>/pack. + that only has the objects directory, not a full `.git` directory. The + commit-graph file is expected to be in the `<dir>/info` directory and + the packfiles are expected to be in `<dir>/pack`. If the directory + could not be made into an absolute path, or does not match any known + object directory, `git commit-graph ...` will exit with non-zero + status. +--[no-]progress:: + Turn progress on/off explicitly. If neither is specified, progress is + shown if standard error is connected to a terminal. COMMANDS -------- 'write':: -Write a commit graph file based on the commits found in packfiles. +Write a commit-graph file based on the commits found in packfiles. + With the `--stdin-packs` option, generate the new commit graph by walking objects only in the specified pack-indexes. (Cannot be combined @@ -51,53 +56,78 @@ or `--stdin-packs`.) + With the `--append` option, include all commits that are present in the existing commit-graph file. - -'read':: - -Read a graph file given by the commit-graph file and output basic -details about the graph file. Used for debugging purposes. ++ +With the `--changed-paths` option, compute and write information about the +paths changed between a commit and its first parent. This operation can +take a while on large repositories. It provides significant performance gains +for getting history of a directory or a file with `git log -- <path>`. ++ +With the `--split[=<strategy>]` option, write the commit-graph as a +chain of multiple commit-graph files stored in +`<dir>/info/commit-graphs`. Commit-graph layers are merged based on the +strategy and other splitting options. The new commits not already in the +commit-graph are added in a new "tip" file. This file is merged with the +existing file if the following merge conditions are met: ++ +* If `--split=no-merge` is specified, a merge is never performed, and +the remaining options are ignored. `--split=replace` overwrites the +existing chain with a new one. A bare `--split` defers to the remaining +options. (Note that merging a chain of commit graphs replaces the +existing chain with a length-1 chain where the first and only +incremental holds the entire graph). ++ +* If `--size-multiple=<X>` is not specified, let `X` equal 2. If the new +tip file would have `N` commits and the previous tip has `M` commits and +`X` times `N` is greater than `M`, instead merge the two files into a +single file. ++ +* If `--max-commits=<M>` is specified with `M` a positive integer, and the +new tip file would have more than `M` commits, then instead merge the new +tip with the previous tip. ++ +Finally, if `--expire-time=<datetime>` is not specified, let `datetime` +be the current time. After writing the split commit-graph, delete all +unused commit-graph whose modified times are older than `datetime`. 'verify':: Read the commit-graph file and verify its contents against the object database. Used to check for corrupted data. ++ +With the `--shallow` option, only check the tip commit-graph file in +a chain of split commit-graphs. EXAMPLES -------- -* Write a commit graph file for the packed commits in your local .git folder. +* Write a commit-graph file for the packed commits in your local `.git` + directory. + ------------------------------------------------ $ git commit-graph write ------------------------------------------------ -* Write a graph file, extending the current graph file using commits -* in <pack-index>. +* Write a commit-graph file, extending the current commit-graph file + using commits in `<pack-index>`. + ------------------------------------------------ $ echo <pack-index> | git commit-graph write --stdin-packs ------------------------------------------------ -* Write a graph file containing all reachable commits. +* Write a commit-graph file containing all reachable commits. + ------------------------------------------------ $ git show-ref -s | git commit-graph write --stdin-commits ------------------------------------------------ -* Write a graph file containing all commits in the current -* commit-graph file along with those reachable from HEAD. +* Write a commit-graph file containing all commits in the current + commit-graph file along with those reachable from `HEAD`. + ------------------------------------------------ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append ------------------------------------------------ -* Read basic information from the commit-graph file. -+ ------------------------------------------------- -$ git commit-graph read ------------------------------------------------- - GIT --- diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 002dae625e..2e2c581098 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -23,6 +23,10 @@ Creates a new commit object based on the provided tree object and emits the new commit object id on stdout. The log message is read from the standard input, unless `-m` or `-F` options are given. +The `-m` and `-F` options can be given any number of times, in any +order. The commit log message will be composed in the order in which +the options are given. + A commit object may have any number of parents. With exactly one parent, it is an ordinary commit. Having more than one parent makes the commit a merge between several lines of history. Initial (root) @@ -41,7 +45,7 @@ state was. OPTIONS ------- <tree>:: - An existing tree object + An existing tree object. -p <parent>:: Each `-p` indicates the id of a parent commit object. @@ -52,18 +56,16 @@ OPTIONS -F <file>:: Read the commit log message from the given file. Use `-` to read - from the standard input. + from the standard input. This can be given more than once and the + content of each file becomes its own paragraph. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. - ---no-gpg-sign:: - Do not GPG-sign commit, to countermand a `--gpg-sign` option - given earlier on the command line. - + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand a `--gpg-sign` option given earlier on the command line. Commit Information ------------------ @@ -74,26 +76,6 @@ A commit encapsulates: - author name, email and date - committer name and email and the commit time. -While parent object ids are provided on the command line, author and -committer information is taken from the following environment variables, -if set: - - GIT_AUTHOR_NAME - GIT_AUTHOR_EMAIL - GIT_AUTHOR_DATE - GIT_COMMITTER_NAME - GIT_COMMITTER_EMAIL - GIT_COMMITTER_DATE - -(nb "<", ">" and "\n"s are stripped) - -In case (some of) these environment variables are not set, the information -is taken from the configuration items user.name and user.email, or, if not -present, the environment variable EMAIL, or, if that is not set, -system user name and the hostname used for outgoing mail (taken -from `/etc/mailname` and falling back to the fully qualified hostname when -that file does not exist). - A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, 'git commit-tree' will just wait for one to be entered and terminated with ^D. @@ -112,6 +94,7 @@ FILES SEE ALSO -------- linkgit:git-write-tree[1] +linkgit:git-commit[1] GIT --- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index f970a43422..a3baea32ae 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -13,20 +13,25 @@ SYNOPSIS [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] [--[no-]status] - [-i | -o] [-S[<keyid>]] [--] [<file>...] + [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [-S[<keyid>]] [--] [<pathspec>...] DESCRIPTION ----------- -Stores the current contents of the index in a new commit along -with a log message from the user describing the changes. +Create a new commit containing the current contents of the index and +the given log message describing the changes. The new commit is a +direct child of HEAD, usually the tip of the current branch, and the +branch is updated to point to it (unless no branch is associated with +the working tree, in which case HEAD is "detached" as described in +linkgit:git-checkout[1]). -The content to be added can be specified in several ways: +The content to be committed can be specified in several ways: -1. by using 'git add' to incrementally "add" changes to the - index before using the 'commit' command (Note: even modified - files must be "added"); +1. by using linkgit:git-add[1] to incrementally "add" changes to the + index before using the 'commit' command (Note: even modified files + must be "added"); -2. by using 'git rm' to remove files from the working tree +2. by using linkgit:git-rm[1] to remove files from the working tree and the index, again before using the 'commit' command; 3. by listing files as arguments to the 'commit' command @@ -274,22 +279,37 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) already been staged. If used together with `--allow-empty` paths are also not required, and an empty commit will be created. +--pathspec-from-file=<file>:: + 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 + global `--literal-pathspecs`. + +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). + -u[<mode>]:: --untracked-files[=<mode>]:: Show untracked files. + +-- The mode parameter is optional (defaults to 'all'), and is used to specify the handling of untracked files; when -u is not used, the default is 'normal', i.e. show untracked files and directories. -+ + The possible options are: -+ + - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. -+ + The default can be changed using the status.showUntrackedFiles configuration variable documented in linkgit:git-config[1]. +-- -v:: --verbose:: @@ -328,26 +348,23 @@ changes to tracked files. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. - ---no-gpg-sign:: - Countermand `commit.gpgSign` configuration variable that is - set to force each and every commit to be signed. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. \--:: Do not interpret any more arguments as options. -<file>...:: - When files are given on the command line, the command - commits the contents of the named files, without - recording the changes already staged. The contents of - these files are also staged for the next commit on top - of what have been staged before. - -:git-commit: 1 -include::date-formats.txt[] +<pathspec>...:: + When pathspec is given on the command line, commit the contents of + the files that match the pathspec without recording the changes + already added to the index. The contents of these files are also + staged for the next commit on top of what have been staged before. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. EXAMPLES -------- @@ -355,7 +372,7 @@ When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area called the "index" with 'git add'. A file can be reverted back, only in the index but not in the working tree, -to that of the last commit with `git reset HEAD -- <file>`, +to that of the last commit with `git restore --staged <file>`, which effectively reverts 'git add' and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, @@ -442,6 +459,43 @@ alter the order the changes are committed, because the merge should be recorded as a single commit. In fact, the command refuses to run when given pathnames (but see `-i` option). +COMMIT INFORMATION +------------------ + +Author and committer information is taken from the following environment +variables, if set: + + GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL + GIT_AUTHOR_DATE + GIT_COMMITTER_NAME + GIT_COMMITTER_EMAIL + GIT_COMMITTER_DATE + +(nb "<", ">" and "\n"s are stripped) + +The author and committer names are by convention some form of a personal name +(that is, the name by which other humans refer to you), although Git does not +enforce or require any particular form. Arbitrary Unicode may be used, subject +to the constraints listed above. This name has no effect on authentication; for +that, see the `credential.username` variable in linkgit:git-config[1]. + +In case (some of) these environment variables are not set, the information +is taken from the configuration items `user.name` and `user.email`, or, if not +present, the environment variable EMAIL, or, if that is not set, +system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). + +The `author.name` and `committer.name` and their corresponding email options +override `user.name` and `user.email` if set and are overridden themselves by +the environment variables. + +The typical usage is to set just the `user.name` and `user.email` variables; +the other options are provided for more complex use cases. + +:git-commit: 1 +include::date-formats.txt[] DISCUSSION ---------- diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 8e240435be..7573160f21 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,18 +9,18 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]] 'git config' [<file-option>] [--type=<type>] --add name value 'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get name [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] 'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list +'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>] -e | --edit @@ -45,13 +45,15 @@ unset an existing `--type` specifier with `--no-type`. When reading, the values are read from the system, global and repository local configuration files by default, and options -`--system`, `--global`, `--local` and `--file <filename>` can be -used to tell the command to read from only that location (see <<FILES>>). +`--system`, `--global`, `--local`, `--worktree` and +`--file <filename>` can be used to tell the command to read from only +that location (see <<FILES>>). When writing, the new value is written to the repository local configuration file by default, and options `--system`, `--global`, -`--file <filename>` can be used to tell the command to write to -that location (you can say `--local` but that is the default). +`--worktree`, `--file <filename>` can be used to tell the command to +write to that location (you can say `--local` but that is the +default). This command will fail with non-zero status upon error. Some exit codes are: @@ -124,13 +126,18 @@ See also <<FILES>>. --local:: For writing options: write to the repository `.git/config` file. - This is the default behavior. + This is the default behavior. + For reading options: read only from the repository `.git/config` rather than from all available files. + See also <<FILES>>. +--worktree:: + Similar to `--local` except that `.git/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. @@ -188,8 +195,8 @@ Valid `<type>`'s include: --bool-or-int:: --path:: --expiry-date:: - Historical options for selecting a type specifier. Prefer instead `--type`, - (see: above). + Historical options for selecting a type specifier. Prefer instead `--type` + (see above). --no-type:: Un-sets the previously set type specifier (if one was previously set). This @@ -215,6 +222,11 @@ Valid `<type>`'s include: the actual origin (config file path, ref, or blob id if applicable). +--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). + --get-colorbool name [stdout-is-tty]:: Find the color setting for `name` (e.g. `color.diff`) and output @@ -233,7 +245,9 @@ Valid `<type>`'s include: output. The optional `default` parameter is used instead, if there is no color configured for `name`. + -`--type=color [--default=<default>]` is preferred over `--get-color`. +`--type=color [--default=<default>]` is preferred over `--get-color` +(but note that `--get-color` will omit the trailing newline printed by +`--type=color`). -e:: --edit:: @@ -281,6 +295,10 @@ $XDG_CONFIG_HOME/git/config:: $GIT_DIR/config:: Repository specific configuration file. +$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 @@ -299,9 +317,10 @@ 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` and the `--system` options will limit the file used -to the global or system-wide file respectively. The `GIT_CONFIG` environment -variable has a similar effect, but you can specify any filename you want. +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. ENVIRONMENT @@ -325,33 +344,35 @@ EXAMPLES Given a .git/config like this: - # - # This is the config file, and - # a '#' or ';' character indicates - # a comment - # - - ; core variables - [core] - ; Don't trust file modes - filemode = false - - ; Our diff algorithm - [diff] - external = /usr/local/bin/diff-wrapper - renames = true - - ; Proxy settings - [core] - gitproxy=proxy-command for kernel.org - gitproxy=default-proxy ; for all the rest - - ; HTTP - [http] - sslVerify - [http "https://weak.example.com"] - sslVerify = false - cookieFile = /tmp/cookie.txt +------------ +# +# This is the config file, and +# a '#' or ';' character indicates +# a comment +# + +; core variables +[core] + ; Don't trust file modes + filemode = false + +; Our diff algorithm +[diff] + external = /usr/local/bin/diff-wrapper + renames = true + +; Proxy settings +[core] + gitproxy=proxy-command for kernel.org + gitproxy=default-proxy ; for all the rest + +; HTTP +[http] + sslVerify +[http "https://weak.example.com"] + sslVerify = false + cookieFile = /tmp/cookie.txt +------------ you can set the filemode to true with @@ -442,9 +463,9 @@ For URLs in `https://weak.example.com`, `http.sslVerify` is set to false, while it is set to `true` for all others: ------------ -% git config --bool --get-urlmatch http.sslverify https://good.example.com +% git config --type=bool --get-urlmatch http.sslverify https://good.example.com true -% git config --bool --get-urlmatch http.sslverify https://weak.example.com +% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com false % git config --get-urlmatch http https://weak.example.com http.cookieFile /tmp/cookie.txt diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 693dd9d9d7..76b0798856 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -94,6 +94,10 @@ stored on its own line as a URL like: https://user:pass@example.com ------------------------------ +No other kinds of lines (e.g. empty lines or comment lines) are +allowed in the file, even though some may be silently ignored. Do +not view or edit the file with editors. + When Git needs authentication for a particular URL context, credential-store will consider that context a pattern to match against each entry in the credentials file. If the protocol, hostname, and diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index b211440373..31c81c4c02 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -19,8 +19,7 @@ from system-specific helpers, as well as prompting the user for usernames and passwords. The git-credential command exposes this interface to scripts which may want to retrieve, store, or prompt for credentials in the same manner as Git. The design of this scriptable -interface models the internal C API; see -link:technical/api-credentials.html[the Git credential API] for more +interface models the internal C API; see credential.h for more background on the concepts. git-credential takes an "action" option on the command-line (one of @@ -104,17 +103,20 @@ INPUT/OUTPUT FORMAT `git credential` reads and/or writes (depending on the action used) credential information in its standard input/output. This information can correspond either to keys for which `git credential` will obtain -the login/password information (e.g. host, protocol, path), or to the -actual credential data to be obtained (login/password). +the login information (e.g. host, protocol, path), or to the actual +credential data to be obtained (username/password). The credential is split into a set of named attributes, with one -attribute per line. Each attribute is -specified by a key-value pair, 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. +attribute per line. Each attribute is specified by a key-value pair, +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, 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. + Git understands the following attributes: `protocol`:: @@ -124,7 +126,8 @@ Git understands the following attributes: `host`:: - The remote hostname for a network credential. + The remote hostname for a network credential. This includes + the port number if one was specified (e.g., "example.com:8088"). `path`:: @@ -135,7 +138,7 @@ Git understands the following attributes: `username`:: The credential's username, if we already have one (e.g., from a - URL, from the user, or from a previously run helper). + URL, the configuration, the user, or from a previously run helper). `password`:: @@ -147,8 +150,12 @@ Git understands the following attributes: value is parsed as a URL and treated as if its constituent parts were read (e.g., `url=https://example.com` would behave as if `protocol=https` and `host=example.com` had been provided). This - can help callers avoid parsing URLs themselves. Note that any - components which are missing from the URL (e.g., there is no - username in the example above) will be set to empty; if you want - to provide a URL and override some attributes, provide the URL - attribute first, followed by any overrides. + can help callers avoid parsing URLs themselves. ++ +Note that specifying a protocol is mandatory and if the URL +doesn't specify a hostname (e.g., "cert:///path/to/file") the +credential will contain a hostname attribute whose value is an +empty string. ++ +Components which are missing from the URL (e.g., there is no +username in the example above) will be left unset. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index f98b7c6ed7..1b1c71ad9d 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -232,7 +232,7 @@ write so it might not be enough to grant the users using 'git-cvsserver' write access to the database file without granting them write access to the directory, too. -The database can not be reliably regenerated in a +The database cannot be reliably regenerated in a consistent form after the branch it is tracking has changed. Example: For merged branches, 'git-cvsserver' only tracks one branch of development, and after a 'git merge' an @@ -294,7 +294,7 @@ In `dbDriver` and `dbUser` you can use the following variables: Git directory name %g:: Git directory name, where all characters except for - alpha-numeric ones, `.`, and `-` are replaced with + alphanumeric ones, `.`, and `-` are replaced with `_` (this should make it easier to use the directory name in a filename if wanted) %m:: diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 56d54a4898..fdc28c041c 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -57,7 +57,7 @@ OPTIONS This is sort of "Git root" - if you run 'git daemon' with '--base-path=/srv/git' on example.com, then if you later try to pull 'git://example.com/hello.git', 'git daemon' will interpret the path - as '/srv/git/hello.git'. + as `/srv/git/hello.git`. --base-path-relaxed:: If --base-path is enabled and repo lookup fails, with this option diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e027fb8c4b..a88f6ae2c6 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -18,7 +18,9 @@ The command finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the -abbreviated object name of the most recent commit. +abbreviated object name of the most recent commit. The result +is a "human-readable" object name which can also be used to +identify the commit to other git commands. By default (without --all or --tags) `git describe` only shows annotated tags. For more information about creating annotated tags @@ -137,7 +139,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" + 7-char abbreviation for the tip commit +The hash suffix is "-g" + unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 2319b2b192..5c8a2a5e97 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] - [-t] [-r] [-c | --cc] [--root] [<common diff options>] - <tree-ish> [<tree-ish>] [<path>...] + [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] + [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] DESCRIPTION ----------- @@ -31,10 +31,7 @@ include::diff-options.txt[] <path>...:: If provided, the results are limited to a subset of files - matching one of these prefix strings. - i.e., file matches `/^<pattern1>|<pattern2>|.../` - Note that this parameter does not provide any wildcard or regexp - features. + matching one of the provided pathspecs. -r:: recurse into sub-trees @@ -108,6 +105,13 @@ include::pretty-options.txt[] itself and the commit log message is not shown, just like in any other "empty diff" case. +--combined-all-paths:: + This flag causes combined diffs (used for merge commits) to + list the name of the file from all parents. It thus only has + effect when -c or --cc are specified, and is likely only + useful if filename changes are detected (i.e. when either + rename or copy detection have been requested). + --always:: Show the commit itself and the commit log message even if the diff itself is empty. @@ -115,51 +119,6 @@ include::pretty-options.txt[] include::pretty-formats.txt[] - -LIMITING OUTPUT ---------------- -If you're only interested in differences in a subset of files, for -example some architecture-specific files, you might do: - - git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 - -and it will only show you what changed in those two directories. - -Or if you are searching for what changed in just `kernel/sched.c`, just do - - git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c - -and it will ignore all differences to other files. - -The pattern is always the prefix, and is matched exactly. There are no -wildcards. Even stricter, it has to match a complete path component. -I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h` -so it can be used to name subdirectories. - -An example of normal usage is: - - torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4 - :100664 100664 ac348b... a01513... git-fsck-objects.c - -which tells you that the last commit changed just one file (it's from -this one: - ------------------------------------------------------------------------------ -commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 -tree 5319e4d609cdd282069cc4dce33c1db559539b03 -parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 -author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 -committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 - -Make "git-fsck-objects" print out all the root commits it finds. - -Once I do the reference tracking, I'll also make it print out all the -HEAD commits it finds, which is even more interesting. ------------------------------------------------------------------------------ - -in case you care). - - include::diff-format.txt[] GIT diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index b180f1fa5b..37781cf175 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -36,7 +36,7 @@ two blob objects, or changes between two files on disk. running the command in a working tree controlled by Git and at least one of the paths points outside the working tree, or when running the command outside a working tree - controlled by Git. + controlled by Git. This form implies `--exit-code`. 'git diff' [<options>] --cached [<commit>] [--] [<path>...]:: @@ -72,10 +72,10 @@ two blob objects, or changes between two files on disk. This form is to view the changes on the branch containing and up to the second <commit>, starting at a common ancestor of both <commit>. "git diff A\...B" is equivalent to - "git diff $(git-merge-base A B) B". You can omit any one + "git diff $(git merge-base A B) B". You can omit any one of <commit>, which has the same effect as using HEAD instead. -Just in case if you are doing something exotic, it should be +Just in case you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the last two forms that use ".." notations, can be any <tree>. @@ -132,9 +132,9 @@ $ git diff HEAD <3> + <1> Changes in the working tree not yet staged for the next commit. <2> Changes between the index and your last commit; what you -would be committing if you run "git commit" without "-a" option. + 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" + would be committing if you run "git commit -a" Comparing with arbitrary commits:: + @@ -145,10 +145,10 @@ $ git diff HEAD^ HEAD <3> ------------ + <1> Instead of using the tip of the current branch, compare with the -tip of "test" branch. + tip of "test" branch. <2> Instead of comparing with the tip of "test" branch, compare with -the tip of the current branch, but limit the comparison to the -file "test". + the tip of the current branch, but limit the comparison to the + file "test". <3> Compare the version before the last commit and the last commit. Comparing branches:: @@ -162,7 +162,7 @@ $ git diff topic...master <3> <1> Changes between the tips of the topic and the master branches. <2> Same as above. <3> Changes that occurred on the master branch since when the topic -branch was started off it. + branch was started off it. Limiting the diff output:: + @@ -173,9 +173,9 @@ $ git diff arch/i386 include/asm-i386 <3> ------------ + <1> Show only modification, rename, and copy, but not addition -or deletion. + or deletion. <2> Show only names and the nature of change, but not actual -diff output. + diff output. <3> Limit diff output to named subtrees. Munging the diff output:: @@ -186,7 +186,7 @@ $ git diff -R <2> ------------ + <1> Spend extra cycles to find renames, copies and complete -rewrites (very expensive). + rewrites (very expensive). <2> Output diff in reverse. SEE ALSO diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 96c26e6aa8..484c485fd0 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -90,7 +90,9 @@ instead. `--no-symlinks` is the default on Windows. 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. + 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. --[no-]trust-exit-code:: 'git-difftool' invokes a diff tool individually on each file. diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index ce954be532..e8950de3ba 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -17,9 +17,9 @@ This program dumps the given revisions in a form suitable to be piped into 'git fast-import'. You can use it as a human-readable bundle replacement (see -linkgit:git-bundle[1]), or as a kind of an interactive -'git filter-branch'. - +linkgit:git-bundle[1]), or as a format that can be edited before being +fed to 'git fast-import' in order to do history rewrites (an ability +relied on by tools like 'git filter-repo'). OPTIONS ------- @@ -75,11 +75,20 @@ produced incorrect results if you gave these options. Before processing any input, load the marks specified in <file>. The input file must exist, must be readable, and must use the same format as produced by --export-marks. + +--mark-tags:: + In addition to labelling blobs and commits with mark ids, also + label tags. This is useful in conjunction with + `--export-marks` and `--import-marks`, and is also useful (and + necessary) for exporting of nested tags. It does not hurt + other cases and would be the default, but many fast-import + frontends are not prepared to accept tags with mark + identifiers. + -Any commits that have already been marked will not be exported again. -If the backend uses a similar --import-marks file, this allows for -incremental bidirectional exporting of the repository by keeping the -marks the same across runs. +Any commits (or tags) that have already been marked will not be +exported again. If the backend uses a similar --import-marks file, +this allows for incremental bidirectional exporting of the repository +by keeping the marks the same across runs. --fake-missing-tagger:: Some old repositories have tags without a tagger. The @@ -110,6 +119,32 @@ marks the same across runs. the shape of the history and stored tree. See the section on `ANONYMIZING` below. +--reference-excluded-parents:: + By default, running a command such as `git fast-export + master~5..master` will not include the commit master{tilde}5 + and will make master{tilde}4 no longer have master{tilde}5 as + a parent (though both the old master{tilde}4 and new + master{tilde}4 will have all the same files). Use + --reference-excluded-parents to instead have the stream + refer to commits in the excluded range of history by their + sha1sum. Note that the resulting stream can only be used by a + repository which already contains the necessary parent + commits. + +--show-original-ids:: + Add an extra directive to the output for commits and blobs, + `original-oid <SHA1SUM>`. While such directives will likely be + ignored by importers such as git-fast-import, it may be useful + for intermediary filters (e.g. for rewriting commit messages + which refer to older commits, or for stripping blobs by id). + +--reencode=(yes|no|abort):: + Specify how to handle `encoding` header in commit objects. When + asking to 'abort' (which is the default), this program will die + when encountering such a commit object. With 'yes', the commit + message will be re-encoded into UTF-8. With 'no', the original + encoding will be preserved. + --refspec:: Apply the specified refspec to each ref exported. Multiple of them can be specified. @@ -119,7 +154,9 @@ marks the same across runs. 'git rev-list', that specifies the specific objects and references to export. For example, `master~10..master` causes the current master reference to be exported along with all objects - added since its 10th ancestor commit. + added since its 10th ancestor commit and (unless the + --reference-excluded-parents option is specified) all files + common to master{tilde}9 and master{tilde}10. EXAMPLES -------- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index e81117d27f..77c6b3d001 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -40,9 +40,10 @@ OPTIONS not contain the old commit). --quiet:: - Disable all non-fatal output, making fast-import silent when it - is successful. This option disables the output shown by - --stats. + Disable the output shown by --stats, making fast-import usually + be silent when it is successful. However, if the import stream + has directives intended to show user output (e.g. `progress` + directives), the corresponding messages will still be shown. --stats:: Display some basic statistics about the objects fast-import has @@ -50,6 +51,21 @@ OPTIONS memory used by fast-import during this run. Showing this output is currently the default, but can be disabled with --quiet. +--allow-unsafe-features:: + Many command-line options can be provided as part of the + fast-import stream itself by using the `feature` or `option` + commands. However, some of these options are unsafe (e.g., + allowing fast-import to access the filesystem outside of the + repository). These options are disabled by default, but can be + allowed by providing this option on the command line. This + currently impacts only the `export-marks`, `import-marks`, and + `import-marks-if-exists` feature commands. ++ + Only enable this option if you trust the program generating the + fast-import stream! This option is enabled automatically for + remote-helpers that use the `import` capability, as they are + already trusted to run their own code. + Options for Frontends ~~~~~~~~~~~~~~~~~~~~~ @@ -106,6 +122,26 @@ Locations of Marks Files Relative and non-relative marks may be combined by interweaving --(no-)-relative-marks with the --(import|export)-marks= options. +Submodule Rewriting +~~~~~~~~~~~~~~~~~~~ + +--rewrite-submodules-from=<name>:<file>:: +--rewrite-submodules-to=<name>:<file>:: + Rewrite the object IDs for the submodule specified by <name> from the values + used in the from <file> to those used in the to <file>. The from marks should + have been created by `git fast-export`, and the to marks should have been + created by `git fast-import` when importing that same submodule. ++ +<name> may be any arbitrary string not containing a colon character, but the +same value must be used with both options when specifying corresponding marks. +Multiple submodules may be specified with different values for <name>. It is an +error not to use these options in corresponding pairs. ++ +These options are primarily useful when converting a repository from one hash +algorithm to another; without them, fast-import will fail if it encounters a +submodule because it has no way of writing the object ID into the new hash +algorithm. + Performance and Compression Tuning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -336,6 +372,13 @@ and control the current import process. More detailed discussion `commit` command. This command is optional and is not needed to perform an import. +`alias`:: + Record that a mark refers to a given object without first + creating any new object. Using --import-marks and referring + to missing marks will cause fast-import to fail, so aliases + can provide a way to set otherwise pruned commits to a valid + value (e.g. the nearest non-pruned ancestor). + `checkpoint`:: Forces fast-import to close the current packfile, generate its unique SHA-1 checksum and index, and start a new packfile. @@ -384,11 +427,13 @@ change to the project. .... 'commit' SP <ref> LF mark? + original-oid? ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? 'committer' (SP <name>)? SP LT <email> GT SP <when> LF + ('encoding' SP <encoding>)? data ('from' SP <commit-ish> LF)? - ('merge' SP <commit-ish> LF)? + ('merge' SP <commit-ish> LF)* (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* LF? .... @@ -420,7 +465,12 @@ However it is recommended that a `filedeleteall` command precede all `filemodify`, `filecopy`, `filerename` and `notemodify` commands in the same commit, as `filedeleteall` wipes the branch clean (see below). -The `LF` after the command is optional (it used to be required). +The `LF` after the command is optional (it used to be required). Note +that for reasons of backward compatibility, if the commit ends with a +`data` command (i.e. it has no `from`, `merge`, `filemodify`, +`filedelete`, `filecopy`, `filerename`, `filedeleteall` or +`notemodify` commands) then two `LF` commands may appear at the end of +the command instead of just one. `author` ^^^^^^^^ @@ -448,6 +498,12 @@ that was selected by the --date-format=<fmt> command-line option. See ``Date Formats'' above for the set of supported formats, and their syntax. +`encoding` +^^^^^^^^^^ +The optional `encoding` command indicates the encoding of the commit +message. Most commits are UTF-8 and the encoding is omitted, but this +allows importing commit messages into git without first reencoding them. + `from` ^^^^^^ The `from` command is used to specify the commit to initialize @@ -740,6 +796,19 @@ New marks are created automatically. Existing marks can be moved to another object simply by reusing the same `<idnum>` in another `mark` command. +`original-oid` +~~~~~~~~~~~~~~ +Provides the name of the object in the original source control system. +fast-import will simply ignore this directive, but filter processes +which operate on and modify the stream before feeding to fast-import +may have uses for this information + +.... + 'original-oid' SP <object-identifier> LF +.... + +where `<object-identifer>` is any string not containing LF. + `tag` ~~~~~ Creates an annotated tag referring to a specific commit. To create @@ -747,7 +816,9 @@ lightweight (non-annotated) tags see the `reset` command below. .... 'tag' SP <name> LF + mark? 'from' SP <commit-ish> LF + original-oid? 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF data .... @@ -822,6 +893,7 @@ assigned mark. .... 'blob' LF mark? + original-oid? data .... @@ -884,6 +956,21 @@ a data chunk which does not have an LF as its last byte. + The `LF` after `<delim> LF` is optional (it used to be required). +`alias` +~~~~~~~ +Record that a mark refers to a given object without first creating any +new object. + +.... + 'alias' LF + mark + 'to' SP <commit-ish> LF + LF? +.... + +For a detailed description of `<commit-ish>` see above under `from`. + + `checkpoint` ~~~~~~~~~~~~ Forces fast-import to close the current packfile, start a new one, and to @@ -949,10 +1036,6 @@ might want to refer to in their commit messages. 'get-mark' SP ':' <idnum> LF .... -This command can be used anywhere in the stream that comments are -accepted. In particular, the `get-mark` command can be used in the -middle of a commit but not in the middle of a `data` command. - See ``Responses To Commands'' below for details about how to read this output safely. @@ -979,9 +1062,10 @@ Output uses the same format as `git cat-file --batch`: <contents> LF ==== -This command can be used anywhere in the stream that comments are -accepted. In particular, the `cat-blob` command can be used in the -middle of a commit but not in the middle of a `data` command. +This command can be used where a `filemodify` directive can appear, +allowing it to be used in the middle of a commit. For a `filemodify` +using an inline directive, it can also appear right before the `data` +directive. See ``Responses To Commands'' below for details about how to read this output safely. @@ -994,8 +1078,8 @@ printing a blob from the active commit (with `cat-blob`) or copying a blob or tree from a previous commit for use in the current one (with `filemodify`). -The `ls` command can be used anywhere in the stream that comments are -accepted, including the middle of a commit. +The `ls` command can also be used where a `filemodify` directive can +appear, allowing it to be used in the middle of a commit. Reading from the active commit:: This form can only be used in the middle of a `commit`. @@ -1379,6 +1463,13 @@ deltas are suboptimal (see above) then also adding the `-f` option to force recomputation of all deltas can significantly reduce the final packfile size (30-50% smaller can be quite typical). +Instead of running `git repack` you can also run `git gc +--aggressive`, which will also optimize other things after an import +(e.g. pack loose refs). As noted in the "AGGRESSIVE" section in +linkgit:git-gc[1] the `--aggressive` option will find new deltas with +the `-f` option to linkgit:git-repack[1]. For the reasons elaborated +on above using `--aggressive` after a fast-import is one of the few +cases where it's known to be worthwhile. MEMORY UTILIZATION ------------------ diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index e319935597..5b1909fdf4 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -262,11 +262,11 @@ This updates (or creates, as necessary) branches `pu` and `tmp` in the local repository by fetching from the branches (respectively) `pu` and `maint` from the remote repository. + -The `pu` branch will be updated even if it is does not fast-forward, +The `pu` branch will be updated even if it does not fast-forward, because it is prefixed with a plus sign; `tmp` will not be. * Peek at a remote's branch, without configuring the remote in your local -repository: + repository: + ------------------------------------------------ $ git fetch git://git.kernel.org/pub/scm/git/git.git maint @@ -285,7 +285,7 @@ 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 can not be +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. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e6f08ab189..40ba4aa3e6 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -16,6 +16,19 @@ SYNOPSIS [--original <namespace>] [-d <directory>] [-f | --force] [--state-branch <branch>] [--] [<rev-list options>...] +WARNING +------- +'git filter-branch' has a plethora of pitfalls that can produce non-obvious +manglings of the intended history rewrite (and can leave you with little +time to investigate such problems since it has such abysmal performance). +These safety and performance issues cannot be backward compatibly fixed and +as such, its use is not recommended. Please use an alternative history +filtering tool such as https://github.com/newren/git-filter-repo/[git +filter-repo]. If you still need to use 'git filter-branch', please +carefully read <<SAFETY>> (and <<PERFORMANCE>>) to learn about the land +mines of filter-branch, and then vigilantly avoid as many of the hazards +listed there as reasonably possible. + DESCRIPTION ----------- Lets you rewrite Git revision history by rewriting the branches mentioned @@ -189,7 +202,7 @@ to other tags will be rewritten to point to the underlying commit. rewriting. When applying a tree filter, the command needs to temporarily check out the tree to some directory, which may consume considerable space in case of large projects. By default it - does this in the '.git-rewrite/' directory but you can override + does this in the `.git-rewrite/` directory but you can override that choice by this parameter. -f:: @@ -445,36 +458,245 @@ warned. (or if your git-gc is not new enough to support arguments to `--prune`, use `git repack -ad; git prune` instead). -NOTES ------ - -git-filter-branch allows you to make complex shell-scripted rewrites -of your Git history, but you probably don't need this flexibility if -you're simply _removing unwanted data_ like large files or passwords. -For those operations you may want to consider -http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner], -a JVM-based alternative to git-filter-branch, typically at least -10-50x faster for those use-cases, and with quite different -characteristics: - -* Any particular version of a file is cleaned exactly _once_. The BFG, - unlike git-filter-branch, does not give you the opportunity to - handle a file differently based on where or when it was committed - within your history. This constraint gives the core performance - benefit of The BFG, and is well-suited to the task of cleansing bad - data - you don't care _where_ the bad data is, you just want it - _gone_. - -* By default The BFG takes full advantage of multi-core machines, - cleansing commit file-trees in parallel. git-filter-branch cleans - commits sequentially (i.e. in a single-threaded manner), though it - _is_ possible to write filters that include their own parallelism, - in the scripts executed against each commit. - -* The http://rtyley.github.io/bfg-repo-cleaner/#examples[command options] - are much more restrictive than git-filter branch, and dedicated just - to the tasks of removing unwanted data- e.g: - `--strip-blobs-bigger-than 1M`. +[[PERFORMANCE]] +PERFORMANCE +----------- + +The performance of git-filter-branch is glacially slow; its design makes it +impossible for a backward-compatible implementation to ever be fast: + +* In editing files, git-filter-branch by design checks out each and + every commit as it existed in the original repo. If your repo has + `10^5` files and `10^5` commits, but each commit only modifies five + files, then git-filter-branch will make you do `10^10` modifications, + despite only having (at most) `5*10^5` unique blobs. + +* If you try and cheat and try to make git-filter-branch only work on + files modified in a commit, then two things happen + + ** you run into problems with deletions whenever the user is simply + trying to rename files (because attempting to delete files that + don't exist looks like a no-op; it takes some chicanery to remap + deletes across file renames when the renames happen via arbitrary + user-provided shell) + + ** even if you succeed at the map-deletes-for-renames chicanery, you + still technically violate backward compatibility because users + are allowed to filter files in ways that depend upon topology of + commits instead of filtering solely based on file contents or + names (though this has not been observed in the wild). + +* Even if you don't need to edit files but only want to e.g. rename or + remove some and thus can avoid checking out each file (i.e. you can + use --index-filter), you still are passing shell snippets for your + filters. This means that for every commit, you have to have a + prepared git repo where those filters can be run. That's a + significant setup. + +* Further, several additional files are created or updated per commit + by git-filter-branch. Some of these are for supporting the + convenience functions provided by git-filter-branch (such as map()), + while others are for keeping track of internal state (but could have + also been accessed by user filters; one of git-filter-branch's + regression tests does so). This essentially amounts to using the + filesystem as an IPC mechanism between git-filter-branch and the + user-provided filters. Disks tend to be a slow IPC mechanism, and + writing these files also effectively represents a forced + synchronization point between separate processes that we hit with + every commit. + +* The user-provided shell commands will likely involve a pipeline of + commands, resulting in the creation of many processes per commit. + Creating and running another process takes a widely varying amount + of time between operating systems, but on any platform it is very + slow relative to invoking a function. + +* git-filter-branch itself is written in shell, which is kind of slow. + This is the one performance issue that could be backward-compatibly + fixed, but compared to the above problems that are intrinsic to the + design of git-filter-branch, the language of the tool itself is a + relatively minor issue. + + ** Side note: Unfortunately, people tend to fixate on the + written-in-shell aspect and periodically ask if git-filter-branch + could be rewritten in another language to fix the performance + issues. Not only does that ignore the bigger intrinsic problems + with the design, it'd help less than you'd expect: if + git-filter-branch itself were not shell, then the convenience + functions (map(), skip_commit(), etc) and the `--setup` argument + could no longer be executed once at the beginning of the program + but would instead need to be prepended to every user filter (and + thus re-executed with every commit). + +The https://github.com/newren/git-filter-repo/[git filter-repo] tool is +an alternative to git-filter-branch which does not suffer from these +performance problems or the safety problems (mentioned below). For those +with existing tooling which relies upon git-filter-branch, 'git +repo-filter' also provides +https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely[filter-lamely], +a drop-in git-filter-branch replacement (with a few caveats). While +filter-lamely suffers from all the same safety issues as +git-filter-branch, it at least ameliorates the performance issues a +little. + +[[SAFETY]] +SAFETY +------ + +git-filter-branch is riddled with gotchas resulting in various ways to +easily corrupt repos or end up with a mess worse than what you started +with: + +* Someone can have a set of "working and tested filters" which they + document or provide to a coworker, who then runs them on a different + OS where the same commands are not working/tested (some examples in + the git-filter-branch manpage are also affected by this). + BSD vs. GNU userland differences can really bite. If lucky, error + messages are spewed. But just as likely, the commands either don't + do the filtering requested, or silently corrupt by making some + unwanted change. The unwanted change may only affect a few commits, + so it's not necessarily obvious either. (The fact that problems + won't necessarily be obvious means they are likely to go unnoticed + until the rewritten history is in use for quite a while, at which + point it's really hard to justify another flag-day for another + rewrite.) + +* Filenames with spaces are often mishandled by shell snippets since + they cause problems for shell pipelines. Not everyone is familiar + with find -print0, xargs -0, git-ls-files -z, etc. Even people who + are familiar with these may assume such flags are not relevant + because someone else renamed any such files in their repo back + before the person doing the filtering joined the project. And + often, even those familiar with handling arguments with spaces may + not do so just because they aren't in the mindset of thinking about + everything that could possibly go wrong. + +* Non-ascii filenames can be silently removed despite being in a + desired directory. Keeping only wanted paths is often done using + pipelines like `git ls-files | grep -v ^WANTED_DIR/ | xargs git rm`. + ls-files will only quote filenames if needed, so folks may not + notice that one of the files didn't match the regex (at least not + until it's much too late). Yes, someone who knows about + core.quotePath can avoid this (unless they have other special + characters like \t, \n, or "), and people who use ls-files -z with + something other than grep can avoid this, but that doesn't mean they + will. + +* Similarly, when moving files around, one can find that filenames + with non-ascii or special characters end up in a different + directory, one that includes a double quote character. (This is + technically the same issue as above with quoting, but perhaps an + interesting different way that it can and has manifested as a + problem.) + +* It's far too easy to accidentally mix up old and new history. It's + still possible with any tool, but git-filter-branch almost + invites it. If lucky, the only downside is users getting frustrated + that they don't know how to shrink their repo and remove the old + stuff. If unlucky, they merge old and new history and end up with + multiple "copies" of each commit, some of which have unwanted or + sensitive files and others which don't. This comes about in + multiple different ways: + + ** the default to only doing a partial history rewrite ('--all' is not + the default and few examples show it) + + ** the fact that there's no automatic post-run cleanup + + ** the fact that --tag-name-filter (when used to rename tags) doesn't + remove the old tags but just adds new ones with the new name + + ** the fact that little educational information is provided to inform + users of the ramifications of a rewrite and how to avoid mixing old + and new history. For example, this man page discusses how users + need to understand that they need to rebase their changes for all + their branches on top of new history (or delete and reclone), but + that's only one of multiple concerns to consider. See the + "DISCUSSION" section of the git filter-repo manual page for more + details. + +* Annotated tags can be accidentally converted to lightweight tags, + due to either of two issues: + + ** Someone can do a history rewrite, realize they messed up, restore + from the backups in refs/original/, and then redo their + git-filter-branch command. (The backup in refs/original/ is not a + 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 + annotated, you must use --tag-name-filter (and must not have + restored from refs/original/ in a previously botched rewrite). + +* Any commit messages that specify an encoding will become corrupted + by the rewrite; git-filter-branch ignores the encoding, takes the + original bytes, and feeds it to commit-tree without telling it the + proper encoding. (This happens whether or not --msg-filter is + used.) + +* Commit messages (even if they are all UTF-8) by default become + corrupted due to not being updated -- any references to other commit + hashes in commit messages will now refer to no-longer-extant + commits. + +* There are no facilities for helping users find what unwanted crud + they should delete, which means they are much more likely to have + incomplete or partial cleanups that sometimes result in confusion + and people wasting time trying to understand. (For example, folks + tend to just look for big files to delete instead of big directories + or extensions, and once they do so, then sometime later folks using + the new repository who are going through history will notice a build + artifact directory that has some files but not others, or a cache of + dependencies (node_modules or similar) which couldn't have ever been + functional since it's missing some files.) + +* If --prune-empty isn't specified, then the filtering process can + create hoards of confusing empty commits + +* If --prune-empty is specified, then intentionally placed empty + commits from before the filtering operation are also pruned instead + of just pruning commits that became empty due to filtering rules. + +* If --prune-empty is specified, sometimes empty commits are missed + and left around anyway (a somewhat rare bug, but it happens...) + +* A minor issue, but users who have a goal to update all names and + emails in a repository may be led to --env-filter which will only + update authors and committers, missing taggers. + +* If the user provides a --tag-name-filter that maps multiple tags to + the same name, no warning or error is provided; git-filter-branch + simply overwrites each tag in some undocumented pre-defined order + resulting in only one tag at the end. (A git-filter-branch + regression test requires this surprising behavior.) + +Also, the poor performance of git-filter-branch often leads to safety +issues: + +* Coming up with the correct shell snippet to do the filtering you + want is sometimes difficult unless you're just doing a trivial + modification such as deleting a couple files. Unfortunately, people + often learn if the snippet is right or wrong by trying it out, but + the rightness or wrongness can vary depending on special + circumstances (spaces in filenames, non-ascii filenames, funny + author names or emails, invalid timezones, presence of grafts or + replace objects, etc.), meaning they may have to wait a long time, + hit an error, then restart. The performance of git-filter-branch is + so bad that this cycle is painful, reducing the time available to + carefully re-check (to say nothing about what it does to the + patience of the person doing the rewrite even if they do technically + have more time available). This problem is extra compounded because + errors from broken filters may not be shown for a long time and/or + get lost in a sea of output. Even worse, broken filters often just + result in silent incorrect rewrites. + +* To top it all off, even when users finally find working commands, + they naturally want to share them. But they may be unaware that + their repo didn't have some special cases that someone else's does. + So, when someone else with a different repository runs the same + commands, they get hit by the problems above. Or, the user just + runs commands that really were vetted for special cases, but they + run it on a different OS where it doesn't work, as noted above. GIT --- diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 423b6e033b..6793d8fc05 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -51,7 +51,7 @@ OPTIONS CONFIGURATION ------------- -include::fmt-merge-msg-config.txt[] +include::config/fmt-merge-msg.txt[] merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 901faef1bf..6dcd39f6f6 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -128,13 +128,18 @@ objecttype:: objectsize:: The size of the object (the same as 'git cat-file -s' reports). - + Append `:disk` to get the size, in bytes, that the object takes up on + disk. See the note about on-disk sizes in the `CAVEATS` section below. objectname:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. For an abbreviation of the object name with desired length append `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The length may be exceeded to ensure unique object names. +deltabase:: + This expands to the object name of the delta base for the + given object, if it is stored as a delta. Otherwise it + expands to the null object name (all zeroes). upstream:: The name of a local ref which can be considered ``upstream'' @@ -209,6 +214,11 @@ symref:: `:lstrip` and `:rstrip` options in the same way as `refname` above. +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. + 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. @@ -361,6 +371,20 @@ This prints the authorname, if present. git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" ------------ +CAVEATS +------- + +Note that the sizes of objects on disk are reported accurately, but care +should be taken in drawing conclusions about which refs or objects are +responsible for disk usage. The size of a packed non-delta object may be +much larger than the size of objects which delta against it, but the +choice of which object is the base and which is the delta is arbitrary +and is subject to change during a repack. + +Note also that multiple copies of an object may be present in the object +database; in this case, it is undefined which copy's size or delta base +will be reported. + SEE ALSO -------- linkgit:git-show-ref[1] diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index b41e1329a7..0f81d0437b 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -17,12 +17,17 @@ SYNOPSIS [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] - [--in-reply-to=Message-Id] [--suffix=.<sfx>] + [--in-reply-to=<message id>] [--suffix=.<sfx>] [--ignore-if-in-upstream] - [--rfc] [--subject-prefix=Subject-Prefix] + [--cover-from-description=<mode>] + [--rfc] [--subject-prefix=<subject prefix>] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] - [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] + [--[no-]cover-letter] [--quiet] + [--[no-]encode-email-headers] + [--no-notes | --notes[=<ref>]] + [--interdiff=<previous>] + [--range-diff=<previous> [--creation-factor=<percent>]] [--progress] [<common diff options>] [ <since> | <revision range> ] @@ -63,7 +68,8 @@ they are created in the current working directory. The default path can be set with the `format.outputDirectory` configuration option. The `-o` option takes precedence over `format.outputDirectory`. To store patches in the current working directory even when -`format.outputDirectory` points elsewhere, use `-o .`. +`format.outputDirectory` points elsewhere, use `-o .`. All directory +components will be created. By default, the subject of a single patch is "[PATCH] " followed by the concatenation of lines from the commit message up to the first blank @@ -156,9 +162,9 @@ Beware that the default for 'git send-email' is to thread emails itself. If you want `git format-patch` to take care of threading, you will want to ensure that threading is disabled for `git send-email`. ---in-reply-to=Message-Id:: +--in-reply-to=<message id>:: Make the first mail (or all the mails with `--no-thread`) appear as a - reply to the given Message-Id, which avoids breaking threads to + reply to the given <message id>, which avoids breaking threads to provide a new patch series. --ignore-if-in-upstream:: @@ -168,9 +174,29 @@ will want to ensure that threading is disabled for `git send-email`. patches being generated, and any patch that matches is ignored. ---subject-prefix=<Subject-Prefix>:: +--cover-from-description=<mode>:: + Controls which parts of the cover letter will be automatically + populated using the branch's description. ++ +If `<mode>` is `message` or `default`, the cover letter subject will be +populated with placeholder text. The body of the cover letter will be +populated with the branch's description. This is the default mode when +no configuration nor command line option is specified. ++ +If `<mode>` is `subject`, the first paragraph of the branch description will +populate the cover letter subject. The remainder of the description will +populate the body of the cover letter. ++ +If `<mode>` is `auto`, if the first paragraph of the branch description +is greater than 100 bytes, then the mode will be `message`, otherwise +`subject` will be used. ++ +If `<mode>` is `none`, both the cover letter subject and body will be +populated with placeholder text. + +--subject-prefix=<subject prefix>:: Instead of the standard '[PATCH]' prefix in the subject - line, instead use '[<Subject-Prefix>]'. This + line, instead use '[<subject prefix>]'. This allows for useful naming of a patch series, and can be combined with the `--numbered` option. @@ -228,7 +254,47 @@ feeding the result to `git send-email`. containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--encode-email-headers:: +--no-encode-email-headers:: + Encode email headers that have non-ASCII characters with + "Q-encoding" (described in RFC 2047), instead of outputting the + headers verbatim. Defaults to the value of the + `format.encodeEmailHeaders` configuration variable. + +--interdiff=<previous>:: + As a reviewer aid, insert an interdiff into the cover letter, + or as commentary of the lone patch of a 1-patch series, showing + the differences between the previous version of the patch series and + the series currently being formatted. `previous` is a single revision + naming the tip of the previous series which shares a common base with + the series being formatted (for example `git format-patch + --cover-letter --interdiff=feature/v1 -3 feature/v2`). + +--range-diff=<previous>:: + As a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1]) + into the cover letter, or as commentary of the lone patch of a + 1-patch series, showing the differences between the previous + version of the patch series and the series currently being formatted. + `previous` can be a single revision naming the tip of the previous + series if it shares a common base with the series being formatted (for + example `git format-patch --cover-letter --range-diff=feature/v1 -3 + feature/v2`), or a revision range if the two versions of the series are + disjoint (for example `git format-patch --cover-letter + --range-diff=feature/v1~3..feature/v1 -3 feature/v2`). ++ +Note that diff options passed to the command affect how the primary +product of `format-patch` is generated, and they are not passed to +the underlying `range-diff` machinery used to generate the cover-letter +material (this may change in the future). + +--creation-factor=<percent>:: + Used with `--range-diff`, tweak the heuristic which matches up commits + between the previous and current series of patches by adjusting the + creation/deletion cost fudge factor. See linkgit:git-range-diff[1]) + for details. + --notes[=<ref>]:: +--no-notes:: Append the notes (see linkgit:git-notes[1]) for the commit after the three-dash line. + @@ -239,6 +305,9 @@ these explanations after `format-patch` has run but before sending, keeping them as Git notes allows them to be maintained between versions of the patch series (but see the discussion of the `notes.rewrite` configuration options in linkgit:git-notes[1] to use this workflow). ++ +The default is `--no-notes`, unless the `format.notes` configuration is +set. --[no-]signature=<signature>:: Add a signature to each message produced. Per RFC 3676 the signature @@ -272,10 +341,12 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. Output an all-zero hash in each patch's From header instead of the hash of the commit. ---base=<commit>:: +--[no-]base[=<commit>]:: Record the base tree information to identify the state the patch series applies to. See the BASE TREE INFORMATION section - below for details. + below for details. If <commit> is "auto", a base commit is + automatically chosen. The `--no-base` option overrides a + `format.useAutoBase` configuration. --root:: Treat the revision argument as a <revision range>, even if it @@ -291,8 +362,9 @@ CONFIGURATION ------------- You can specify extra mail header lines to be added to each message, defaults for the subject prefix and file suffix, number patches when -outputting more than one patch, add "To" or "Cc:" headers, configure -attachments, and sign off patches with configuration variables. +outputting more than one patch, add "To:" or "Cc:" headers, configure +attachments, change the patch output directory, and sign off patches +with configuration variables. ------------ [format] @@ -304,7 +376,9 @@ attachments, and sign off patches with configuration variables. cc = <email> attach [ = mime-boundary-string ] signOff = true - coverletter = auto + outputDirectory = <directory> + coverLetter = auto + coverFromDescription = auto ------------ @@ -387,8 +461,8 @@ One way to test if your MUA is set up correctly is: * Apply it: $ git fetch <project> master:test-apply - $ git checkout test-apply - $ git reset --hard + $ git switch test-apply + $ git restore --source=HEAD --staged --worktree :/ $ git am a.patch If it does not apply correctly, there can be various reasons. @@ -470,9 +544,9 @@ Toggle it to make sure it is set to `false`. Also, search for "mailnews.wraplength" and set the value to 0. 3. Disable the use of format=flowed: -Edit..Preferences..Advanced..Config Editor. Search for -"mailnews.send_plaintext_flowed". -Toggle it to make sure it is set to `false`. + Edit..Preferences..Advanced..Config Editor. Search for + "mailnews.send_plaintext_flowed". + Toggle it to make sure it is set to `false`. After that is done, you should be able to compose email as you otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), @@ -595,14 +669,14 @@ EXAMPLES -------- * Extract commits between revisions R1 and R2, and apply them on top of -the current branch using 'git am' to cherry-pick them: + the current branch using 'git am' to cherry-pick them: + ------------ $ git format-patch -k --stdout R1..R2 | git am -3 -k ------------ * Extract all commits which are in the current branch but not in the -origin branch: + origin branch: + ------------ $ git format-patch origin @@ -611,7 +685,7 @@ $ git format-patch origin For each commit a separate file is created in the current directory. * Extract all commits that lead to 'origin' since the inception of the -project: + project: + ------------ $ git format-patch --root origin @@ -630,7 +704,7 @@ Note that non-Git "patch" programs won't understand renaming patches, so use it only when you know the recipient uses Git to apply your patch. * Extract three topmost commits from the current branch and format them -as e-mailable patches: + as e-mailable patches: + ------------ $ git format-patch -3 diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index ab9a93fb9b..d72d15be5b 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -62,9 +62,17 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs with --no-full. --connectivity-only:: - Check only the connectivity of tags, commits and tree objects. By - avoiding to unpack blobs, this speeds up the operation, at the - expense of missing corrupt objects or other problematic issues. + 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 + 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 + in blob objects will not be detected at all. ++ +Unreachable tags, commits, and trees will also be accessed to find the +tips of dangling segments of history. Use `--no-dangling` if you don't +care about this output and want to speed it up further. --strict:: Enable more strict checking, namely to catch a file mode @@ -96,6 +104,11 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs progress status even if the standard error stream is not directed to a terminal. +CONFIGURATION +------------- + +include::config/fsck.txt[] + DISCUSSION ---------- @@ -140,9 +153,9 @@ dangling <type> <object>:: The <type> object <object>, is present in the database but never 'directly' used. A dangling commit could be a root node. -sha1 mismatch <object>:: - The database has an object who's sha1 doesn't match the - database value. +hash mismatch <object>:: + The database has an object whose hash doesn't match the + object database value. This indicates a serious data integrity problem. Environment Variables diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index f5bc98ccb3..0c114ad1ca 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -17,19 +17,19 @@ Runs a number of housekeeping tasks within the current repository, such as compressing file revisions (to reduce disk space and increase performance), removing unreachable objects which may have been created from prior invocations of 'git add', packing refs, pruning -reflog, rerere metadata or stale working trees. +reflog, rerere metadata or stale working trees. May also update ancillary +indexes such as the commit-graph. -Users are encouraged to run this task on a regular basis within -each repository to maintain good disk space utilization and good -operating performance. +When common porcelain operations that create objects are run, they +will check whether the repository has grown substantially since the +last maintenance, and if so run `git gc` automatically. See `gc.auto` +below for how to disable this behavior. -Some git commands may automatically run 'git gc'; see the `--auto` flag -below for details. If you know what you're doing and all you want is to -disable this behavior permanently without further considerations, just do: - ----------------------- -$ git config --global gc.auto 0 ----------------------- +Running `git gc` manually should only be needed when adding objects to +a repository without regularly running such porcelain commands, to do +a one-off repository optimization, or e.g. to clean up a suboptimal +mass-import. See the "PACKFILE OPTIMIZATION" section in +linkgit:git-fast-import[1] for more details on the import case. OPTIONS ------- @@ -39,35 +39,17 @@ OPTIONS space utilization and performance. This option will cause 'git gc' to more aggressively optimize the repository at the expense of taking much more time. The effects of this optimization are - persistent, so this option only needs to be used occasionally; every - few hundred changesets or so. + mostly persistent. See the "AGGRESSIVE" section below for details. --auto:: With this option, 'git gc' checks whether any housekeeping is required; if not, it exits without performing any work. - Some git commands run `git gc --auto` after performing - operations that could create many loose objects. Housekeeping - is required if there are too many loose objects or too many - packs in the repository. -+ -If the number of loose objects exceeds the value of the `gc.auto` -configuration variable, then all loose objects are combined into a -single pack using `git repack -d -l`. Setting the value of `gc.auto` -to 0 disables automatic packing of loose objects. + -If the number of packs exceeds the value of `gc.autoPackLimit`, -then existing packs (except those marked with a `.keep` file -or over `gc.bigPackThreshold` limit) -are consolidated into a single pack by using the `-A` option of -'git repack'. -If the amount of memory is estimated not enough for `git repack` to -run smoothly and `gc.bigPackThreshold` is not set, the largest -pack will also be excluded (this is the equivalent of running `git gc` -with `--keep-base-pack`). -Setting `gc.autoPackLimit` to 0 disables automatic consolidation of -packs. +See the `gc.auto` option in the "CONFIGURATION" section below for how +this heuristic works. + -If houskeeping is required due to many loose objects or packs, all +Once housekeeping is triggered by exceeding the limits of +configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. @@ -75,7 +57,7 @@ be performed as well. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, overridable by the config variable `gc.pruneExpire`). - --prune=all prunes loose objects regardless of their age and + --prune=now prunes loose objects regardless of their age and increases the risk of corruption if another process is writing to the repository concurrently; see "NOTES" below. --prune is on by default. @@ -95,83 +77,52 @@ be performed as well. `.keep` files are consolidated into a single pack. When this option is used, `gc.bigPackThreshold` is ignored. +AGGRESSIVE +---------- + +When the `--aggressive` option is supplied, linkgit:git-repack[1] will +be invoked with the `-f` flag, which in turn will pass +`--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw +away any existing deltas and re-compute them, at the expense of +spending much more time on the repacking. + +The effects of this are mostly persistent, e.g. when packs and loose +objects are coalesced into one another pack the existing deltas in +that pack might get re-used, but there are also various cases where we +might pick a sub-optimal delta from a newer pack instead. + +Furthermore, supplying `--aggressive` will tweak the `--depth` and +`--window` options passed to linkgit:git-repack[1]. See the +`gc.aggressiveDepth` and `gc.aggressiveWindow` settings below. By +using a larger window size we're more likely to find more optimal +deltas. + +It's probably not worth it to use this option on a given repository +without running tailored performance benchmarks on it. It takes a lot +more time, and the resulting space/delta optimization may or may not +be worth it. Not using this at all is the right trade-off for most +users and their repositories. + CONFIGURATION ------------- -The optional configuration variable `gc.reflogExpire` can be -set to indicate how long historical entries within each branch's -reflog should remain available in this repository. The setting is -expressed as a length of time, for example '90 days' or '3 months'. -It defaults to '90 days'. - -The optional configuration variable `gc.reflogExpireUnreachable` -can be set to indicate how long historical reflog entries which -are not part of the current branch should remain available in -this repository. These types of entries are generally created as -a result of using `git commit --amend` or `git rebase` and are the -commits prior to the amend or rebase occurring. Since these changes -are not part of the current project most users will want to expire -them sooner. This option defaults to '30 days'. - -The above two configuration variables can be given to a pattern. For -example, this sets non-default expiry values only to remote-tracking -branches: - ------------- -[gc "refs/remotes/*"] - reflogExpire = never - reflogExpireUnreachable = 3 days ------------- - -The optional configuration variable `gc.rerereResolved` indicates -how long records of conflicted merge you resolved earlier are -kept. This defaults to 60 days. - -The optional configuration variable `gc.rerereUnresolved` indicates -how long records of conflicted merge you have not resolved are -kept. This defaults to 15 days. - -The optional configuration variable `gc.packRefs` determines if -'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable -it within all non-bare repos or it can be set to a boolean value. -This defaults to true. - -The optional configuration variable `gc.commitGraph` determines if -'git gc' should run 'git commit-graph write'. This can be set to a -boolean value. This defaults to false. - -The optional configuration variable `gc.aggressiveWindow` controls how -much time is spent optimizing the delta compression of the objects in -the repository when the --aggressive option is specified. The larger -the value, the more time is spent optimizing the delta compression. See -the documentation for the --window option in linkgit:git-repack[1] for -more details. This defaults to 250. - -Similarly, the optional configuration variable `gc.aggressiveDepth` -controls --depth option in linkgit:git-repack[1]. This defaults to 50. - -The optional configuration variable `gc.pruneExpire` controls how old -the unreferenced loose objects have to be before they are pruned. The -default is "2 weeks ago". - -Optional configuration variable `gc.worktreePruneExpire` controls how -old a stale working tree should be before `git worktree prune` deletes -it. Default is "3 months ago". +The below documentation is the same as what's found in +linkgit:git-config[1]: +include::config/gc.txt[] NOTES ----- 'git gc' tries very hard not to delete objects that are referenced -anywhere in your repository. In -particular, it will keep not only objects referenced by your current set -of branches and tags, but also objects referenced by the index, -remote-tracking branches, refs saved by 'git filter-branch' in -refs/original/, or reflogs (which may reference commits in branches -that were later amended or rewound). -If you are expecting some objects to be deleted and they aren't, check -all of those locations and decide whether it makes sense in your case to -remove those references. +anywhere in your repository. In particular, it will keep not only +objects referenced by your current set of branches and tags, but also +objects referenced by the index, remote-tracking branches, notes saved +by 'git notes' under refs/notes/, reflogs (which may reference commits +in branches that were later amended or rewound), and anything else in +the refs/* namespace. If you are expecting some objects to be deleted +and they aren't, check all of those locations and decide whether it +makes sense in your case to remove those references. On the other hand, when 'git gc' runs concurrently with another process, there is a risk of it deleting an object that the other process is using @@ -189,8 +140,7 @@ mitigate this problem: However, these features fall short of a complete solution, so users who run commands concurrently have to live with some risk of corruption (which -seems to be low in practice) unless they turn off automatic garbage -collection with 'git config gc.auto 0'. +seems to be low in practice). HOOKS ----- diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index a3049af1a3..a7f9bc99ea 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -18,7 +18,7 @@ SYNOPSIS [(-O | --open-files-in-pager) [<pager>]] [-z | --null] [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet] - [--max-depth <depth>] + [--max-depth <depth>] [--[no-]recursive] [--color[=<when>] | --no-color] [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] @@ -59,8 +59,8 @@ grep.extendedRegexp:: other than 'default'. grep.threads:: - Number of grep worker threads to use. If unset (or set to 0), - 8 threads are used by default (for now). + 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. @@ -88,15 +88,16 @@ OPTIONS mechanism. Only useful with `--untracked`. --exclude-standard:: - Do not pay attention to ignored files specified via the `.gitignore` + Do not pay attention to ignored files specified via the `.gitignore` mechanism. Only useful when searching files in the current directory with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + 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. + the parent project's <tree> object. This option has no effect + if `--no-index` is given. -a:: --text:: @@ -119,11 +120,18 @@ OPTIONS --max-depth <depth>:: For each <pathspec> given on command line, descend at most <depth> - levels of directories. A negative value means no limit. + levels of directories. A value of -1 means no limit. This option is ignored if <pathspec> contains active wildcards. In other words if "a*" matches a directory named "a*", "*" is matched literally so --max-depth is still effective. +-r:: +--recursive:: + Same as `--max-depth=-1`; this is the default. + +--no-recursive:: + Same as `--max-depth=0`. + -w:: --word-regexp:: Match the pattern only at word boundary (either begin at the @@ -198,8 +206,10 @@ providing this option will cause it to die. -z:: --null:: - Output \0 instead of the character that normally follows a - file name. + 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 git-config(1)). -o:: --only-matching:: @@ -264,6 +274,23 @@ providing this option will cause it to die. -f <file>:: Read patterns from <file>, one per line. ++ +Passing the pattern via <file> allows for providing a search pattern +containing a \0. ++ +Not all pattern types support patterns containing \0. Git will error +out if a given pattern type can't support such a pattern. The +`--perl-regexp` pattern type when compiled against the PCRE v2 backend +has the widest support for these types of patterns. ++ +In versions of Git before 2.23.0 patterns containing \0 would be +silently considered fixed. This was never documented, there were also +odd and undocumented interactions between e.g. non-ASCII patterns +containing \0 and `--ignore-case`. ++ +In future versions we may learn to support patterns containing \0 for +more search backends, until then we'll die when the pattern type in +question doesn't support them. -e:: The next parameter is the pattern. This option has to be @@ -323,6 +350,17 @@ EXAMPLES `git grep solution -- :^Documentation`:: Looks for `solution`, excluding files in `Documentation`. +NOTES ON THREADS +---------------- + +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`. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index 5f93f8003d..c9d7e96214 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -112,15 +112,9 @@ Other versions are distributed as part of the Git suite for the convenience of end users. -A 'git gui' development repository can be obtained from: +The official repository of the 'git gui' project can be found at: - git clone git://repo.or.cz/git-gui.git - -or - - git clone http://repo.or.cz/r/git-gui.git - -or browsed online at http://repo.or.cz/w/git-gui.git/[]. + https://github.com/prati0100/git-gui.git/ GIT --- diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 814e74406a..df9e2c58bd 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -18,9 +18,7 @@ Computes the object ID value for an object with specified type with the contents of the named file (which can be outside of the work tree), and optionally writes the resulting object into the object database. Reports its object ID to its standard output. -This is used by 'git cvsimport' to update the index -without modifying files in the work tree. When <type> is not -specified, it defaults to "blob". +When <type> is not specified, it defaults to "blob". OPTIONS ------- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 83d25d825a..f71db0daa2 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,7 +8,7 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all [--verbose]] [-g|--guide] +'git help' [-a|--all [--[no-]verbose]] [-g|--guide] [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE] DESCRIPTION @@ -29,6 +29,10 @@ guide is 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`. + Note that `git --help ...` is identical to `git help ...` because the former is internally converted into the latter. @@ -42,8 +46,10 @@ OPTIONS --all:: Prints all the available commands on the standard output. This option overrides any given command or guide name. - When used with `--verbose` print description for all recognized - commands. + +--verbose:: + When used with `--all` print description for all recognized + commands. This is the default. -c:: --config:: @@ -112,9 +118,9 @@ format is chosen. The following values are currently supported: * "man": use the 'man' program as usual, * "woman": use 'emacsclient' to launch the "woman" mode in emacs -(this only works starting with emacsclient versions 22), + (this only works starting with emacsclient versions 22), * "konqueror": use 'kfmclient' to open the man page in a new konqueror -tab (see 'Note about konqueror' below). + tab (see 'Note about konqueror' below). Values for other tools can be used if there is a corresponding `man.<tool>.cmd` configuration entry (see below). @@ -165,8 +171,8 @@ variable, we launch 'kfmclient' to try to open the man page on an already opened konqueror in a new tab if possible. For consistency, we also try such a trick if 'man.konqueror.path' is -set to something like 'A_PATH_TO/konqueror'. That means we will try to -launch 'A_PATH_TO/kfmclient' instead. +set to something like `A_PATH_TO/konqueror`. That means we will try to +launch `A_PATH_TO/kfmclient` instead. If you really want to use 'konqueror', then you can use something like the following: diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index bb0db195ce..558966aa83 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -162,7 +162,7 @@ ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage. Accelerated static Apache 2.x:: Similar to the above, but Apache can be used to return static - files that are stored on disk. On many systems this may + files that are stored on disk. On many systems this may be more efficient as Apache can ask the kernel to copy the file contents from the file system directly to the network: + diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 7b157441eb..65b53fcc47 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -57,50 +57,7 @@ to appropriate values. Variables ~~~~~~~~~ -imap.folder:: - The folder to drop the mails into, which is typically the Drafts - folder. For example: "INBOX.Drafts", "INBOX/Drafts" or - "[Gmail]/Drafts". Required. - -imap.tunnel:: - Command used to setup 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. - -imap.host:: - A URL identifying the server. Use an `imap://` prefix for non-secure - connections and an `imaps://` prefix for secure connections. - Ignored when imap.tunnel is set, but required otherwise. - -imap.user:: - The username to use when logging in to the server. - -imap.pass:: - The password to use when logging in to the server. - -imap.port:: - An integer port number to connect to on the server. - Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. - Ignored when imap.tunnel is set. - -imap.sslverify:: - A boolean to enable/disable verification of the server certificate - used by the SSL/TLS connection. Default is `true`. Ignored when - imap.tunnel is set. - -imap.preformattedHTML:: - A boolean to enable/disable the use of html encoding when sending - a patch. An html encoded patch will be bracketed with <pre> - and have a content type of text/html. Ironically, enabling this - option causes Thunderbird to send the patch as a plain/text, - format=fixed email. Default is `false`. - -imap.authMethod:: - Specify authenticate method for authentication with 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 - then 'git imap-send' uses the basic IMAP plaintext LOGIN command. +include::config/imap.txt[] Examples ~~~~~~~~ diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 3c5a67fb96..adc6adfd38 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git init' [-q | --quiet] [--bare] [--template=<template_directory>] - [--separate-git-dir <git dir>] + [--separate-git-dir <git dir>] [--object-format=<format] [--shared[=<permissions>]] [directory] @@ -38,8 +38,6 @@ the repository to another place if --separate-git-dir is given). OPTIONS ------- --- - -q:: --quiet:: @@ -50,6 +48,11 @@ Only print error and warning messages; all other output will be suppressed. Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. +--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. + --template=<template_directory>:: Specify the directory from which templates will be used. (See the "TEMPLATE @@ -111,8 +114,6 @@ into it. If you provide a 'directory', the command is run inside it. If this directory does not exist, it will be created. --- - TEMPLATE DIRECTORY ------------------ @@ -132,7 +133,7 @@ The template directory will be one of the following (in order): The default template directory includes some directory structure, suggested "exclude patterns" (see linkgit:gitignore[5]), and sample hook files. -The sample hooks are all disabled by default, To enable one of the +The sample hooks are all disabled by default. To enable one of the sample hooks rename it by removing its `.sample` suffix. See linkgit:githooks[5] for more general info on hook execution. diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index e8ecdbf927..a54fe4401b 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -29,7 +29,8 @@ OPTIONS The HTTP daemon command-line that will be executed. Command-line options may be specified here, and the configuration file will be added at the end of the command-line. - Currently apache2, lighttpd, mongoose, plackup and webrick are supported. + Currently apache2, lighttpd, mongoose, plackup, python and + webrick are supported. (Default: lighttpd) -m:: diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index b8fafb1e8b..96ec6499f0 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -3,7 +3,7 @@ git-interpret-trailers(1) NAME ---- -git-interpret-trailers - add or parse structured information in commit messages +git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- @@ -56,8 +56,9 @@ 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 -non-whitespace lines before a line that starts with '---'. Such three -minus signs start the patch part of the message. +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. When reading trailers, there can be whitespaces after the token, the separator and the value. There can also be whitespaces @@ -125,6 +126,11 @@ OPTIONS A convenience alias for `--only-trailers --only-input --unfold`. +--no-divider:: + Do not treat `---` as the end of the commit message. Use this + when you know your input contains just the commit message itself + (and not an email or the output of `git format-patch`). + CONFIGURATION VARIABLES ----------------------- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 90761f1694..20e6d21a74 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -43,13 +43,17 @@ OPTIONS If no `--decorate-refs` is given, pretend as if all refs were included. For each candidate, 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`. + 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`. --source:: Print out the ref name given on the command line by which each commit was reached. ---use-mailmap:: +--[no-]mailmap:: +--[no-]use-mailmap:: Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. See linkgit:git-shortlog[1]. @@ -76,8 +80,12 @@ produced by `--stat`, etc. (or the function name regex <funcname>) within the <file>. You may not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only - give zero or one positive revision arguments. - You can specify this option more than once. + give zero or one positive revision arguments, and + <start> and <end> (or <funcname>) must exist in the starting revision. + You can specify this option more than once. Implies `--patch`. + Patch output can be suppressed using `--no-patch`, but other diff formats + (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`, + `--name-only`, `--name-status`, `--check`) are not currently implemented. + include::line-range-format.txt[] @@ -192,6 +200,10 @@ 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 diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 5298f1bc30..3cb2ebb438 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -118,6 +118,7 @@ OPTIONS 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: @@ -128,6 +129,7 @@ a space) at the start of each line: C:: modified/changed K:: to be killed ?:: other +-- -v:: Similar to `-t`, but use lowercase letters for files @@ -146,7 +148,7 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. + Recursively calls ls-files on each active submodule in the repository. Currently there is only support for the --cached mode. --abbrev[=<n>]:: diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index b9fd3770a6..0a5c8b7d49 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -28,10 +28,12 @@ OPTIONS Limit to only refs/heads and refs/tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. + displayed. Note that `git ls-remote -h` used without + anything else on the command line gives help, consistent + with other git subcommands. --refs:: - Do not show peeled tags or pseudorefs like HEAD in the output. + Do not show peeled tags or pseudorefs like `HEAD` in the output. -q:: --quiet:: @@ -92,21 +94,23 @@ OPTIONS EXAMPLES -------- - $ 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 pu rc - 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master - c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu - $ 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 +---- +$ 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 pu rc +5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master +c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu +$ 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 +---- SEE ALSO -------- diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 9dee7bef35..a7515714da 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -27,9 +27,9 @@ in the current working directory. Note that: taken as relative to the current working directory. E.g. when you are in a directory 'sub' that has a directory 'dir', you can run 'git ls-tree -r HEAD dir' to list the contents of the tree (that is - 'sub/dir' in `HEAD`). You don't want to give a tree that is not at the + `sub/dir` in `HEAD`). You don't want to give a tree that is not at the root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that - would result in asking for 'sub/sub/dir' in the `HEAD` commit. + would result in asking for `sub/sub/dir` in the `HEAD` commit. However, the current working directory can be ignored by passing --full-tree option. diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 502e00ec35..2d944e0851 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -80,9 +80,11 @@ which is reachable from both 'A' and 'B' through the parent relationship. For example, with this topology: - o---o---o---B - / - ---o---1---o---o---o---A +.... + o---o---o---B + / +---o---1---o---o---o---A +.... the merge base between 'A' and 'B' is '1'. @@ -90,21 +92,25 @@ 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: - o---o---o---o---C - / - / o---o---o---B - / / - ---2---1---o---o---o---A +.... + o---o---o---o---C + / + / o---o---o---B + / / +---2---1---o---o---o---A +.... the result of `git merge-base A B C` is '1'. This is because the equivalent topology with a merge commit 'M' between 'B' and 'C' is: - o---o---o---o---o - / \ - / o---o---o---o---M - / / - ---2---1---o---o---o---A +.... + o---o---o---o---o + / \ + / o---o---o---o---M + / / +---2---1---o---o---o---A +.... and the result of `git merge-base A M` is '1'. Commit '2' is also a common ancestor between 'A' and 'M', but '1' is a better common ancestor, @@ -116,11 +122,13 @@ the best common ancestor of all commits. When the history involves criss-cross merges, there can be more than one 'best' common ancestor for two commits. For example, with this topology: - ---1---o---A - \ / - X - / \ - ---2---o---o---B +.... +---1---o---A + \ / + X + / \ +---2---o---o---B +.... 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, @@ -131,36 +139,42 @@ and B is (or at least used to be) to compute the merge base between A and B, and check if it is the same as A, in which case, A is an ancestor of B. You will see this idiom used often in older scripts. - A=$(git rev-parse --verify A) - if test "$A" = "$(git merge-base A B)" - then - ... A is an ancestor of B ... - fi +.... +A=$(git rev-parse --verify A) +if test "$A" = "$(git merge-base A B)" +then + ... A is an ancestor of B ... +fi +.... In modern git, you can say this in a more direct way: - if git merge-base --is-ancestor A B - then - ... A is an ancestor of B ... - fi +.... +if git merge-base --is-ancestor A B +then + ... A is an ancestor of B ... +fi +.... instead. Discussion on fork-point mode ----------------------------- -After working on the `topic` branch created with `git checkout -b +After working on the `topic` branch created with `git switch -c topic origin/master`, the history of remote-tracking branch `origin/master` may have been rewound and rebuilt, leading to a history of this shape: - o---B2 - / - ---o---o---B1--o---o---o---B (origin/master) - \ - B0 - \ - D0---D1---D (topic) +.... + o---B2 + / +---o---o---B1--o---o---o---B (origin/master) + \ + B0 + \ + D0---D1---D (topic) +.... where `origin/master` used to point at commits B0, B1, B2 and now it points at B, and your `topic` branch was started on top of it back @@ -193,13 +207,15 @@ will find B0, and will replay D0, D1 and D on top of B to create a new history of this shape: - o---B2 - / - ---o---o---B1--o---o---o---B (origin/master) - \ \ - B0 D0'--D1'--D' (topic - updated) - \ - D0---D1---D (topic - old) +.... + o---B2 + / +---o---o---B1--o---o---o---B (origin/master) + \ \ + B0 D0'--D1'--D' (topic - updated) + \ + D0---D1---D (topic - old) +.... A caveat is that older reflog entries in your repository may be expired by `git gc`. If B0 no longer appears in the reflog of the diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 02676fb391..2ab84a91e5 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -54,20 +54,24 @@ original is first. But the argument order to the 3-way merge program Examples: - torvalds@ppc970:~/merge-test> git merge-index cat MM - This is MM from the original tree. # original - This is modified MM in the branch A. # merge1 - This is modified MM in the branch B. # merge2 - This is modified MM in the branch B. # current contents +---- +torvalds@ppc970:~/merge-test> git merge-index cat MM +This is MM from the original tree. # original +This is modified MM in the branch A. # merge1 +This is modified MM in the branch B. # merge2 +This is modified MM in the branch B. # current contents +---- or - torvalds@ppc970:~/merge-test> git merge-index cat AA MM - cat: : No such file or directory - This is added AA in the branch A. - This is added AA in the branch B. - This is added AA in the branch B. - fatal: merge program failed +---- +torvalds@ppc970:~/merge-test> git merge-index cat AA MM +cat: : No such file or directory +This is added AA in the branch A. +This is added AA in the branch B. +This is added AA in the branch B. +fatal: merge program failed +---- where the latter example shows how 'git merge-index' will stop trying to merge once anything has returned an error (i.e., `cat` returned an error diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index eb36837f86..3819fadac1 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -10,11 +10,10 @@ SYNOPSIS -------- [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] - [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] + [--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...] -'git merge' --abort -'git merge' --continue +'git merge' (--continue | --abort | --quit) DESCRIPTION ----------- @@ -83,13 +82,20 @@ 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. ---[no-]rerere-autoupdate:: +--rerere-autoupdate:: +--no-rerere-autoupdate:: Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--overwrite-ignore:: +--no-overwrite-ignore:: + Silently overwrite ignored files from the merge result. This + is the default behavior. Use `--no-overwrite-ignore` to abort. + --abort:: Abort the current conflict resolution process, and - try to reconstruct the pre-merge state. + try to reconstruct the pre-merge state. If an autostash entry is + 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 @@ -97,7 +103,15 @@ reconstruct these changes. It is therefore recommended to always commit or stash your changes before running 'git merge'. + 'git merge --abort' is equivalent to 'git reset --merge' when -`MERGE_HEAD` is present. +`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 +list. + +--quit:: + Forget about the current merge in progress. Leave the index + and the working tree as-is. If `MERGE_AUTOSTASH` is present, the + stash entry will be saved to the stash list. --continue:: After a 'git merge' stops due to conflicts you can conclude the @@ -342,7 +356,7 @@ include::merge-strategies.txt[] CONFIGURATION ------------- -include::merge-config.txt[] +include::config/merge.txt[] branch.<name>.mergeOptions:: Sets default options for merging into branch <name>. The syntax and diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 055550b2bc..4da9d24096 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -28,7 +28,9 @@ to define the operation mode for the functions listed below. FUNCTIONS --------- get_merge_tool:: - returns a merge tool. + 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. diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 3622d66488..6b14702e78 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -79,6 +79,19 @@ success of the resolution after the custom tool has exited. Prompt before each invocation of the merge resolution program to give the user a chance to skip the path. +-g:: +--gui:: + 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`. + +--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. + -O<orderfile>:: Process files in the order specified in the <orderfile>, which has one shell glob pattern per line. diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index f7778a2c85..0c6619493c 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -9,7 +9,7 @@ git-multi-pack-index - Write and verify multi-pack-indexes SYNOPSIS -------- [verse] -'git multi-pack-index' [--object-dir=<dir>] <verb> +'git multi-pack-index' [--object-dir=<dir>] [--[no-]progress] <subcommand> DESCRIPTION ----------- @@ -23,13 +23,42 @@ OPTIONS `<dir>/packs/multi-pack-index` for the current MIDX file, and `<dir>/packs` for the pack-files to index. +--[no-]progress:: + Turn progress on/off explicitly. If neither is specified, progress is + shown if standard error is connected to a terminal. + +The following subcommands are available: + write:: - When given as the verb, write a new MIDX file to - `<dir>/packs/multi-pack-index`. + Write a new MIDX file. verify:: - When given as the verb, verify the contents of the MIDX file - at `<dir>/packs/multi-pack-index`. + 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. + +repack:: + Create a new pack-file containing objects in small pack-files + referenced by the multi-pack-index. If the size given by the + `--batch-size=<size>` argument is zero, then create a pack + containing all objects referenced by the multi-pack-index. For + a non-zero batch size, Select the pack-files by examining packs + from oldest-to-newest, computing the "expected size" by counting + the number of objects in the pack referenced by the + multi-pack-index, then divide by the total number of objects in + the pack and multiply by the pack size. We select packs with + expected size below the batch size until the set of packs have + total expected size at least the batch size. If the total size + does not reach the batch size, then do nothing. If a new pack- + file is created, rewrite the multi-pack-index to reference the + new pack-file. A later run of 'git multi-pack-index expire' will + delete the pack-files that were part of this batch. ++ +If `repack.packKeptObjects` is `false`, then any pack-files with an +associated `.keep` file will not be selected for the batch to repack. EXAMPLES diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index df2b64dbb6..ced2e8280e 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git notes' [list [<object>]] 'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] -'git notes' copy [-f] ( --stdin | <from-object> <to-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' show [<object>] @@ -68,8 +68,8 @@ add:: subcommand). copy:: - Copy the notes for the first object onto the second object. - Abort if the second object already has notes, or if the first + Copy the notes for the first object onto the second object (defaults to + HEAD). Abort if the second object already has notes, or if the first object has none (use -f to overwrite existing notes to the second object). This subcommand is equivalent to: `git notes add [-f] -C $(git notes list <from-object>) <to-object>` @@ -146,7 +146,7 @@ OPTIONS -C <object>:: --reuse-message=<object>:: - Take the given blob object (for example, another note) as the + Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to copy notes between objects.) diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 41780a5aa9..dab9609013 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -71,12 +71,12 @@ $ git p4 clone //depot/path/project ------------ This: -1. Creates an empty Git repository in a subdirectory called 'project'. +1. Creates an empty Git repository in a subdirectory called 'project'. + -2. Imports the full contents of the head revision from the given p4 -depot path into a single commit in the Git branch 'refs/remotes/p4/master'. +2. Imports the full contents of the head revision from the given p4 + depot path into a single commit in the Git branch 'refs/remotes/p4/master'. + -3. Creates a local branch, 'master' from this remote and checks it out. +3. Creates a local branch, 'master' from this remote and checks it out. To reproduce the entire p4 history in Git, use the '@all' modifier on the depot path: @@ -174,21 +174,21 @@ $ git p4 submit --update-shelve 1234 --update-shelve 2345 Unshelve ~~~~~~~~ Unshelving will take a shelved P4 changelist, and produce the equivalent git commit -in the branch refs/remotes/p4/unshelved/<changelist>. +in the branch refs/remotes/p4-unshelved/<changelist>. The git commit is created relative to the current origin revision (HEAD by default). -If the shelved changelist's parent revisions differ, git-p4 will refuse to unshelve; -you need to be unshelving onto an equivalent tree. +A parent commit is created based on the origin, and then the unshelve commit is +created based on that. The origin revision can be changed with the "--origin" option. -If the target branch in refs/remotes/p4/unshelved already exists, the old one will +If the target branch in refs/remotes/p4-unshelved already exists, the old one will be renamed. ---- $ git p4 sync $ git p4 unshelve 12345 -$ git show refs/remotes/p4/unshelved/12345 +$ git show p4-unshelved/12345 <submit more changes via p4 to the same files> $ git p4 unshelve 12345 <refuses to unshelve until git is in sync with p4 again> @@ -374,14 +374,55 @@ These options can be used to modify 'git p4 submit' behavior. been submitted. Implies --disable-rebase. Can also be set with git-p4.disableP4Sync. Sync with origin/master still goes ahead if possible. -Hook for submit -~~~~~~~~~~~~~~~ +Hooks for submit +---------------- + +p4-pre-submit +~~~~~~~~~~~~~ + The `p4-pre-submit` hook is executed if it exists and is executable. The hook takes no parameters and nothing from standard input. Exiting with non-zero status from this script prevents `git-p4 submit` from launching. +It can be bypassed with the `--no-verify` command line option. One usage scenario is to run unit tests in the hook. +p4-prepare-changelist +~~~~~~~~~~~~~~~~~~~~~ + +The `p4-prepare-changelist` hook is executed right after preparing +the default changelist message and before the editor is started. +It takes one parameter, the name of the file that contains the +changelist text. Exiting with a non-zero status from the script +will abort the process. + +The purpose of the hook is to edit the message file in place, +and it is not supressed by the `--no-verify` option. This hook +is called even if `--prepare-p4-only` is set. + +p4-changelist +~~~~~~~~~~~~~ + +The `p4-changelist` hook is executed after the changelist +message has been edited by the user. It can be bypassed with the +`--no-verify` option. It takes a single parameter, the name +of the file that holds the proposed changelist text. Exiting +with a non-zero status causes the command to abort. + +The hook is allowed to edit the changelist file and can be used +to normalize the text into some project standard format. It can +also be used to refuse the Submit after inspect the message file. + +p4-post-changelist +~~~~~~~~~~~~~~~~~~ + +The `p4-post-changelist` hook is invoked after the submit has +successfully occured in P4. It takes no parameters and is meant +primarily for notification and cannot affect the outcome of the +git p4 submit action. + + + Rebase options ~~~~~~~~~~~~~~ These options can be used to modify 'git p4 rebase' behavior. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index d95b472d16..eaa2f2a404 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -14,7 +14,7 @@ SYNOPSIS [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] < object-list + [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list DESCRIPTION @@ -131,7 +131,7 @@ depth is 4095. --keep-pack=<pack-name>:: This flag causes an object already in the given pack to be ignored, even if it would have otherwise been - packed. `<pack-name>` is the the pack file name without + packed. `<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 packs. @@ -196,6 +196,17 @@ depth is 4095. Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. +--[no-]sparse:: + Toggle the "sparse" algorithm to determine which objects to include in + the pack, when combined with the "--revs" option. This algorithm + only walks trees that appear in paths that introduce new objects. + This can have significant performance benefits when computing + a pack to send a small change. However, it is possible that extra + objects are added to the pack-file if the included commits contain + certain types of direct renames. If this option is not included, + it defaults to the value of `pack.useSparse`, which is true unless + otherwise specified. + --thin:: Create a "thin" pack by omitting the common objects between a sender and a receiver in order to reduce network transfer. This @@ -289,6 +300,103 @@ Unexpected missing object will raise an error. --unpack-unreachable:: Keep unreachable objects in loose form. This implies `--revs`. +--delta-islands:: + Restrict delta matches based on "islands". See DELTA ISLANDS + below. + + +DELTA ISLANDS +------------- + +When possible, `pack-objects` tries to reuse existing on-disk deltas to +avoid having to search for new ones on the fly. This is an important +optimization for serving fetches, because it means the server can avoid +inflating most objects at all and just send the bytes directly from +disk. This optimization can't work when an object is stored as a delta +against a base which the receiver does not have (and which we are not +already sending). In that case the server "breaks" the delta and has to +find a new one, which has a high CPU cost. Therefore it's important for +performance that the set of objects in on-disk delta relationships match +what a client would fetch. + +In a normal repository, this tends to work automatically. The objects +are mostly reachable from the branches and tags, and that's what clients +fetch. Any deltas we find on the server are likely to be between objects +the client has or will have. + +But in some repository setups, you may have several related but separate +groups of ref tips, with clients tending to fetch those groups +independently. For example, imagine that you are hosting several "forks" +of a repository in a single shared object store, and letting clients +view them as separate repositories through `GIT_NAMESPACE` or separate +repos using the alternates mechanism. A naive repack may find that the +optimal delta for an object is against a base that is only found in +another fork. But when a client fetches, they will not have the base +object, and we'll have to find a new delta on the fly. + +A similar situation may exist if you have many refs outside of +`refs/heads/` and `refs/tags/` that point to related objects (e.g., +`refs/pull` or `refs/changes` used by some hosting providers). By +default, clients fetch only heads and tags, and deltas against objects +found only in those other groups cannot be sent as-is. + +Delta islands solve this problem by allowing you to group your refs into +distinct "islands". Pack-objects computes which objects are reachable +from which islands, and refuses to make a delta from an object `A` +against a base which is not present in all of `A`'s islands. This +results in slightly larger packs (because we miss some delta +opportunities), but guarantees that a fetch of one island will not have +to recompute deltas on the fly due to crossing island boundaries. + +When repacking with delta islands the delta window tends to get +clogged with candidates that are forbidden by the config. Repacking +with a big --window helps (and doesn't take as long as it otherwise +might because we can reject some object pairs based on islands before +doing any computation on the content). + +Islands are configured via the `pack.island` option, which can be +specified multiple times. Each value is a left-anchored regular +expressions matching refnames. For example: + +------------------------------------------- +[pack] +island = refs/heads/ +island = refs/tags/ +------------------------------------------- + +puts heads and tags into an island (whose name is the empty string; see +below for more on naming). Any refs which do not match those regular +expressions (e.g., `refs/pull/123`) is not in any island. Any object +which is reachable only from `refs/pull/` (but not heads or tags) is +therefore not a candidate to be used as a base for `refs/heads/`. + +Refs are grouped into islands based on their "names", and two regexes +that produce the same name are considered to be in the same +island. The names are computed from the regexes by concatenating any +capture groups from the regex, with a '-' dash in between. (And if +there are no capture groups, then the name is the empty string, as in +the above example.) This allows you to create arbitrary numbers of +islands. Only up to 14 such capture groups are supported though. + +For example, imagine you store the refs for each fork in +`refs/virtual/ID`, where `ID` is a numeric identifier. You might then +configure: + +------------------------------------------- +[pack] +island = refs/virtual/([0-9]+)/heads/ +island = refs/virtual/([0-9]+)/tags/ +island = refs/virtual/([0-9]+)/(pull)/ +------------------------------------------- + +That puts the heads and tags for each fork in their own island (named +"1234" or similar), and the pull refs for each go into their own +"1234-pull". + +Note that we pick a single island for each regex to go into, using "last +one wins" ordering (which allows repo-specific config to take precedence +over user-wide config, and so forth). + SEE ALSO -------- linkgit:git-rev-list[1] diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 118d9d86f7..5c3fb67c01 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,8 +85,9 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[no-]recurse-submodules[=yes|on-demand|no]:: - This option controls if new commits of all populated submodules should - be fetched and updated, too (see linkgit:git-config[1] and + 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 linkgit:gitmodules[5]). + If the checkout is done via rebase, local submodule commits are rebased as well. @@ -112,8 +113,9 @@ 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, rebase with the `--preserve-merges` option passed -to `git rebase` so that locally created merge commits will not be flattened. +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. + @@ -132,15 +134,6 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: Override earlier --rebase. ---autostash:: ---no-autostash:: - Before starting rebase, stash local modifications away (see - linkgit:git-stash[1]) if needed, and apply the stash entry when - done. `--no-autostash` is useful to override the `rebase.autoStash` - configuration variable (see linkgit:git-config[1]). -+ -This option is only valid when "--rebase" is used. - Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -228,9 +221,9 @@ branch.<name>.merge options; see linkgit:git-config[1] for details. $ git pull origin next ------------------------------------------------ + -This leaves a copy of `next` temporarily in FETCH_HEAD, but -does not update any remote-tracking branches. Using remote-tracking -branches, the same can be done by invoking fetch and merge: +This leaves a copy of `next` temporarily in FETCH_HEAD, and +updates the remote-tracking branch `origin/next`. +The same can be done by invoking fetch and merge: + ------------------------------------------------ $ git fetch origin @@ -248,7 +241,7 @@ 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 can not be +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. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 55277a9781..3b8053447e 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -73,23 +73,78 @@ be omitted--such a push will update a ref that `<src>` normally updates without any `<refspec>` on the command line. Otherwise, missing `:<dst>` means to update the same ref as the `<src>`. + -The object referenced by <src> is used to update the <dst> reference -on the remote side. By default this is only allowed if <dst> is not -a tag (annotated or lightweight), and then only if it can fast-forward -<dst>. By having the optional leading `+`, you can tell Git to update -the <dst> ref even if it is not allowed by default (e.g., it is not a -fast-forward.) This does *not* attempt to merge <src> into <dst>. See -EXAMPLES below for details. +If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will +try to infer where in `refs/*` on the destination <repository> it +belongs based on the type of <src> being pushed and whether <dst> +is ambiguous. + -`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. +-- +* If <dst> unambiguously refers to a ref on the <repository> remote, + then push to that ref. + +* If <src> resolves to a ref starting with refs/heads/ or refs/tags/, + then prepend that to <dst>. + +* Other ambiguity resolutions might be added in the future, but for + now any other cases will error out with an error indicating what we + tried, and depending on the `advice.pushUnqualifiedRefname` + configuration (see linkgit:git-config[1]) suggest what refs/ + namespace you may have wanted to push to. + +-- + -Pushing an empty <src> allows you to delete the <dst> ref from -the remote repository. +The object referenced by <src> is used to update the <dst> reference +on the remote side. Whether this is allowed depends on where in +`refs/*` the <dst> reference lives as described in detail below, in +those sections "update" means any modifications except deletes, which +as noted after the next few sections are treated differently. ++ +The `refs/heads/*` namespace will only accept commit objects, and +updates only if they can be fast-forwarded. ++ +The `refs/tags/*` namespace will accept any kind of object (as +commits, trees and blobs can be tagged), and any updates to them will +be rejected. ++ +It's possible to push any type of object to any namespace outside of +`refs/{tags,heads}/*`. In the case of tags and commits, these will be +treated as if they were the commits inside `refs/heads/*` for the +purposes of whether the update is allowed. ++ +I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*` +is allowed, even in cases where what's being fast-forwarded is not a +commit, but a tag object which happens to point to a new commit which +is a fast-forward of the commit the last tag (or commit) it's +replacing. Replacing a tag with an entirely different tag is also +allowed, if it points to the same commit, as well as pushing a peeled +tag, i.e. pushing the commit that existing tag object points to, or a +new tag object which an existing commit points to. ++ +Tree and blob objects outside of `refs/{tags,heads}/*` will be treated +the same way as if they were inside `refs/tags/*`, any update of them +will be rejected. ++ +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` 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. Hooks and configuration can also override +or amend these rules, see e.g. `receive.denyNonFastForwards` in +linkgit:git-config[1] and `pre-receive` and `update` in +linkgit:githooks[5]. ++ +Pushing an empty <src> allows you to delete the <dst> ref from the +remote repository. Deletions are always accepted without a leading `+` +in the refspec (or `--force`), except when forbidden by configuration +or hooks. See `receive.denyDeletes` in linkgit:git-config[1] and +`pre-receive` and `update` in linkgit:githooks[5]. + The special refspec `:` (or `+:` to allow non-fast-forward updates) directs Git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name already exists on the remote side. ++ +`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. --all:: Push all branches (i.e. refs under `refs/heads/`); cannot be @@ -556,6 +611,9 @@ the ones in the examples below) can be configured as the default for `refs/remotes/satellite/master`) in the `mothership` repository; do the same for `dev` and `satellite/dev`. + +See the section describing `<refspec>...` above for a discussion of +the matching semantics. ++ This is to emulate `git fetch` run on the `mothership` using `git push` that is run in the opposite direction in order to integrate the work done on `satellite`, and is often necessary when you can diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 8cf952b4de..70562dc4c0 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git quiltimport' [--dry-run | -n] [--author <author>] [--patches <dir>] - [--series <file>] + [--series <file>] [--keep-non-patch] DESCRIPTION @@ -56,6 +56,9 @@ The default for the series file is <patches>/series or the value of the `$QUILT_SERIES` environment variable. +--keep-non-patch:: + Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt index f693930fdb..9701c1e5fd 100644 --- a/Documentation/git-range-diff.txt +++ b/Documentation/git-range-diff.txt @@ -57,6 +57,10 @@ to revert to color all lines according to the outer diff markers See the ``Algorithm`` section below for an explanation why this is needed. +--[no-]notes[=<ref>]:: + This flag is passed to the `git log` program + (see linkgit:git-log[1]) that generates the patches. + <range1> <range2>:: Compare the commits specified by the two ranges, where `<range1>` is considered an older version of `<range2>`. @@ -75,9 +79,26 @@ to revert to color all lines according to the outer diff markers linkgit:git-diff[1]), most notably the `--color=[<when>]` and `--no-color` options. These options are used when generating the "diff between patches", i.e. to compare the author, commit message and diff of -corresponding old/new commits. There is currently no means to tweak the +corresponding old/new commits. There is currently no means to tweak most of the diff options passed to `git log` when generating those patches. +OUTPUT STABILITY +---------------- + +The output of the `range-diff` command is subject to change. It is +intended to be human-readable porcelain output, not something that can +be used across versions of Git to get a textually stable `range-diff` +(as opposed to something like the `--stable` option to +linkgit:git-patch-id[1]). There's also no equivalent of +linkgit:git-apply[1] for `range-diff`, the output is not intended to +be machine-readable. + +This is particularly true when passing in diff options. Currently some +options like `--stat` can, as an emergent effect, produce output +that's quite useless in the context of `range-diff`. Future versions +of `range-diff` may learn to interpret such options in a manner +specific to `range-diff` (e.g. for `--stat` producing human-readable +output which summarizes how the diffstat changed). CONFIGURATION ------------- @@ -225,7 +246,7 @@ corresponding. The overall time needed to compute this algorithm is the time needed to compute n+m commit diffs and then n*m diffs of patches, plus the time -needed to compute the least-cost assigment between n and m diffs. Git +needed to compute the least-cost assignment between n and m diffs. Git uses an implementation of the Jonker-Volgenant algorithm to solve the assignment problem, which has cubic runtime complexity. The matching found in this case will look like this: diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 5c70bc2878..5fa8bab64c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -38,8 +38,9 @@ OPTIONS started. --reset:: - Same as -m, except that unmerged entries are discarded - instead of failing. + 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. -u:: After a successful merge, update the files in the work @@ -115,9 +116,9 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by - calling read-tree recursively, also setting the submodules HEAD to be + calling read-tree recursively, also setting the submodules' HEAD to be detached at that commit. --no-sparse-checkout:: @@ -128,6 +129,10 @@ OPTIONS Instead of reading tree object(s) into the index, just empty it. +-q:: +--quiet:: + Quiet, suppress feedback messages. + <tree-ish#>:: The id of the tree object(s) to be read/merged. @@ -431,7 +436,7 @@ support. SEE ALSO -------- linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; -linkgit:gitignore[5] +linkgit:gitignore[5]; linkgit:git-sparse-checkout[1]; GIT --- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 1fbc6ebcde..4624cfd288 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,16 +8,16 @@ git-rebase - Reapply commits on top of another base tip SYNOPSIS -------- [verse] -'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>] - [<upstream> [<branch>]] +'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] + [--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 -`git checkout <branch>` before doing anything else. Otherwise +`git switch <branch>` before doing anything else. Otherwise it remains on the current branch. If <upstream> is not specified, the upstream configured in @@ -203,7 +203,7 @@ Alternatively, you can undo the 'git rebase' with CONFIGURATION ------------- -include::rebase-config.txt[] +include::config/rebase.txt[] OPTIONS ------- @@ -217,6 +217,24 @@ 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. +--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>'. ++ +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. ++ +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. + <upstream>:: Upstream branch to compare against. May be any valid commit, not just an existing branch name. Defaults to the configured @@ -238,18 +256,79 @@ leave out at most one of A and B, in which case it defaults to HEAD. --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. + unchanged as a result. If a temporary stash entry was created + using --autostash, it will be saved to the stash list. + +--apply: + Use applying strategies to rebase (calling `git-am` + internally). This option may become a no-op in the future + once the merge backend handles everything the apply one does. ++ +See also INCOMPATIBLE OPTIONS below. +--empty={drop,keep,ask}:: + 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. ++ +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). ++ +See also INCOMPATIBLE OPTIONS below. + +--no-keep-empty:: --keep-empty:: - Keep the commits that do not change anything from its - parents in the result. + 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 + override flag to `git commit`, signifying that a user is very + intentionally creating such a commit and thus wants to keep + it. ++ +Usage of this flag will probably be rare, since you can get rid of +commits that start empty by just firing up an interactive rebase and +removing the lines corresponding to the commits you don't want. This +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 also INCOMPATIBLE OPTIONS below. + +--reapply-cherry-picks:: +--no-reapply-cherry-picks:: + Reapply all clean cherry-picks of any upstream commit instead + of preemptively dropping them. (If these commits then become + empty after rebasing, because they contain a subset of already + 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. ++ +`--reapply-cherry-picks` allows rebase to forgo reading all upstream +commits, potentially improving performance. + See also INCOMPATIBLE OPTIONS below. --allow-empty-message:: - By default, rebasing commits with an empty message will fail. - This option overrides that behavior, allowing commits with empty - messages to be rebased. + No-op. Rebasing commits with an empty message used to fail + and this option would override that behavior, allowing commits + with empty messages to be rebased. Now commits with an empty + message do not cause rebasing to halt. + See also INCOMPATIBLE OPTIONS below. @@ -268,7 +347,7 @@ See also INCOMPATIBLE OPTIONS below. --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. + upstream side. This is the 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 @@ -300,11 +379,19 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. + -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. -q:: --quiet:: @@ -333,7 +420,7 @@ See also INCOMPATIBLE OPTIONS below. 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. + ever ignored. Implies --apply. + See also INCOMPATIBLE OPTIONS below. @@ -362,13 +449,20 @@ When --fork-point is active, 'fork_point' will be used instead of <branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' ends up being empty, the <upstream> will be used as a fallback. + -If either <upstream> or --root is given on the command line, then the -default is `--no-fork-point`, otherwise the default is `--fork-point`. +If <upstream> is given on the command line, then the default is +`--no-fork-point`, otherwise the default is `--fork-point`. ++ +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. ++ +See also INCOMPATIBLE OPTIONS below. --ignore-whitespace:: --whitespace=<option>:: - These flag are passed to the 'git apply' program + These flags are passed to the 'git apply' program (see linkgit:git-apply[1]) that applies the patch. + Implies --apply. + See also INCOMPATIBLE OPTIONS below. @@ -410,14 +504,14 @@ See also INCOMPATIBLE OPTIONS below. + 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 gitlink:git-log[1]'s +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 `--preserve-merges`, but -in contrast to that option works well in interactive rebases: commits can be -reordered, inserted and dropped at will. +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. + It is currently only possible to recreate the merge commits using the `recursive` merge strategy; Different merge strategies can be used only via @@ -427,9 +521,10 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS below. -p:: --preserve-merges:: - 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. + [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 @@ -441,7 +536,8 @@ See also INCOMPATIBLE OPTIONS below. --exec <cmd>:: Append "exec <cmd>" after each line creating a commit in the final history. <cmd> will be interpreted as one or more shell - commands. + commands. Any command that fails will interrupt the rebase, + with exit code 1. + You may execute several commands by either using one instance of `--exec` with several commands: @@ -500,73 +596,188 @@ See also INCOMPATIBLE OPTIONS below. with care: the final stash application after a successful rebase might result in non-trivial conflicts. +--reschedule-failed-exec:: +--no-reschedule-failed-exec:: + Automatically reschedule `exec` commands that failed. This only makes + sense in interactive mode (or when an `--exec` option was provided). + INCOMPATIBLE OPTIONS -------------------- -git-rebase has many flags that are incompatible with each other, -predominantly due to the fact that it has three different underlying -implementations: - - * one based on linkgit:git-am[1] (the default) - * one based on git-merge-recursive (merge backend) - * one based on linkgit:git-cherry-pick[1] (interactive backend) - -Flags only understood by the am backend: +The following options: + * --apply * --committer-date-is-author-date * --ignore-date - * --whitespace * --ignore-whitespace + * --whitespace * -C -Flags understood by both merge and interactive backends: +are incompatible with the following options: * --merge * --strategy * --strategy-option * --allow-empty-message - -Flags only understood by the interactive backend: - * --[no-]autosquash * --rebase-merges * --preserve-merges * --interactive * --exec - * --keep-empty - * --autosquash + * --no-keep-empty + * --empty= + * --reapply-cherry-picks * --edit-todo * --root when used in combination with --onto -Other incompatible flag pairs: +In addition, the following pairs of options are incompatible: * --preserve-merges and --interactive * --preserve-merges and --signoff * --preserve-merges and --rebase-merges - * --rebase-merges and --strategy - * --rebase-merges and --strategy-option + * --preserve-merges and --empty= + * --keep-base and --onto + * --keep-base and --root + * --fork-point and --root BEHAVIORAL DIFFERENCES ----------------------- - * empty commits: - - am-based rebase will drop any "empty" commits, whether the - commit started empty (had no changes relative to its parent to - start with) or ended empty (all changes were already applied - upstream in other commits). +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 +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 +subtle differences in how these two backends behave: - merge-based rebase does the same. - - interactive-based rebase will by default drop commits that - started empty and halt if it hits a commit that ended up empty. - The `--keep-empty` option exists for interactive rebases to allow - it to keep commits that started empty. - - * directory rename detection: +Empty commits +~~~~~~~~~~~~~ - merge-based and interactive-based rebases work fine with - directory rename detection. am-based rebases sometimes do not. +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). + +Similar to the apply backend, by default the merge backend drops +commits that become empty unless -i/--interactive is specified (in +which case it stops and asks the user what to do). The merge backend +also has an --empty={drop,keep,ask} option for changing the behavior +of handling commits that become empty. + +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. +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 +warnings in such cases. + +Context +~~~~~~~ + +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 +line numbers have to be taken with some fuzz, since the other side +will likely have inserted or deleted lines earlier in the file. The +context region is meant to help find how to adjust the line numbers in +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 +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, +insulating it from these types of problems. + +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 +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. + +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 +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 +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. + +Interruptability +~~~~~~~~~~~~~~~~ + +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 +suffer from the same shortcoming. (See +https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for +details.) + +Commit Rewording +~~~~~~~~~~~~~~~~ + +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. + +Miscellaneous differences +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few more behavioral differences that most folks would +probably consider inconsequential but which are mentioned for +completeness: + +* Reflog: The two backends will use different wording when describing + the changes made in the reflog, though both will make use of the + word "rebase". + +* Progress, informational, and error messages: The two backends + provide slightly different progress and informational messages. + Also, the apply backend writes error messages (such as "Your files + would be overwritten...") to stdout, while the merge backend writes + them to stderr. + +* State directories: The two backends keep their state in different + directories under .git/ include::merge-strategies.txt[] @@ -641,6 +852,9 @@ By replacing the command "pick" with the command "edit", you can tell the files and/or the commit message, amend the commit, and continue rebasing. +To interrupt the rebase (just like an "edit" command would do, but without +cherry-picking any commit first), use the "break" command. + If you just want to edit the commit message for a commit, replace the command "pick" with the command "reword". @@ -669,7 +883,8 @@ $ git rebase -i HEAD~5 And move the first patch to the end of the list. -You might want to preserve merges, if you have a history like this: +You might want to recreate merge commits, e.g. if you have a history +like this: ------------------ X @@ -683,7 +898,7 @@ Suppose you want to rebase the side branch starting at "A" to "Q". Make sure that the current HEAD is "B", and call ----------------------------- -$ git rebase -i -p --onto Q O +$ git rebase -i -r --onto Q O ----------------------------- Reordering and editing commits usually creates untested intermediate @@ -825,7 +1040,8 @@ Hard case: The changes are not the same.:: This happens if the 'subsystem' rebase had conflicts, or used `--interactive` to omit, edit, squash, or fixup commits; or if the upstream used one of `commit --amend`, `reset`, or - `filter-branch`. + a full history rewriting command like + https://github.com/newren/git-filter-repo[`filter-repo`]. The easy case @@ -836,7 +1052,8 @@ Only works if the changes (patch IDs based on the diff contents) on 'subsystem' did. In that case, the fix is easy because 'git rebase' knows to skip -changes that are already present in the new upstream. So if you say +changes that are already present in the new upstream (unless +`--reapply-cherry-picks` is given). So if you say (assuming you're on 'topic') ------------ $ git rebase subsystem @@ -863,7 +1080,7 @@ NOTE: While an "easy case recovery" sometimes appears to be successful --interactive` will be **resurrected**! The idea is to manually tell 'git rebase' "where the old 'subsystem' -ended and your 'topic' began", that is, what the old merge-base +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: @@ -954,7 +1171,7 @@ command fails, it is rescheduled immediately, with a helpful message how to proceed. The `reset` command resets the HEAD, index and worktree to the specified -revision. It is isimilar to an `exec git reset --hard <label>`, but +revision. It is similar to an `exec git reset --hard <label>`, but refuses to overwrite untracked files. If the `reset` command fails, it is rescheduled immediately, with a helpful message how to edit the todo list (this typically happens when a `reset` command was inserted into the todo @@ -971,7 +1188,7 @@ 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, -strategy, with no way to choose a different one. To work around +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). @@ -1020,11 +1237,11 @@ merge cmake BUGS ---- -The todo list presented by `--preserve-merges --interactive` does not -represent the topology of the revision graph. 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. +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 ------------ diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index dedf97efbb..25702ed730 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -165,29 +165,31 @@ ref listing the commits pushed to the repository, and logs the push certificates of signed pushes with good signatures to a logger service: - #!/bin/sh - # mail out commit update information. - while read oval nval ref - do - if expr "$oval" : '0*$' >/dev/null - then - echo "Created a new ref, with the following commits:" - git rev-list --pretty "$nval" - else - echo "New commits:" - git rev-list --pretty "$nval" "^$oval" - fi | - mail -s "Changes to ref $ref" commit-list@mydomain - done - # log signed push certificate, if any - if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G +---- +#!/bin/sh +# mail out commit update information. +while read oval nval ref +do + if expr "$oval" : '0*$' >/dev/null then - ( - echo expected nonce is ${GIT_PUSH_NONCE} - git cat-file blob ${GIT_PUSH_CERT} - ) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain - fi - exit 0 + echo "Created a new ref, with the following commits:" + git rev-list --pretty "$nval" + else + echo "New commits:" + git rev-list --pretty "$nval" "^$oval" + fi | + mail -s "Changes to ref $ref" commit-list@mydomain +done +# log signed push certificate, if any +if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G +then + ( + echo expected nonce is ${GIT_PUSH_NONCE} + git cat-file blob ${GIT_PUSH_CERT} + ) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain +fi +exit 0 +---- The exit code from this hook invocation is ignored, however a non-zero exit code will generate an error message. @@ -212,8 +214,10 @@ anyway. This hook can be used, for example, to run `git update-server-info` if the repository is packed and is served via a dumb transport. - #!/bin/sh - exec git update-server-info +---- +#!/bin/sh +exec git update-server-info +---- QUARANTINE ENVIRONMENT diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 472a6808cd..ff487ff77d 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -20,7 +20,7 @@ depending on the subcommand: 'git reflog' ['show'] [log-options] [<ref>] 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] - [--dry-run | -n] [--verbose] [--all | <refs>...] + [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] [--dry-run | -n] [--verbose] ref@\{specifier\}... 'git reflog exists' <ref> @@ -72,6 +72,11 @@ Options for `expire` --all:: Process the reflogs of all references. +--single-worktree:: + By default when `--all` is specified, reflogs from all working + trees are processed. This option limits the processing to reflogs + from the current working tree only. + --expire=<time>:: Prune entries older than the specified time. If this option is not specified, the expiration time is taken from the diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 3fc5d94336..88ea7e1cc0 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -104,7 +104,7 @@ begins with `ext::`. Examples: link-level address). "ext::git-server-alias foo %G/repo% with% spaces %Vfoo":: - Represents a repository with path '/repo with spaces' accessed + Represents a repository with path `/repo with spaces` accessed using the helper program "git-server-alias foo". The hostname for the remote server passed in the protocol stream will be "foo" (this allows multiple virtual Git servers to share a @@ -118,7 +118,7 @@ begins with `ext::`. Examples: SEE ALSO -------- -linkgit:gitremote-helpers[1] +linkgit:gitremote-helpers[7] GIT --- diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 80afca866c..0451ceb8a2 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -52,7 +52,7 @@ EXAMPLES SEE ALSO -------- -linkgit:gitremote-helpers[1] +linkgit:gitremote-helpers[7] GIT --- diff --git a/Documentation/git-remote-helpers.txto b/Documentation/git-remote-helpers.txto index 49233f5d26..6f353ebfd3 100644 --- a/Documentation/git-remote-helpers.txto +++ b/Documentation/git-remote-helpers.txto @@ -1,7 +1,7 @@ git-remote-helpers ================== -This document has been moved to linkgit:gitremote-helpers[1]. +This document has been moved to linkgit:gitremote-helpers[7]. Please let the owners of the referring site know so that they can update the link you clicked to get here. diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt deleted file mode 100644 index f791d73c05..0000000000 --- a/Documentation/git-remote-testgit.txt +++ /dev/null @@ -1,30 +0,0 @@ -git-remote-testgit(1) -===================== - -NAME ----- -git-remote-testgit - Example remote-helper - - -SYNOPSIS --------- -[verse] -git clone testgit::<source-repo> [<destination>] - -DESCRIPTION ------------ - -This command is a simple remote-helper, that is used both as a -testcase for the remote-helper functionality, and as an example to -show remote-helper authors one possible implementation. - -The best way to learn more is to read the comments and source code in -'git-remote-testgit'. - -SEE ALSO --------- -linkgit:gitremote-helpers[1] - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 0cad37fb81..9659abbf8e 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -230,7 +230,7 @@ $ git branch -r staging/master staging/staging-linus staging/staging-next -$ git checkout -b staging staging/master +$ git switch -c staging staging/master ... ------------ diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index d056250968..92f146d27d 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -142,7 +142,7 @@ depth is 4095. --keep-pack=<pack-name>:: Exclude the given pack from repacking. This is the equivalent - of having `.keep` file on the pack. `<pack-name>` is the the + 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 packs. @@ -160,6 +160,11 @@ depth is 4095. being removed. In addition, any unreachable loose objects will be packed (and their loose counterparts removed). +-i:: +--delta-islands:: + Pass the `--delta-islands` option to `git-pack-objects`, see + linkgit:git-pack-objects[1]. + Configuration ------------- diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 246dc9943c..f271d758c3 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -123,10 +123,10 @@ The following format are available: CREATING REPLACEMENT OBJECTS ---------------------------- -linkgit:git-filter-branch[1], linkgit:git-hash-object[1] and -linkgit:git-rebase[1], among other git commands, can be used to create -replacement objects from existing objects. The `--edit` option can -also be used with 'git replace' to create a replacement object by +linkgit:git-hash-object[1], linkgit:git-rebase[1], and +https://github.com/newren/git-filter-repo[git-filter-repo], among other git commands, can be used to +create replacement objects from existing objects. The `--edit` option +can also be used with 'git replace' to create a replacement object by editing an existing object. If you want to replace many blobs, trees or commits that are part of a @@ -148,13 +148,13 @@ pending objects. SEE ALSO -------- linkgit:git-hash-object[1] -linkgit:git-filter-branch[1] linkgit:git-rebase[1] linkgit:git-tag[1] linkgit:git-branch[1] linkgit:git-commit[1] linkgit:git-var[1] linkgit:git[1] +https://github.com/newren/git-filter-repo[git-filter-repo] GIT --- diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 031f31fa47..4cfc883378 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -24,7 +24,7 @@ on the initial manual merge, and applying previously recorded hand resolutions to their corresponding automerge results. [NOTE] -You need to set the configuration variable rerere.enabled in order to +You need to set the configuration variable `rerere.enabled` in order to enable this command. @@ -91,7 +91,7 @@ For such a test, you need to merge master and topic somehow. One way to do it is to pull master into the topic branch: ------------ - $ git checkout topic + $ git switch topic $ git merge master o---*---o---+ topic @@ -113,10 +113,10 @@ the upstream might have been advanced since the test merge `+`, in which case the final commit graph would look like this: ------------ - $ git checkout topic + $ git switch topic $ git merge master $ ... work on both topic and master branches - $ git checkout master + $ git switch master $ git merge topic o---*---o---+---o---o topic @@ -136,11 +136,11 @@ merges, you could blow away the test merge, and keep building on top of the tip before the test merge: ------------ - $ git checkout topic + $ git switch topic $ git merge master $ git reset --hard HEAD^ ;# rewind the test merge $ ... work on both topic and master branches - $ git checkout master + $ git switch master $ git merge topic o---*---o-------o---o topic @@ -211,6 +211,12 @@ would conflict the same way as the test merge you resolved earlier. 'git rerere' will be run by 'git rebase' to help you resolve this conflict. +[NOTE] 'git rerere' relies on the conflict markers in the file to +detect the conflict. If the file already contains lines that look the +same as lines with conflict markers, 'git rerere' may fail to record a +conflict resolution. To work around this, the `conflict-marker-size` +setting in linkgit:gitattributes[5] can be used. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 1d697d9962..252e2d4e47 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,35 +8,38 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [-q] [<tree-ish>] [--] <paths>... -'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...] +'git reset' [-q] [<tree-ish>] [--] <pathspec>... +'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>] +'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...] 'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- -In the first and second form, copy entries from <tree-ish> to the index. -In the third form, set the current branch head (HEAD) to <commit>, optionally -modifying index and working tree to match. The <tree-ish>/<commit> defaults -to HEAD in all forms. - -'git reset' [-q] [<tree-ish>] [--] <paths>...:: - This form resets the index entries for all <paths> to their - state at <tree-ish>. (It does not affect the working tree or - the current branch.) -+ -This means that `git reset <paths>` is the opposite of `git add -<paths>`. -+ -After running `git reset <paths>` to update the index entry, you can -use linkgit:git-checkout[1] to check the contents out of the index to -the working tree. -Alternatively, using linkgit:git-checkout[1] and specifying a commit, you +In the first three forms, copy entries from `<tree-ish>` to the index. +In the last form, set the current branch head (`HEAD`) to `<commit>`, +optionally modifying index and working tree to match. +The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms. + +'git reset' [-q] [<tree-ish>] [--] <pathspec>...:: +'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]:: + These forms reset the index entries for all paths that match the + `<pathspec>` to their state at `<tree-ish>`. (It does not affect + the working tree or the current branch.) ++ +This means that `git reset <pathspec>` is the opposite of `git add +<pathspec>`. This command is equivalent to +`git restore [--source=<tree-ish>] --staged <pathspec>...`. ++ +After running `git reset <pathspec>` to update the index entry, you can +use linkgit:git-restore[1] to check the contents out of the index to +the working tree. Alternatively, using linkgit:git-restore[1] +and specifying a commit with `--source`, you can copy the contents of a path out of a commit to the index and to the working tree in one go. -'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]:: +'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]:: Interactively select hunks in the difference between the index - and <tree-ish> (defaults to HEAD). The chosen hunks are applied + and `<tree-ish>` (defaults to `HEAD`). The chosen hunks are applied in reverse to the index. + This means that `git reset -p` is the opposite of `git add -p`, i.e. @@ -44,16 +47,16 @@ you can use it to selectively reset hunks. See the ``Interactive Mode'' 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, - defaults to "--mixed". The <mode> must be one of the following: + 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, + defaults to `--mixed`. The `<mode>` must be one of the following: + -- --soft:: Does not touch the index file or the working tree at all (but - resets the head to <commit>, just like all modes do). This leaves - all your changed files "Changes to be committed", as 'git status' + resets the head to `<commit>`, just like all modes do). This leaves + all your changed files "Changes to be committed", as `git status` would put it. --mixed:: @@ -66,28 +69,34 @@ 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. --merge:: Resets the index and updates the files in the working tree that are - different between <commit> and HEAD, but keeps those which are + different between `<commit>` and `HEAD`, but keeps those which are different between the index and working tree (i.e. which have changes which have not been added). - If a file that is different between <commit> and the index has unstaged - changes, reset is aborted. + If a file that is different between `<commit>` and the index has + unstaged changes, reset is aborted. + -In other words, --merge does something like a 'git read-tree -u -m <commit>', +In other words, `--merge` does something like a `git read-tree -u -m <commit>`, but carries forward unmerged index entries. --keep:: Resets index entries and updates files in the working tree that are - different between <commit> and HEAD. - If a file that is different between <commit> and HEAD has local changes, - reset is aborted. + different between `<commit>` and `HEAD`. + If a file that is different between `<commit>` and `HEAD` has local + changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the working tree of all active submodules + according to the commit recorded in the superproject, also setting + the submodules' HEAD to be detached at that commit. -- -If you want to undo a commit other than the latest on a branch, -linkgit:git-revert[1] is your friend. +See "Reset, restore and revert" in linkgit:git[1] for the differences +between the three commands. OPTIONS @@ -95,8 +104,31 @@ OPTIONS -q:: --quiet:: - Be quiet, only report errors. +--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. + +--pathspec-from-file=<file>:: + 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 + global `--literal-pathspecs`. +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). + +\--:: + Do not interpret any more arguments as options. + +<pathspec>...:: + Limits the paths affected by the operation. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. EXAMPLES -------- @@ -112,17 +144,17 @@ $ git pull git://info.example.com/ nitfol <4> ------------ + <1> You are happily working on something, and find the changes -in these files are in good order. You do not want to see them -when you run "git diff", because you plan to work on other files -and changes with these files are distracting. + in these files are in good order. You do not want to see them + when you run `git diff`, because you plan to work on other files + and changes with these files are distracting. <2> Somebody asks you to pull, and the changes sound worthy of merging. <3> However, you already dirtied the index (i.e. your index does -not match the HEAD commit). But you know the pull you are going -to make does not affect frotz.c or filfre.c, so you revert the -index changes for these two files. Your changes in working tree -remain there. -<4> Then you can pull and merge, leaving frotz.c and filfre.c -changes still in the working tree. + not match the `HEAD` commit). But you know the pull you are going + to make does not affect `frotz.c` or `filfre.c`, so you revert the + index changes for these two files. Your changes in working tree + remain there. +<4> Then you can pull and merge, leaving `frotz.c` and `filfre.c` + changes still in the working tree. Undo a commit and redo:: + @@ -134,29 +166,29 @@ $ git commit -a -c ORIG_HEAD <3> ------------ + <1> This is most often done when you remembered what you -just committed is incomplete, or you misspelled your commit -message, or both. Leaves working tree as it was before "reset". + just committed is incomplete, or you misspelled your commit + message, or both. Leaves working tree as it was before "reset". <2> Make corrections to working tree files. -<3> "reset" copies the old head to .git/ORIG_HEAD; redo the -commit by starting with its log message. If you do not need to -edit the message further, you can give -C option instead. +<3> "reset" copies the old head to `.git/ORIG_HEAD`; redo the + commit by starting with its log message. If you do not need to + edit the message further, you can give `-C` option instead. + -See also the --amend option to linkgit:git-commit[1]. +See also the `--amend` option to linkgit:git-commit[1]. Undo a commit, making it a topic branch:: + ------------ -$ git branch topic/wip <1> -$ git reset --hard HEAD~3 <2> -$ git checkout topic/wip <3> +$ git branch topic/wip <1> +$ git reset --hard HEAD~3 <2> +$ git switch topic/wip <3> ------------ + <1> You have made some commits, but realize they were premature -to be in the "master" branch. You want to continue polishing -them in a topic branch, so create "topic/wip" branch off of the -current HEAD. + to be in the `master` branch. You want to continue polishing + them in a topic branch, so create `topic/wip` branch off of the + current `HEAD`. <2> Rewind the master branch to get rid of those three commits. -<3> Switch to "topic/wip" branch and keep working. +<3> Switch to `topic/wip` branch and keep working. Undo commits permanently:: + @@ -165,11 +197,11 @@ $ git commit ... $ git reset --hard HEAD~3 <1> ------------ + -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad -and you do not want to ever see them again. Do *not* do this if -you have already given these commits to somebody else. (See the -"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for -the implications of doing so.) +<1> The last three commits (`HEAD`, `HEAD^`, and `HEAD~2`) were bad + and you do not want to ever see them again. Do *not* do this if + you have already given these commits to somebody else. (See the + "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] + for the implications of doing so.) Undo a merge or pull:: + @@ -186,18 +218,18 @@ $ git reset --hard ORIG_HEAD <4> ------------ + <1> Try to update from the upstream resulted in a lot of -conflicts; you were not ready to spend a lot of time merging -right now, so you decide to do that later. -<2> "pull" has not made merge commit, so "git reset --hard" -which is a synonym for "git reset --hard HEAD" clears the mess -from the index file and the working tree. + conflicts; you were not ready to spend a lot of time merging + right now, so you decide to do that later. +<2> "pull" has not made merge commit, so `git reset --hard` + which is a synonym for `git reset --hard HEAD` clears the mess + from the index file and the working tree. <3> Merge a topic branch into the current branch, which resulted -in a fast-forward. + in a fast-forward. <4> But you decided that the topic branch is not ready for public -consumption yet. "pull" or "merge" always leaves the original -tip of the current branch in ORIG_HEAD, so resetting hard to it -brings your index file and the working tree back to that state, -and resets the tip of the branch to that commit. + consumption yet. "pull" or "merge" always leaves the original + tip of the current branch in `ORIG_HEAD`, so resetting hard to it + brings your index file and the working tree back to that state, + and resets the tip of the branch to that commit. Undo a merge or pull inside a dirty working tree:: + @@ -211,14 +243,14 @@ $ git reset --merge ORIG_HEAD <2> ------------ + <1> Even if you may have local modifications in your -working tree, you can safely say "git pull" when you know -that the change in the other branch does not overlap with -them. + working tree, you can safely say `git pull` when you know + that the change in the other branch does not overlap with + them. <2> After inspecting the result of the merge, you may find -that the change in the other branch is unsatisfactory. Running -"git reset --hard ORIG_HEAD" will let you go back to where you -were, but it will discard your local changes, which you do not -want. "git reset --merge" keeps your local changes. + that the change in the other branch is unsatisfactory. Running + `git reset --hard ORIG_HEAD` will let you go back to where you + were, but it will discard your local changes, which you do not + want. `git reset --merge` keeps your local changes. Interrupted workflow:: @@ -229,13 +261,13 @@ working tree are not in any shape to be committed yet, but you need to get to the other branch for a quick bugfix. + ------------ -$ git checkout feature ;# you were working in "feature" branch and -$ work work work ;# got interrupted +$ git switch feature ;# you were working in "feature" branch and +$ work work work ;# got interrupted $ git commit -a -m "snapshot WIP" <1> -$ git checkout master +$ git switch master $ fix fix fix $ git commit ;# commit with real log -$ git checkout feature +$ git switch feature $ git reset --soft HEAD^ ;# go back to WIP state <2> $ git reset <3> ------------ @@ -276,21 +308,21 @@ reset it while keeping the changes in your working tree. + ------------ $ git tag start -$ git checkout -b branch1 +$ git switch -c branch1 $ edit $ git commit ... <1> $ edit -$ git checkout -b branch2 <2> +$ git switch -c branch2 <2> $ git reset --keep start <3> ------------ + -<1> This commits your first edits in branch1. +<1> This commits your first edits in `branch1`. <2> In the ideal world, you could have realized that the earlier commit did not belong to the new topic when you created and switched - to branch2 (i.e. "git checkout -b branch2 start"), but nobody is + to `branch2` (i.e. `git switch -c branch2 start`), but nobody is perfect. -<3> But you can use "reset --keep" to remove the unwanted commit after - you switched to "branch2". +<3> But you can use `reset --keep` to remove the unwanted commit after + you switched to `branch2`. Split a commit apart into a sequence of commits:: + @@ -314,26 +346,27 @@ $ git commit ... <8> + <1> First, reset the history back one commit so that we remove the original commit, but leave the working tree with all the changes. The -N ensures - that any new files added with HEAD are still marked so that git add -p + that any new files added with `HEAD` are still marked so that `git add -p` will find them. -<2> Next, we interactively select diff hunks to add using the git add -p +<2> Next, we interactively select diff hunks to add using the `git add -p` facility. This will ask you about each diff hunk in sequence and you can use simple commands such as "yes, include this", "No don't include this" or even the very powerful "edit" facility. <3> Once satisfied with the hunks you want to include, you should verify what - has been prepared for the first commit by using git diff --cached. This + has been prepared for the first commit by using `git diff --cached`. This shows all the changes that have been moved into the index and are about to be committed. -<4> Next, commit the changes stored in the index. The -c option specifies to +<4> Next, commit the changes stored in the index. The `-c` option specifies to pre-populate the commit message from the original message that you started - with in the first commit. This is helpful to avoid retyping it. The HEAD@{1} - is a special notation for the commit that HEAD used to be at prior to the - original reset commit (1 change ago). See linkgit:git-reflog[1] for more - details. You may also use any other valid commit reference. + with in the first commit. This is helpful to avoid retyping it. The + `HEAD@{1}` is a special notation for the commit that `HEAD` used to be at + prior to the original reset commit (1 change ago). + See linkgit:git-reflog[1] for more details. You may also use any other + valid commit reference. <5> You can repeat steps 2-4 multiple times to break the original code into any number of commits. <6> Now you've split out many of the changes into their own commits, and might - no longer use the patch mode of git add, in order to select all remaining + no longer use the patch mode of `git add`, in order to select all remaining uncommitted changes. <7> Once again, check to verify that you've included what you want to. You may also wish to verify that git diff doesn't show any remaining changes to be @@ -350,104 +383,120 @@ The tables below show what happens when running: git reset --option target ---------- -to reset the HEAD to another commit (`target`) with the different +to reset the `HEAD` to another commit (`target`) with the different reset options depending on the state of the files. -In these tables, A, B, C and D are some different states of a +In these tables, `A`, `B`, `C` and `D` are some different states of a file. For example, the first line of the first table means that if a -file is in state A in the working tree, in state B in the index, in -state C in HEAD and in state D in the target, then "git reset --soft -target" will leave the file in the working tree in state A and in the -index in state B. It resets (i.e. moves) the HEAD (i.e. the tip of -the current branch, if you are on one) to "target" (which has the file -in state D). - - working index HEAD target working index HEAD - ---------------------------------------------------- - A B C D --soft A B D - --mixed A D D - --hard D D D - --merge (disallowed) - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - A B C C --soft A B C - --mixed A C C - --hard C C C - --merge (disallowed) - --keep A C C - - working index HEAD target working index HEAD - ---------------------------------------------------- - B B C D --soft B B D - --mixed B D D - --hard D D D - --merge D D D - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - B B C C --soft B B C - --mixed B C C - --hard C C C - --merge C C C - --keep B C C - - working index HEAD target working index HEAD - ---------------------------------------------------- - B C C D --soft B C D - --mixed B D D - --hard D D D - --merge (disallowed) - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - B C C C --soft B C C - --mixed B C C - --hard C C C - --merge B C C - --keep B C C - -"reset --merge" is meant to be used when resetting out of a conflicted +file is in state `A` in the working tree, in state `B` in the index, in +state `C` in `HEAD` and in state `D` in the target, then `git reset --soft +target` will leave the file in the working tree in state `A` and in the +index in state `B`. It resets (i.e. moves) the `HEAD` (i.e. the tip of +the current branch, if you are on one) to `target` (which has the file +in state `D`). + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + A B C D --soft A B D + --mixed A D D + --hard D D D + --merge (disallowed) + --keep (disallowed) +.... + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + A B C C --soft A B C + --mixed A C C + --hard C C C + --merge (disallowed) + --keep A C C +.... + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + B B C D --soft B B D + --mixed B D D + --hard D D D + --merge D D D + --keep (disallowed) +.... + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + B B C C --soft B B C + --mixed B C C + --hard C C C + --merge C C C + --keep B C C +.... + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + B C C D --soft B C D + --mixed B D D + --hard D D D + --merge (disallowed) + --keep (disallowed) +.... + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + B C C C --soft B C C + --mixed B C C + --hard C C C + --merge B C C + --keep B C C +.... + +`reset --merge` is meant to be used when resetting out of a conflicted merge. Any mergy operation guarantees that the working tree file that is -involved in the merge does not have local change wrt the index before -it starts, and that it writes the result out to the working tree. So if +involved in the merge does not have a local change with respect to the index +before it starts, and that it writes the result out to the working tree. So if we see some difference between the index and the target and also between the index and the working tree, then it means that we are not resetting out from a state that a mergy operation left after failing -with a conflict. That is why we disallow --merge option in this case. +with a conflict. That is why we disallow `--merge` option in this case. -"reset --keep" is meant to be used when removing some of the last +`reset --keep` is meant to be used when removing some of the last commits in the current branch while keeping changes in the working tree. If there could be conflicts between the changes in the commit we want to remove and the changes in the working tree we want to keep, the reset is disallowed. That's why it is disallowed if there are both -changes between the working tree and HEAD, and between HEAD and the +changes between the working tree and `HEAD`, and between `HEAD` and the target. To be safe, it is also disallowed when there are unmerged entries. The following tables show what happens when there are unmerged entries: - working index HEAD target working index HEAD - ---------------------------------------------------- - X U A B --soft (disallowed) - --mixed X B B - --hard B B B - --merge B B B - --keep (disallowed) - - working index HEAD target working index HEAD - ---------------------------------------------------- - X U A A --soft (disallowed) - --mixed X A A - --hard A A A - --merge A A A - --keep (disallowed) - -X means any state and U means an unmerged index. +.... +working index HEAD target working index HEAD +---------------------------------------------------- + X U A B --soft (disallowed) + --mixed X B B + --hard B B B + --merge B B B + --keep (disallowed) +.... + +.... +working index HEAD target working index HEAD +---------------------------------------------------- + X U A A --soft (disallowed) + --mixed X A A + --hard A A A + --merge A A A + --keep (disallowed) +.... + +`X` means any state and `U` means an unmerged index. GIT --- diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt new file mode 100644 index 0000000000..84c6c40010 --- /dev/null +++ b/Documentation/git-restore.txt @@ -0,0 +1,215 @@ +git-restore(1) +============== + +NAME +---- +git-restore - Restore working tree files + +SYNOPSIS +-------- +[verse] +'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>... +'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] --pathspec-from-file=<file> [--pathspec-file-nul] +'git restore' (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...] + +DESCRIPTION +----------- +Restore specified paths in the working tree with some contents from a +restore source. If a path is tracked but does not exist in the restore +source, it will be removed to match the source. + +The command can also be used to restore the content in the index with +`--staged`, or restore both the working tree and the index with +`--staged --worktree`. + +By default, if `--staged` is given, the contents are restored from `HEAD`, +otherwise from the index. Use `--source` to restore from a different commit. + +See "Reset, restore and revert" in linkgit:git[1] for the differences +between the three commands. + +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. + +OPTIONS +------- +-s <tree>:: +--source=<tree>:: + Restore the working tree files with the content from the given + tree. It is common to specify the source tree by naming a + commit, branch or tag associated with it. ++ +If not specified, the contents are restored from `HEAD` if `--staged` is +given, otherwise from the index. + +-p:: +--patch:: + Interactively select hunks in the difference between the + restore source and the restore location. See the ``Interactive + Mode'' section of linkgit:git-add[1] to learn how to operate + the `--patch` mode. ++ +Note that `--patch` can accept no pathspec and will prompt to restore +all modified paths. + +-W:: +--worktree:: +-S:: +--staged:: + Specify the restore location. If neither option is specified, + by default the working tree is restored. Specifying `--staged` + will only restore the index. Specifying both restores both. + +-q:: +--quiet:: + Quiet, suppress feedback messages. Implies `--no-progress`. + +--progress:: +--no-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 enables progress reporting even if not + attached to a terminal, regardless of `--quiet`. + +--ours:: +--theirs:: + When restoring files in the working tree from the index, use + stage #2 ('ours') or #3 ('theirs') for unmerged paths. ++ +Note that during `git rebase` and `git pull --rebase`, 'ours' and +'theirs' may appear swapped. See the explanation of the same options +in linkgit:git-checkout[1] for details. + +-m:: +--merge:: + When restoring files on the working tree from the index, + recreate the conflicted merge in the unmerged paths. + +--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). + +--ignore-unmerged:: + When restoring files on the working tree from the index, do + not abort the operation if there are unmerged entries and + neither `--ours`, `--theirs`, `--merge` or `--conflict` is + 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 + matched by `<pathspec>` and sparse patterns in + $GIT_DIR/info/sparse-checkout. This option ignores the sparse + patterns and unconditionally restores any files in + `<pathspec>`. + +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names an active submodule and the restore location + includes the working tree, the submodule will only be updated if + this option is given, in which case its working tree will be + restored to the commit recorded in the superproject, and any local + modifications overwritten. If nothing (or + `--no-recurse-submodules`) is used, submodules working trees will + not be updated. Just like linkgit:git-checkout[1], this will detach + `HEAD` of the submodule. + +--overlay:: +--no-overlay:: + In overlay mode, the command never removes files when + restoring. In no-overlay mode, tracked files that do not + appear in the `--source` tree are removed, to make them match + `<tree>` exactly. The default is no-overlay mode. + +--pathspec-from-file=<file>:: + 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 + global `--literal-pathspecs`. + +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). + +\--:: + Do not interpret any more arguments as options. + +<pathspec>...:: + Limits the paths affected by the operation. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. + +EXAMPLES +-------- + +The following sequence switches to the `master` branch, reverts the +`Makefile` to two revisions back, deletes hello.c by mistake, and gets +it back from the index. + +------------ +$ git switch master +$ git restore --source master~2 Makefile <1> +$ rm -f hello.c +$ git restore hello.c <2> +------------ + +<1> take a file out of another commit +<2> restore hello.c from the index + +If you want to restore _all_ C source files to match the version in +the index, you can say + +------------ +$ git restore '*.c' +------------ + +Note the quotes around `*.c`. The file `hello.c` will also be +restored, 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). + +To restore all files in the current directory + +------------ +$ git restore . +------------ + +or to restore all working tree files with 'top' pathspec magic (see +linkgit:gitglossary[7]) + +------------ +$ git restore :/ +------------ + +To restore a file in the index to match the version in `HEAD` (this is +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 +as using linkgit:git-checkout[1]) + +------------ +$ git restore --source=HEAD --staged --worktree hello.c +------------ + +or the short form which is more practical but less readable: + +------------ +$ git restore -s@ -SW hello.c +------------ + +SEE ALSO +-------- +linkgit:git-checkout[1], +linkgit:git-reset[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 88609ff435..025c911436 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,58 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order SYNOPSIS -------- [verse] -'git rev-list' [ --max-count=<number> ] - [ --skip=<number> ] - [ --max-age=<timestamp> ] - [ --min-age=<timestamp> ] - [ --sparse ] - [ --merges ] - [ --no-merges ] - [ --min-parents=<number> ] - [ --no-min-parents ] - [ --max-parents=<number> ] - [ --no-max-parents ] - [ --first-parent ] - [ --remove-empty ] - [ --full-history ] - [ --not ] - [ --all ] - [ --branches[=<pattern>] ] - [ --tags[=<pattern>] ] - [ --remotes[=<pattern>] ] - [ --glob=<glob-pattern> ] - [ --ignore-missing ] - [ --stdin ] - [ --quiet ] - [ --topo-order ] - [ --parents ] - [ --timestamp ] - [ --left-right ] - [ --left-only ] - [ --right-only ] - [ --cherry-mark ] - [ --cherry-pick ] - [ --encoding=<encoding> ] - [ --(author|committer|grep)=<pattern> ] - [ --regexp-ignore-case | -i ] - [ --extended-regexp | -E ] - [ --fixed-strings | -F ] - [ --date=<format>] - [ [ --objects | --objects-edge | --objects-edge-aggressive ] - [ --unpacked ] - [ --filter=<filter-spec> [ --filter-print-omitted ] ] ] - [ --missing=<missing-action> ] - [ --pretty | --header ] - [ --bisect ] - [ --bisect-vars ] - [ --bisect-all ] - [ --merge ] - [ --reverse ] - [ --walk-reflogs ] - [ --no-walk ] [ --do-walk ] - [ --count ] - [ --use-bitmap-index ] - <commit>... [ \-- <paths>... ] +'git rev-list' [<options>] <commit>... [[--] <path>...] DESCRIPTION ----------- diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index e72d332b83..19b12b6d43 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -262,7 +262,8 @@ print a message to stderr and exit with nonzero status. directory. --show-toplevel:: - Show the absolute path of the top-level directory. + Show the absolute path of the top-level directory of the working + tree. If there is no working tree, report an error. --show-superproject-working-tree:: Show the absolute path of the root of the superproject's @@ -274,6 +275,13 @@ print a message to stderr and exit with nonzero status. Show the path to the shared index file in split index mode, or empty if not in split-index mode. +--show-object-format[=(storage|input|output)]:: + Show the object format (hash algorithm) used for the repository + for storage inside the `.git` directory, input, or output. For + input, multiple algorithms may be printed, space-separated. + If not specified, the default is "storage". + + Other Options ~~~~~~~~~~~~~ diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 837707a8fd..044276e9da 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -9,9 +9,7 @@ SYNOPSIS -------- [verse] 'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>... -'git revert' --continue -'git revert' --quit -'git revert' --abort +'git revert' (--continue | --skip | --abort | --quit) DESCRIPTION ----------- @@ -26,10 +24,13 @@ effect of some earlier commits (often only a faulty one). If you want to throw away all uncommitted changes in your working directory, you should see linkgit:git-reset[1], particularly the `--hard` option. If you want to extract specific files as they were in another commit, you -should see linkgit:git-checkout[1], specifically the `git checkout -<commit> -- <filename>` syntax. Take care with these alternatives as +should see linkgit:git-restore[1], specifically the `--source` +option. Take care with these alternatives as both will discard uncommitted changes in your working directory. +See "Reset, restore and revert" in linkgit:git[1] for the differences +between the three commands. + OPTIONS ------- <commit>...:: @@ -66,6 +67,13 @@ more details. With this option, 'git revert' will not start the commit message editor. +--cleanup=<mode>:: + This option determines how the commit message will be cleaned up before + being passed on to the commit machinery. See linkgit:git-commit[1] for more + details. In particular, if the '<mode>' is given a value of `scissors`, + scissors will be appended to `MERGE_MSG` before being passed on in the case + of a conflict. + -n:: --no-commit:: Usually the command automatically creates some commits with @@ -82,9 +90,12 @@ effect to your index in a row. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. -s:: --signoff:: @@ -101,6 +112,11 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[] diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index b5c46223c4..ab750367fd 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -8,16 +8,18 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- [verse] -'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... +'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] + [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...] DESCRIPTION ----------- -Remove files from the index, or from the working tree and the index. -`git rm` will not remove a file from just your working directory. -(There is no option to remove a file only from the working tree -and yet keep it in the index; use `/bin/rm` if you want to do that.) -The files being removed have to be identical to the tip of the branch, -and no updates to their contents can be staged in the index, +Remove files matching pathspec from the index, or from the working tree +and the index. `git rm` will not remove a file from just your working +directory. (There is no option to remove a file only from the working +tree and yet keep it in the index; use `/bin/rm` if you want to do +that.) The files being removed have to be identical to the tip of the +branch, and no updates to their contents can be staged in the index, though that default behavior can be overridden with the `-f` option. When `--cached` is given, the staged content has to match either the tip of the branch or the file on disk, @@ -26,15 +28,20 @@ allowing the file to be removed from just the index. OPTIONS ------- -<file>...:: - Files to remove. Fileglobs (e.g. `*.c`) can be given to - remove all matching files. If you want Git to expand - file glob characters, you may need to shell-escape them. - A leading directory name - (e.g. `dir` to remove `dir/file1` and `dir/file2`) can be - given to remove all files in the directory, and recursively - all sub-directories, - but this requires the `-r` option to be explicitly given. +<pathspec>...:: + Files to remove. A leading directory name (e.g. `dir` to remove + `dir/file1` and `dir/file2`) can be given to remove all files in + the directory, and recursively all sub-directories, but this + requires the `-r` option to be explicitly given. ++ +The command removes only the paths that are known to Git. ++ +File globbing matches across directory boundaries. Thus, given two +directories `d` and `d2`, there is a difference between using +`git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all +of directory `d2`. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. -f:: --force:: @@ -68,19 +75,19 @@ OPTIONS `git rm` normally outputs one line (in the form of an `rm` command) for each file removed. This option suppresses that output. +--pathspec-from-file=<file>:: + 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 + global `--literal-pathspecs`. -DISCUSSION ----------- - -The <file> list given to the command can be exact pathnames, -file glob patterns, or leading directory names. The command -removes only the paths that are known to Git. Giving the name of -a file that you have not told Git about does not remove that file. +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). -File globbing matches across directory boundaries. Thus, given -two directories `d` and `d2`, there is a difference between -using `git rm 'd*'` and `git rm 'd/*'`, as the former will -also remove all of directory `d2`. REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM -------------------------------------------------------- diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 465a4ecbed..0a69810147 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -33,7 +33,7 @@ This is what linkgit:git-format-patch[1] generates. Most headers and MIME formatting are ignored. 2. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl' -script + script + This format expects the first line of the file to contain the "Cc:" value and the "Subject:" of the message as the second line. @@ -190,7 +190,9 @@ $ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ... If at least one of the specified mechanisms matches the ones advertised by the SMTP server and if it is supported by the utilized SASL library, the mechanism is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth` -is specified, all mechanisms supported by the SASL library can be used. +is specified, all mechanisms supported by the SASL library can be used. The +special value 'none' maybe specified to completely disable authentication +independently of `--smtp-user` --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no @@ -204,6 +206,9 @@ or on the command line. If a username has been specified (with specified (with `--smtp-pass` or `sendemail.smtpPass`), then a password is obtained using 'git-credential'. +--no-smtp-auth:: + Disable SMTP authentication. Short hand for `--smtp-auth=none` + --smtp-server=<host>:: If set, specifies the outgoing SMTP server to use (e.g. `smtp.example.com` or a raw IP address). Alternatively it can @@ -273,6 +278,14 @@ must be used for each option. Automating ~~~~~~~~~~ +--no-[to|cc|bcc]:: + Clears any list of "To:", "Cc:", "Bcc:" addresses previously + set via config. + +--no-identity:: + Clears the previously read value of `sendemail.identity` set + via config, if any. + --to-cmd=<command>:: Specify a command to execute once per patch file which should generate patch file specific "To:" entries. @@ -321,16 +334,19 @@ Automating auto-cc of: + -- -- 'author' will avoid including the patch author -- 'self' will avoid including the sender +- 'author' will avoid including the patch author. +- 'self' will avoid including the sender. - 'cc' will avoid including anyone mentioned in Cc lines in the patch header except for self (use 'self' for that). - 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). - 'sob' will avoid including anyone mentioned in Signed-off-by lines except - for self (use 'self' for that). + for self (use 'self' for that). +- 'misc-by' will avoid including anyone mentioned in Acked-by, + Reviewed-by, Tested-by and other "-by" lines in the patch body, + except Signed-off-by (use 'sob' for that). - 'cccmd' will avoid running the --cc-cmd. -- 'body' is equivalent to 'sob' + 'bodycc' +- 'body' is equivalent to 'sob' + 'bodycc' + 'misc-by'. - 'all' will suppress all auto cc values. -- + @@ -470,11 +486,13 @@ Use gmail as the smtp server To use 'git send-email' to send your patches through the GMail SMTP server, edit ~/.gitconfig to specify your account settings: - [sendemail] - smtpEncryption = tls - smtpServer = smtp.gmail.com - smtpUser = yourname@gmail.com - smtpServerPort = 587 +---- +[sendemail] + smtpEncryption = tls + smtpServer = smtp.gmail.com + smtpUser = yourname@gmail.com + smtpServerPort = 587 +---- If you have multifactor authentication setup on your gmail account, you will need to generate an app-specific password for use with 'git send-email'. Visit @@ -492,8 +510,12 @@ app-specific or your regular password as appropriate. If you have credential helper configured (see linkgit:git-credential[1]), the password will be saved in the credential store so you won't have to type it the next time. -Note: the following perl modules are required - Net::SMTP::SSL, MIME::Base64 and Authen::SASL +Note: the following core Perl modules that may be installed with your +distribution of Perl are required: +MIME::Base64, MIME::QuotedPrint, Net::Domain and Net::SMTP. +These additional Perl modules are also required: +Authen::SASL and Mail::Address. + SEE ALSO -------- diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index bc80905a8a..a72ea7f7ba 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -76,6 +76,9 @@ them. Paths may need to be prefixed with `--` to separate them from options or the revision range, when confusion arises. +:git-shortlog: 1 +include::rev-list-options.txt[] + MAPPING AUTHORS --------------- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 262db049d7..5cc2fcefba 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -19,7 +19,7 @@ DESCRIPTION ----------- Shows the commit ancestry graph starting from the commits named -with <rev>s or <globs>s (or all refs under refs/heads +with <rev>s or <glob>s (or all refs under refs/heads and/or refs/tags) semi-visually. It cannot show more than 29 branches and commits at a time. @@ -167,7 +167,7 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +whose commit message is "Add \'git show-branch'". The "fixes" branch adds one commit "Introduce "reset type" flag to "git reset"". The "mhf" branch adds many other commits. The current branch is "master". diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index d28e6154c6..ab4d271925 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -37,8 +37,8 @@ OPTIONS Show the HEAD reference, even if it would normally be filtered out. ---tags:: --heads:: +--tags:: Limit to "refs/heads" and "refs/tags", respectively. These options are not mutually exclusive; when given both, references stored in diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt new file mode 100644 index 0000000000..7c8943af7a --- /dev/null +++ b/Documentation/git-sparse-checkout.txt @@ -0,0 +1,217 @@ +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. + + +SYNOPSIS +-------- +[verse] +'git sparse-checkout <subcommand> [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 EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER +COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN +THE FUTURE. + + +COMMANDS +-------- +'list':: + Describe the 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. ++ +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 `--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). + +'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. + +'reapply':: + Reapply the sparsity pattern rules to paths in the working tree. + Commands like merge or rebase can materialize paths to do their + work (e.g. in order to show you a conflict), and other + sparse-checkout commands might fail to sparsify an individual file + (e.g. because it has unstaged changes or conflicts). In such + 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.). + +'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. + +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. + +The `$GIT_DIR/info/sparse-checkout` file is used to define the +skip-worktree reference bitmap. When Git updates the working +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. + +To repopulate the working directory with all files, use the +`git sparse-checkout disable` command. + + +FULL PATTERN SET +---------------- + +By default, the sparse-checkout file uses the same syntax as `.gitignore` +files. + +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`: + +---------------- +/* +!unwanted +---------------- + + +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. + +The accepted patterns in the cone pattern set are: + +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: + +---------------- +/* +!/*/ +---------------- + +This says "include everything in root, but nothing two levels below root." + +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 + +---------------- +/* +!/*/ +/A/ +!/A/*/ +/A/B/ +!/A/B/*/ +/A/B/C/ +---------------- + +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. + +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: + +-------------------------- +$ git sparse-checkout list +A/B/C +-------------------------- + +If `core.ignoreCase=true`, then the pattern-matching algorithm will use a +case-insensitive check. This corrects for case mismatched filenames in the +'git sparse-checkout set' command to reflect the expected cone in the working +directory. + + +SUBMODULES +---------- + +If your repository contains one or more submodules, then those submodules will +appear based on which you initialized with the `git submodule` command. If +your sparse-checkout patterns exclude an initialized submodule, then that +submodule will still appear in your working directory. + + +SEE ALSO +-------- + +linkgit:git-read-tree[1] +linkgit:gitignore[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 7ef8c47911..31f1beb65b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,12 +9,13 @@ SYNOPSIS -------- [verse] 'git stash' list [<options>] -'git stash' show [<stash>] +'git stash' show [<options>] [<stash>] 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | 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>] + [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]] 'git stash' clear 'git stash' create [<message>] @@ -43,10 +44,10 @@ created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}` is also possible). Stashes may also be referenced by specifying just the stash index (e.g. the integer `n` is equivalent to `stash@{n}`). -OPTIONS -------- +COMMANDS +-------- -push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--] [<pathspec>...]:: +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>...]:: Save your local modifications to a new 'stash entry' and roll them back to HEAD (in the working tree and in the index). @@ -56,39 +57,15 @@ push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q For quickly making a snapshot, you can omit "push". In this mode, non-option arguments are not allowed to prevent a misspelled subcommand from making an unwanted stash entry. The two exceptions to this -are `stash -p` which acts as alias for `stash push -p` and pathspecs, +are `stash -p` which acts as alias for `stash push -p` and pathspec elements, which are allowed after a double hyphen `--` for disambiguation. -+ -When pathspec is given to 'git stash push', the new stash entry records the -modified states only for the files that match the pathspec. The index -entries and working tree files are then rolled back to the state in -HEAD only for these files, too, leaving files that do not match the -pathspec intact. -+ -If the `--keep-index` option is used, all changes already added to the -index are left intact. -+ -If the `--include-untracked` option is used, all untracked files are also -stashed and then cleaned up with `git clean`, leaving the working directory -in a very clean state. If the `--all` option is used instead then the -ignored files are stashed and cleaned in addition to the untracked files. -+ -With `--patch`, you can interactively select hunks from the diff -between HEAD and the working tree to be stashed. The stash entry is -constructed such that its index state is the same as the index state -of your repository, and its worktree contains only the changes you -selected interactively. The selected changes are then rolled back -from your worktree. See the ``Interactive Mode'' section of -linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -The `--patch` option implies `--keep-index`. You can use -`--no-keep-index` to override this. save [-p|--patch] [-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 pathspecs, - and any non-option arguments form the message. + differs from "stash push" in that it cannot take pathspec. + Instead, all non-option arguments are concatenated to form the stash + message. list [<options>]:: @@ -106,11 +83,11 @@ stash@{1}: On master: 9cc0589... Add git-stash The command takes options applicable to the 'git log' command to control what is shown and how. See linkgit:git-log[1]. -show [<stash>]:: +show [<options>] [<stash>]:: Show the changes recorded in the stash entry as a diff between the stashed contents and the commit back when the stash entry was first - created. When no `<stash>` is given, it shows the latest one. + created. By default, the command shows the diffstat, but it will accept any format known to 'git diff' (e.g., `git stash show -p stash@{1}` to view the second most recent entry in patch form). @@ -127,14 +104,6 @@ pop [--index] [-q|--quiet] [<stash>]:: Applying the state can fail with conflicts; in this case, it is not removed from the stash list. You need to resolve the conflicts by hand and call `git stash drop` manually afterwards. -+ -If the `--index` option is used, then tries to reinstate not only the working -tree's changes, but also the index's ones. However, this can fail, when you -have conflicts (which are stored in the index, where you therefore can no -longer apply the changes as they were originally). -+ -When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must -be a reference of the form `stash@{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: @@ -148,8 +117,7 @@ branch <branchname> [<stash>]:: the commit at which the `<stash>` was originally created, applies the changes recorded in `<stash>` to the new working tree and index. If that succeeds, and `<stash>` is a reference of the form - `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>` - is given, applies the latest one. + `stash@{<revision>}`, it then drops the `<stash>`. + This is useful if the branch on which you ran `git stash push` has changed enough that `git stash apply` fails due to conflicts. Since @@ -165,9 +133,6 @@ clear:: drop [-q|--quiet] [<stash>]:: Remove a single stash entry from the list of stash entries. - When no `<stash>` is given, it removes the latest one. - i.e. `stash@{0}`, otherwise `<stash>` must be a valid stash - log reference of the form `stash@{<revision>}`. create:: @@ -184,6 +149,98 @@ store:: reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "push" above. +OPTIONS +------- +-a:: +--all:: + This option is only valid for `push` and `save` commands. ++ +All ignored and untracked files are also stashed and then cleaned +up with `git clean`. + +-u:: +--include-untracked:: + This option is only valid for `push` and `save` commands. ++ +All untracked files are also stashed and then cleaned up with +`git clean`. + +--index:: + This option is only valid for `pop` and `apply` commands. ++ +Tries to reinstate not only the working tree's changes, but also +the index's ones. However, this can fail, when you have conflicts +(which are stored in the index, where you therefore can no longer +apply the changes as they were originally). + +-k:: +--keep-index:: +--no-keep-index:: + This option is only valid for `push` and `save` commands. ++ +All changes already added to the index are left intact. + +-p:: +--patch:: + This option is only valid for `push` and `save` commands. ++ +Interactively select hunks from the diff between HEAD and the +working tree to be stashed. The stash entry is constructed such +that its index state is the same as the index state of your +repository, and its worktree contains only the changes you selected +interactively. The selected changes are then rolled back from your +worktree. See the ``Interactive Mode'' section of linkgit:git-add[1] +to learn how to operate the `--patch` mode. ++ +The `--patch` option implies `--keep-index`. You can use +`--no-keep-index` to override this. + +--pathspec-from-file=<file>:: + This option is only valid for `push` command. ++ +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 +global `--literal-pathspecs`. + +--pathspec-file-nul:: + This option is only valid for `push` command. ++ +Only meaningful with `--pathspec-from-file`. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes). + +-q:: +--quiet:: + This option is only valid for `apply`, `drop`, `pop`, `push`, + `save`, `store` commands. ++ +Quiet, suppress feedback messages. + +\--:: + This option is only valid for `push` command. ++ +Separates pathspec from options for disambiguation purposes. + +<pathspec>...:: + This option is only valid for `push` command. ++ +The new stash entry records the modified states only for the files +that match the pathspec. The index entries and working tree files +are then rolled back to the state in HEAD only for these files, +too, leaving files that do not match the pathspec intact. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. + +<stash>:: + This option is only valid for `apply`, `branch`, `drop`, `pop`, + `show` commands. ++ +A reference of the form `stash@{<revision>}`. When no `<stash>` is +given, the latest stash is assumed (that is, `stash@{0}`). + DISCUSSION ---------- @@ -235,12 +292,12 @@ return to your original branch to make the emergency fix, like this: + ---------------------------------------------------------------- # ... hack hack hack ... -$ git checkout -b my_wip +$ git switch -c my_wip $ git commit -a -m "WIP" -$ git checkout master +$ git switch master $ edit emergency fix $ git commit -a -m "Fix in a hurry" -$ git checkout my_wip +$ git switch my_wip $ git reset --soft HEAD^ # ... continue hacking ... ---------------------------------------------------------------- @@ -293,7 +350,8 @@ SEE ALSO linkgit:git-checkout[1], linkgit:git-commit[1], linkgit:git-reflog[1], -linkgit:git-reset[1] +linkgit:git-reset[1], +linkgit:git-switch[1] GIT --- diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index d9f422d560..7731b45f07 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -59,16 +59,17 @@ This is optional and defaults to the original version 'v1' format. --untracked-files[=<mode>]:: Show untracked files. + +-- The mode parameter is used to specify the handling of untracked files. It is optional: it defaults to 'all', and if specified, it must be stuck to the option (e.g. `-uno`, but not `-u no`). -+ + The possible options are: -+ + - 'no' - Show no untracked files. - 'normal' - Shows untracked files and directories. - 'all' - Also shows individual files in untracked directories. -+ + When `-u` option is not used, untracked files and directories are shown (i.e. the same as specifying `normal`), to help you avoid forgetting to add newly created files. Because it takes extra work @@ -78,9 +79,10 @@ 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. -+ + The default can be changed using the status.showUntrackedFiles configuration variable documented in linkgit:git-config[1]. +-- --ignore-submodules[=<when>]:: Ignore changes to submodules when looking for changes. <when> can be @@ -100,11 +102,12 @@ configuration variable documented in linkgit:git-config[1]. --ignored[=<mode>]:: Show ignored files as well. + +-- The mode parameter is used to specify the handling of ignored files. It is optional: it defaults to 'traditional'. -+ + The possible options are: -+ + - 'traditional' - Shows ignored files and directories, unless --untracked-files=all is specified, in which case individual files in ignored directories are @@ -112,12 +115,13 @@ The possible options are: - 'no' - Show no ignored files. - 'matching' - Shows ignored files and directories matching an ignore pattern. -+ + When 'matching' mode is specified, paths that explicitly match an ignored pattern are shown. If a directory matches an ignore pattern, then it is shown, but not paths contained in the ignored directory. If a directory does not match an ignore pattern, but all contents are ignored, then the directory is not shown, but all contents are shown. +-- -z:: Terminate entries with NUL, instead of LF. This implies @@ -197,31 +201,33 @@ codes can be interpreted as follows: Ignored files are not listed, unless `--ignored` option is in effect, in which case `XY` are `!!`. - X Y Meaning - ------------------------------------------------- - [AMD] not updated - M [ MD] updated in index - A [ MD] 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 - ------------------------------------------------- - D D unmerged, both deleted - A U unmerged, added by us - U D unmerged, deleted by them - U A unmerged, added by them - D U unmerged, deleted by us - A A unmerged, both added - U U unmerged, both modified - ------------------------------------------------- - ? ? untracked - ! ! ignored - ------------------------------------------------- +.... +X Y Meaning +------------------------------------------------- + [AMD] not updated +M [ MD] updated in index +A [ MD] 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 +------------------------------------------------- +D D unmerged, both deleted +A U unmerged, added by us +U D unmerged, deleted by them +U A unmerged, added by them +D U unmerged, deleted by us +A A unmerged, both added +U U unmerged, both modified +------------------------------------------------- +? ? untracked +! ! ignored +------------------------------------------------- +.... Submodules have more state and instead report M the submodule has a different HEAD than @@ -276,21 +282,25 @@ Header lines start with "#" and are added in response to specific command line arguments. Parsers should ignore headers they don't recognize. -### Branch Headers +Branch Headers +^^^^^^^^^^^^^^ If `--branch` is given, a series of header lines are printed with information about the current branch. - Line Notes - ------------------------------------------------------------ - # branch.oid <commit> | (initial) Current commit. - # branch.head <branch> | (detached) Current branch. - # branch.upstream <upstream_branch> If upstream is set. - # branch.ab +<ahead> -<behind> If upstream is set and - the commit is present. - ------------------------------------------------------------ +.... +Line Notes +------------------------------------------------------------ +# branch.oid <commit> | (initial) Current commit. +# branch.head <branch> | (detached) Current branch. +# branch.upstream <upstream_branch> If upstream is set. +# branch.ab +<ahead> -<behind> If upstream is set and + the commit is present. +------------------------------------------------------------ +.... -### Changed Tracked Entries +Changed Tracked Entries +^^^^^^^^^^^^^^^^^^^^^^^ Following the headers, a series of lines are printed for tracked entries. One of three different line formats may be used to describe @@ -306,58 +316,63 @@ Renamed or copied entries have the following format: 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath> - Field Meaning - -------------------------------------------------------- - <XY> A 2 character field containing the staged and - unstaged XY values described in the short format, - with unchanged indicated by a "." rather than - a space. - <sub> A 4 character field describing the submodule state. - "N..." when the entry is not a submodule. - "S<c><m><u>" when the entry is a submodule. - <c> is "C" if the commit changed; otherwise ".". - <m> is "M" if it has tracked changes; otherwise ".". - <u> is "U" if there are untracked changes; otherwise ".". - <mH> The octal file mode in HEAD. - <mI> The octal file mode in the index. - <mW> The octal file mode in the worktree. - <hH> The object name in HEAD. - <hI> The object name in the index. - <X><score> The rename or copy score (denoting the percentage - of similarity between the source and target of the - move or copy). For example "R100" or "C75". - <path> The pathname. In a renamed/copied entry, this - is the target path. - <sep> When the `-z` option is used, the 2 pathnames are separated - with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09) - byte separates them. - <origPath> The pathname in the commit at HEAD or in the index. - This is only present in a renamed/copied entry, and - tells where the renamed/copied contents came from. - -------------------------------------------------------- +.... +Field Meaning +-------------------------------------------------------- +<XY> A 2 character field containing the staged and + unstaged XY values described in the short format, + with unchanged indicated by a "." rather than + a space. +<sub> A 4 character field describing the submodule state. + "N..." when the entry is not a submodule. + "S<c><m><u>" when the entry is a submodule. + <c> is "C" if the commit changed; otherwise ".". + <m> is "M" if it has tracked changes; otherwise ".". + <u> is "U" if there are untracked changes; otherwise ".". +<mH> The octal file mode in HEAD. +<mI> The octal file mode in the index. +<mW> The octal file mode in the worktree. +<hH> The object name in HEAD. +<hI> The object name in the index. +<X><score> The rename or copy score (denoting the percentage + of similarity between the source and target of the + move or copy). For example "R100" or "C75". +<path> The pathname. In a renamed/copied entry, this + is the target path. +<sep> When the `-z` option is used, the 2 pathnames are separated + with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09) + byte separates them. +<origPath> The pathname in the commit at HEAD or in the index. + This is only present in a renamed/copied entry, and + tells where the renamed/copied contents came from. +-------------------------------------------------------- +.... 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> - Field Meaning - -------------------------------------------------------- - <XY> A 2 character field describing the conflict type - as described in the short format. - <sub> A 4 character field describing the submodule state - as described above. - <m1> The octal file mode in stage 1. - <m2> The octal file mode in stage 2. - <m3> The octal file mode in stage 3. - <mW> The octal file mode in the worktree. - <h1> The object name in stage 1. - <h2> The object name in stage 2. - <h3> The object name in stage 3. - <path> The pathname. - -------------------------------------------------------- - -### Other Items +.... +Field Meaning +-------------------------------------------------------- +<XY> A 2 character field describing the conflict type + as described in the short format. +<sub> A 4 character field describing the submodule state + as described above. +<m1> The octal file mode in stage 1. +<m2> The octal file mode in stage 2. +<m3> The octal file mode in stage 3. +<mW> The octal file mode in the worktree. +<h1> The object name in stage 1. +<h2> The object name in stage 2. +<h3> The object name in stage 3. +<path> The pathname. +-------------------------------------------------------- +.... + +Other Items +^^^^^^^^^^^ Following the tracked entries (and if requested), a series of lines will be printed for untracked and then ignored items @@ -371,7 +386,8 @@ Ignored items have the following format: ! <path> -### Pathname Format Notes and -z +Pathname Format Notes and -z +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the `-z` option is given, pathnames are printed as is and without any quoting and lines are terminated with a NUL (ASCII 0x00) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index ba3c4df550..c9ed2bf3d5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,11 +9,14 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] +'git submodule' [--quiet] [--cached] 'git submodule' [--quiet] add [<options>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) 'git submodule' [--quiet] update [<options>] [--] [<path>...] +'git submodule' [--quiet] set-branch [<options>] [--] <path> +'git submodule' [--quiet] set-url [--] <path> <newurl> 'git submodule' [--quiet] summary [<options>] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--recursive] [--] [<path>...] @@ -28,6 +31,9 @@ For more information about submodules, see linkgit:gitsubmodules[7]. COMMANDS -------- +With no arguments, shows the status of existing submodules. Several +subcommands are available to perform operations on the submodules. + add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current @@ -38,7 +44,7 @@ This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's default remote repository (Please note that to specify a repository 'foo.git' which is located right next to a superproject 'bar.git', you'll -have to use '../foo.git' instead of './foo.git' - as one might expect +have to use `../foo.git` instead of `./foo.git` - as one might expect when following the rules for relative URLs - because the evaluation of relative URLs in Git is identical to that of relative directories). + @@ -75,6 +81,9 @@ status [--cached] [--recursive] [--] [<path>...]:: does not match the SHA-1 found in the index of the containing repository and `U` if the submodule has merge conflicts. + +If `--cached` is specified, this command will instead print the SHA-1 +recorded in the superproject for each submodule. ++ If `--recursive` is specified, this command will recurse into nested submodules, and show their status as well. + @@ -124,11 +133,12 @@ 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>] [--] [<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] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject -expects by cloning missing submodules and updating the working tree of +expects by cloning missing submodules, fetching missing commits +in submodules and updating the working tree of 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 @@ -168,6 +178,18 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. -- +set-branch (-b|--branch) <branch> [--] <path>:: +set-branch (-d|--default) [--] <path>:: + Sets the default remote tracking branch for the submodule. The + `--branch` option allows the remote branch to be specified. The + `--default` option removes the submodule.<name>.branch configuration + key, which causes the tracking branch to default to 'master'. + +set-url [--] <path> <newurl>:: + Sets the URL of the specified submodule to <newurl>. Then, it will + automatically synchronize the submodule's new remote URL + configuration. + summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits @@ -207,7 +229,7 @@ As an example, the command below will show the path and currently checked out commit for each submodule: + -------------- -git submodule foreach 'echo $path `git rev-parse HEAD`' +git submodule foreach 'echo $sm_path `git rev-parse HEAD`' -------------- sync [--recursive] [--] [<path>...]:: @@ -226,7 +248,7 @@ registered submodules, and sync any nested submodules within. absorbgitdirs:: If a git directory of a submodule is inside the submodule, - move the git directory of the submodule into its superprojects + move the git directory of the submodule into its superproject's `$GIT_DIR/modules` path and then connect the git directory and its working directory by setting the `core.worktree` and adding a .git file pointing to the git directory embedded in the @@ -255,13 +277,14 @@ OPTIONS This option is only valid for the deinit command. Unregister all submodules in the working tree. --b:: ---branch:: +-b <branch>:: +--branch <branch>:: Branch of repository to add as submodule. The name of the branch is recorded as `submodule.<name>.branch` in `.gitmodules` for `update --remote`. A special value of `.` is used to indicate that the name of the branch in the submodule should be the - same name as the current branch in the current repository. + same name as the current branch in the current repository. If the + option is not specified, it defaults to 'master'. -f:: --force:: @@ -407,6 +430,10 @@ options carefully. Clone new submodules in parallel with as many jobs. Defaults to the `submodule.fetchJobs` option. +--[no-]single-branch:: + This option is only valid for the update command. + Clone only one branch during update: HEAD or one specified by --branch. + <path>...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index b99029520d..6624a14fbd 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -126,7 +126,7 @@ your Perl's Getopt::Long is < v2.37). command-line argument. + This automatically updates the rev_map if needed (see -'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +'$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). --localtime;; Store Git commit times in the local time zone instead of UTC. This @@ -239,7 +239,7 @@ Like 'git rebase'; this requires that the working tree be clean and have no uncommitted changes. + This automatically updates the rev_map if needed (see -'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +'$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). -l;; --local;; @@ -524,7 +524,7 @@ This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file way to repair the repo is to use 'reset'. + Only the rev_map and refs/remotes/git-svn are changed (see -'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +'$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to move local branches onto the new tree. @@ -677,7 +677,8 @@ config key: svn.authorsProg -s<strategy>:: --strategy=<strategy>:: -p:: ---preserve-merges:: +--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 @@ -760,7 +761,7 @@ svn-remote.<name>.noMetadata:: + This option can only be used for one-shot imports as 'git svn' will not be able to fetch again without metadata. Additionally, -if you lose your '$GIT_DIR/svn/\*\*/.rev_map.*' files, 'git svn' will not +if you lose your '$GIT_DIR/svn/\**/.rev_map.*' files, 'git svn' will not be able to rebuild them. + The 'git svn log' command will not work on repositories using @@ -769,11 +770,11 @@ option for (hopefully) obvious reasons. + This option is NOT recommended as it makes it difficult to track down old references to SVN revision numbers in existing documentation, bug -reports and archives. If you plan to eventually migrate from SVN to Git -and are certain about dropping SVN history, consider -linkgit:git-filter-branch[1] instead. filter-branch also allows -reformatting of metadata for ease-of-reading and rewriting authorship -info for non-"svn.authorsFile" users. +reports, and archives. If you plan to eventually migrate from SVN to +Git and are certain about dropping SVN history, consider +https://github.com/newren/git-filter-repo[git-filter-repo] instead. +filter-repo also allows reformatting of metadata for ease-of-reading +and rewriting authorship info for non-"svn.authorsFile" users. svn.useSvmProps:: svn-remote.<name>.useSvmProps:: @@ -1100,10 +1101,10 @@ listed below are allowed: tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ -Keep in mind that the '\*' (asterisk) wildcard of the local ref -(right of the ':') *must* be the farthest right path component; +Keep in mind that the `*` (asterisk) wildcard of the local ref +(right of the `:`) *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's an -independent path component (surrounded by '/' or EOL). This +independent path component (surrounded by `/` or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. @@ -1154,7 +1155,7 @@ fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove FILES ----- -$GIT_DIR/svn/\*\*/.rev_map.*:: +$GIT_DIR/svn/\**/.rev_map.*:: Mapping between Subversion revision numbers and Git commit names. In a repository where the noMetadata option is not set, this can be rebuilt from the git-svn-id: lines that are at the diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt new file mode 100644 index 0000000000..3759c3a265 --- /dev/null +++ b/Documentation/git-switch.txt @@ -0,0 +1,273 @@ +git-switch(1) +============= + +NAME +---- +git-switch - Switch branches + +SYNOPSIS +-------- +[verse] +'git switch' [<options>] [--no-guess] <branch> +'git switch' [<options>] --detach [<start-point>] +'git switch' [<options>] (-c|-C) <new-branch> [<start-point>] +'git switch' [<options>] --orphan <new-branch> + +DESCRIPTION +----------- +Switch to a specified branch. The working tree and the index are +updated to match the branch. All new commits will be added to the tip +of this branch. + +Optionally a new branch could be created with either `-c`, `-C`, +automatically from a remote branch of same name (see `--guess`), or +detach the working tree from any branch with `--detach`, along with +switching. + +Switching branches does not require a clean index and working tree +(i.e. no differences compared to `HEAD`). The operation is aborted +however if the operation leads to loss of local changes, unless told +otherwise with `--discard-changes` or `--merge`. + +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. + +OPTIONS +------- +<branch>:: + Branch to switch to. + +<new-branch>:: + Name for the new branch. + +<start-point>:: + The starting point for the new branch. Specifying a + `<start-point>` allows you to create a branch based on some + other point in history than where HEAD currently points. (Or, + in the case of `--detach`, allows you to inspect and detach + from some other point.) ++ +You can use the `@{-N}` syntax to refer to the N-th last +branch/commit switched to using "git switch" or "git checkout" +operation. You may also specify `-` which is synonymous to `@{-1}`. +This is often used to switch quickly between two branches, or to undo +a branch switch by mistake. ++ +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`. + +-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: ++ +------------ +$ git branch <new-branch> +$ git switch <new-branch> +------------ + +-C <new-branch>:: +--force-create <new-branch>:: + Similar to `--create` except that if `<new-branch>` already + exists, it will be reset to `<start-point>`. This is a + convenient shortcut for: ++ +------------ +$ git branch -f <new-branch> +$ git switch <new-branch> +------------ + +-d:: +--detach:: + Switch to a commit for inspection and discardable + experiments. See the "DETACHED HEAD" section in + linkgit:git-checkout[1] for details. + +--guess:: +--no-guess:: + If `<branch>` is not found but there does exist a tracking + branch in exactly one remote (call it `<remote>`) with a + matching name, treat as equivalent to ++ +------------ +$ git switch -c <branch> --track <remote>/<branch> +------------ ++ +If the branch exists in multiple remotes and one of them is named by +the `checkout.defaultRemote` configuration variable, we'll use that +one for the purposes of disambiguation, even if the `<branch>` isn't +unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` +to always checkout remote branches from there if `<branch>` is +ambiguous but exists on the 'origin' remote. See also +`checkout.defaultRemote` in linkgit:git-config[1]. ++ +`--guess` is the default behavior. Use `--no-guess` to disable it. + +-f:: +--force:: + An alias for `--discard-changes`. + +--discard-changes:: + Proceed even if the index or the working tree differs from + `HEAD`. Both the index and working tree are restored to match + the switching target. If `--recurse-submodules` is specified, + submodule content is also restored to match the switching + target. This is used to throw away local changes. + +-m:: +--merge:: + If you have local modifications to one or more files that are + different between the current branch and the branch to which + you are switching, the command refuses to switch branches in + order to preserve your modifications in context. However, + with this option, a three-way merge between the current + branch, your working tree contents, and the new branch is + done, and you will be on the new branch. ++ +When a merge conflict happens, the index entries for conflicting +paths are left unmerged, and you need to resolve the conflicts +and mark the resolved paths with `git add` (or `git rm` if the merge +should result in deletion of the path). + +--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). + +-q:: +--quiet:: + Quiet, suppress feedback messages. + +--progress:: +--no-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 enables progress reporting even if not + attached to a terminal, regardless of `--quiet`. + +-t:: +--track:: + When creating a new branch, set up "upstream" configuration. + `-c` is implied. See `--track` in linkgit:git-branch[1] for + details. ++ +If no `-c` option is given, the name of the new branch will be derived +from the remote-tracking branch, by looking at the local part of the +refspec configured for the corresponding remote, and then stripping +the initial part up to the "*". This would tell us to use `hack` as +the local branch when branching off of `origin/hack` (or +`remotes/origin/hack`, or even `refs/remotes/origin/hack`). If the +given name has no slash, or the above guessing results in an empty +name, the guessing is aborted. You can explicitly give a name with +`-c` in such a case. + +--no-track:: + Do not set up "upstream" configuration, even if the + `branch.autoSetupMerge` configuration variable is true. + +--orphan <new-branch>:: + Create a new 'orphan' branch, named `<new-branch>`. All + tracked files are removed. + +--ignore-other-worktrees:: + `git switch` refuses when the wanted ref is already + checked out by another worktree. This option makes it check + the ref out anyway. In other words, the ref can be held by + more than one worktree. + +--recurse-submodules:: +--no-recurse-submodules:: + Using `--recurse-submodules` will update the content of all + active submodules according to the commit recorded in the + superproject. If nothing (or `--no-recurse-submodules`) is + used, submodules working trees will not be updated. Just + like linkgit:git-submodule[1], this will detach `HEAD` of the + submodules. + +EXAMPLES +-------- + +The following command switches to the "master" branch: + +------------ +$ git switch master +------------ + +After working in the wrong branch, switching to the correct branch +would be done using: + +------------ +$ git switch mytopic +------------ + +However, your "wrong" branch and correct "mytopic" branch may differ +in files that you have modified locally, in which case the above +switch would fail like this: + +------------ +$ git switch 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 switch -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. + +To switch back to the previous branch before we switched to mytopic +(i.e. "master" branch): + +------------ +$ git switch - +------------ + +You can grow a new branch from any commit. For example, switch to +"HEAD~3" and create branch "fixup": + +------------ +$ git switch -c fixup HEAD~3 +Switched to a new branch 'fixup' +------------ + +If you want to start a new branch from a remote branch of the same +name: + +------------ +$ git switch new-topic +Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin' +Switched to a new branch 'new-topic' +------------ + +To check out commit `HEAD~3` for temporary inspection or experiment +without creating a new branch: + +------------ +$ git switch --detach HEAD~3 +HEAD is now at 9fc9555312 Merge branch 'cc/shared-index-permbits' +------------ + +If it turns out whatever you have done is worth keeping, you can +always create a new name for it (without switching away): + +------------ +$ git switch -c good-surprises +------------ + +SEE ALSO +-------- +linkgit:git-checkout[1], +linkgit:git-branch[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 92f9c12b87..f6d9791780 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -64,6 +64,13 @@ OPTIONS -s:: --sign:: Make a GPG-signed tag, using the default e-mail address's key. + The default behavior of tag GPG-signing is controlled by `tag.gpgSign` + configuration variable if it exists, or disabled otherwise. + See linkgit:git-config[1]. + +--no-sign:: + Override `tag.gpgSign` configuration variable that is + set to force each and every tag to be signed. -u <keyid>:: --local-user=<keyid>:: @@ -187,6 +194,12 @@ This option is only applicable when listing tags without annotation lines. `--create-reflog`, but currently does not negate the setting of `core.logAllRefUpdates`. +--format=<format>:: + A string that interpolates `%(fieldname)` from a tag ref being shown + and the object it points at. The format is the same as + that of linkgit:git-for-each-ref[1]. When unspecified, + defaults to `%(refname:strip=2)`. + <tagname>:: The name of the tag to create, delete, or describe. The new tag name must pass all checks defined by @@ -198,12 +211,6 @@ This option is only applicable when listing tags without annotation lines. The object that the new tag will refer to, usually a commit. Defaults to HEAD. -<format>:: - A string that interpolates `%(fieldname)` from a tag ref being shown - and the object it points at. The format is the same as - that of linkgit:git-for-each-ref[1]. When unspecified, - defaults to `%(refname:strip=2)`. - CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your @@ -237,16 +244,16 @@ your repository directly), then others will have already seen the old tag. In that case you can do one of two things: . The sane thing. -Just admit you screwed up, and use a different name. Others have -already seen one tag-name, and if you keep the same name, you -may be in the situation that two people both have "version X", -but they actually have 'different' "X"'s. So just call it "X.1" -and be done with it. + Just admit you screwed up, and use a different name. Others have + already seen one tag-name, and if you keep the same name, you + may be in the situation that two people both have "version X", + but they actually have 'different' "X"'s. So just call it "X.1" + and be done with it. . The insane thing. -You really want to call the new version "X" too, 'even though' -others have already seen the old one. So just use 'git tag -f' -again, as if you hadn't already published the old one. + You really want to call the new version "X" too, 'even though' + others have already seen the old one. So just use 'git tag -f' + again, as if you hadn't already published the old one. However, Git does *not* (and it should not) change tags behind users back. So if somebody already got the old tag, doing a diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 1c4d146a41..1489cb09a0 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -16,6 +16,7 @@ SYNOPSIS [--chmod=(+|-)x] [--[no-]assume-unchanged] [--[no-]skip-worktree] + [--[no-]ignore-skip-worktree-entries] [--[no-]fsmonitor-valid] [--ignore-submodules] [--[no-]split-index] @@ -113,6 +114,11 @@ you will need to handle the situation manually. set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. + +--[no-]ignore-skip-worktree-entries:: + Do not remove skip-worktree (AKA "index-only") entries even when + the `--remove` option was specified. + --[no-]fsmonitor-valid:: When one of these flags is specified, the object name recorded for the paths are not updated. Instead, these options @@ -426,7 +432,7 @@ specified by the splitIndex.sharedIndexExpire config variable (see linkgit:git-config[1]). To avoid deleting a shared index file that is still used, its -modification time is updated to the current time everytime a new split +modification time is updated to the current time every time a new split index based on the shared index file is either created or read from. UNTRACKED CACHE @@ -543,6 +549,22 @@ The untracked cache extension can be enabled by the `core.untrackedCache` configuration variable (see linkgit:git-config[1]). +NOTES +----- + +Users often try to use the assume-unchanged and skip-worktree bits +to tell Git to ignore changes to files that are tracked. This does not +work as expected, since Git may still check working tree files against +the index when performing certain operations. In general, Git does not +provide a way to ignore changes to tracked files, so alternate solutions +are recommended. + +For example, if the file you want to change is some sort of config file, +the repository can include a sample config file that can then be copied +into the ignored name and modified. The repository can even include a +script to treat the sample file as a template, modifying and copying it +automatically. + SEE ALSO -------- linkgit:git-config[1], diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index bc8fdfd469..3e737c2360 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -8,7 +8,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- [verse] -'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) +'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) DESCRIPTION ----------- @@ -66,6 +66,10 @@ performs all modifications together. Specify commands of the form: delete SP <ref> [SP <oldvalue>] LF verify SP <ref> [SP <oldvalue>] LF option SP <opt> LF + start LF + prepare LF + commit LF + abort LF With `--create-reflog`, update-ref will create a reflog for each ref even if one would not ordinarily be created. @@ -83,6 +87,10 @@ quoting: delete SP <ref> NUL [<oldvalue>] NUL verify SP <ref> NUL [<oldvalue>] NUL option SP <opt> NUL + start NUL + prepare NUL + commit NUL + abort NUL In this format, use 40 "0" to specify a zero value, and use the empty string to specify a missing value. @@ -107,13 +115,31 @@ delete:: verify:: Verify <ref> against <oldvalue> but do not change it. If - <oldvalue> zero or missing, the ref must not exist. + <oldvalue> is zero or missing, the ref must not exist. option:: Modify behavior of the next command naming a <ref>. The only valid option is `no-deref` to avoid dereferencing a symbolic ref. +start:: + Start a transaction. In contrast to a non-transactional session, a + transaction will automatically abort if the session ends without an + explicit commit. + +prepare:: + Prepare to commit the transaction. This will create lock files for all + queued reference updates. If one reference could not be locked, the + transaction will be aborted. + +commit:: + Commit all reference updates queued for the transaction, ending the + transaction. + +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 simultaneously, all modifications are performed. Otherwise, no modifications are performed. Note that while each individual @@ -129,8 +155,8 @@ a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating the log name) describing the change in ref value. Log lines are formatted as: - . oldsha1 SP newsha1 SP committer LF -+ + oldsha1 SP newsha1 SP committer LF + 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 @@ -138,8 +164,8 @@ and date in the standard Git committer ident format. Optionally with -m: - . oldsha1 SP newsha1 SP committer TAB message LF -+ + oldsha1 SP newsha1 SP committer TAB message LF + Where all fields are as described above and "message" is the value supplied to the -m option. diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index bd0e36492f..969bb2e15f 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' [--force] +'git update-server-info' DESCRIPTION ----------- @@ -19,15 +19,6 @@ $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 ------ diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 822ad593af..9822c1eb1a 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc] [--advertise-refs] <directory> + DESCRIPTION ----------- Invoked by 'git fetch-pack', learns what @@ -21,7 +22,6 @@ The UI for the protocol is on the 'git fetch-pack' side, and the program pair is meant to be used to pull updates from a remote repository. For push operations, see 'git send-pack'. - OPTIONS ------- diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index fd952a5ff9..8d162b56c5 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -92,8 +92,8 @@ configuration variable, we launch 'kfmclient' to try to open the HTML man page on an already opened konqueror in a new tab if possible. For consistency, we also try such a trick if 'browser.konqueror.path' is -set to something like 'A_PATH_TO/konqueror'. That means we will try to -launch 'A_PATH_TO/kfmclient' instead. +set to something like `A_PATH_TO/konqueror`. That means we will try to +launch `A_PATH_TO/kfmclient` instead. If you really want to use 'konqueror', then you can use something like the following: diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 9c26be40f4..85d92c9761 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -120,8 +120,16 @@ OPTIONS --force:: By default, `add` refuses to create a new working tree when `<commit-ish>` is a branch name and is already checked out by - another working tree and `remove` refuses to remove an unclean - working tree. This option overrides these safeguards. + another working tree, or if `<path>` is already assigned to some + working tree 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. ++ +`move` refuses to move a locked working tree unless `--force` is specified +twice. ++ +`remove` refuses to remove an unclean working tree unless `--force` is used. +To remove a locked working tree, specify `--force` twice. -b <new-branch>:: -B <new-branch>:: @@ -173,6 +181,10 @@ This can also be set up as the default behaviour by using the This format will remain stable across Git versions and regardless of user configuration. See below for details. +-q:: +--quiet:: + With 'add', suppress feedback messages. + -v:: --verbose:: With `prune`, report all removals. @@ -192,6 +204,65 @@ working trees, it can be used to identify worktrees. 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. +REFS +---- +In multiple working trees, some refs may be shared between all working +trees, some refs are local. One example is HEAD is different for all +working trees. 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 is one +exception to this: refs inside refs/bisect and refs/worktree is 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-worktree refs of the main working tree, +while the latter to all linked working trees. + +For example, main-worktree/HEAD or main-worktree/refs/bisect/good +resolve to the same value as the main working tree'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 +GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad. + +To access refs, it's best not to look inside GIT_DIR directly. Instead +use commands such as linkgit:git-rev-parse[1] or linkgit:git-update-ref[1] +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. + +In order to have configuration specific to working trees, you can turn +on "worktreeConfig" extension, e.g.: + +------------ +$ git config extensions.worktreeConfig true +------------ + +In this mode, specific configuration stays in the path pointed by `git +rev-parse --git-path config.worktree`. You can add or update +configuration in this file with `git config --worktree`. Older Git +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 you have them in $GIT_DIR/config before, 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: + + - `core.worktree` and `core.bare` should never be shared + + - `core.sparseCheckout` is recommended per working tree, unless you + are sure you always use sparse checkout for all working trees. + DETAILS ------- Each linked working tree has a private sub-directory in the repository's @@ -216,7 +287,8 @@ linked working tree `git rev-parse --git-path HEAD` returns `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git rev-parse --git-path refs/heads/master` uses $GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, -since refs are shared across all working trees. +since refs are shared across all working trees, except refs/bisect and +refs/worktree. See linkgit:gitrepository-layout[5] for more information. The rule of thumb is do not make any assumption about whether a path belongs to @@ -241,6 +313,9 @@ to `/path/main/.git/worktrees/test-next` then a file named `test-next` entry from being pruned. See linkgit:gitrepository-layout[5] for details. +When extensions.worktreeConfig is enabled, the config file +`.git/worktrees/<id>/config.worktree` is read after `.git/config` is. + LIST OUTPUT FORMAT ------------------ The worktree list command has two output formats. The default format shows the @@ -258,8 +333,8 @@ Porcelain Format The porcelain format has a line per attribute. 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 only present if and only -if the value is true. An empty line indicates the end of a worktree. For -example: +if the value is true. The first attribute of a worktree is always `worktree`, +an empty line indicates the end of the record. For example: ------------ $ git worktree list --porcelain diff --git a/Documentation/git.txt b/Documentation/git.txt index dba7f0c18e..9d6769e95a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -33,7 +33,8 @@ individual Git commands with "git help command". linkgit:gitcli[7] manual page gives you an overview of the command-line command syntax. A formatted and hyperlinked copy of the latest Git documentation -can be viewed at `https://git.github.io/htmldocs/git.html`. +can be viewed at https://git.github.io/htmldocs/git.html +or https://git-scm.com/docs. OPTIONS @@ -56,7 +57,8 @@ help ...`. Run as if git was started in '<path>' instead of the current working directory. When multiple `-C` options are given, each subsequent non-absolute `-C <path>` is interpreted relative to the preceding `-C - <path>`. + <path>`. If '<path>' is present but empty, e.g. `-C ""`, then the + current working directory is left unchanged. + This option affects options that expect path name like `--git-dir` and `--work-tree` in that their interpretations of the path names would be @@ -76,7 +78,7 @@ Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets `foo.bar` to the boolean true value (just like `[foo]bar` would in a config file). Including the equals but with an empty value (like `git -c foo.bar= ...`) sets `foo.bar` to the empty string which `git config ---bool` will convert to `false`. +--type=bool` will convert to `false`. --exec-path[=<path>]:: Path to wherever your core Git programs are installed. @@ -108,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config Do not pipe Git output into a pager. --git-dir=<path>:: - Set the path to the repository. This can also be controlled by - setting the `GIT_DIR` environment variable. It can be an absolute - path or relative path to current working directory. + Set the path to the repository (".git" directory). This can also be + controlled by setting the `GIT_DIR` environment variable. It can be + an absolute path or relative path to current working directory. ++ +Specifying the location of the ".git" directory using this +option (or `GIT_DIR` environment variable) turns off the +repository discovery that tries to find a directory with +".git" subdirectory (which is how the repository and the +top-level of the working tree are discovered), and tells Git +that you are at the top level of the working tree. If you +are not at the top-level directory of the working tree, you +should tell Git where the top-level of the working tree is, +with the `--work-tree=<path>` option (or `GIT_WORK_TREE` +environment variable) ++ +If you just want to run git as if it was started in `<path>` then use +`git -C <path>`. --work-tree=<path>:: Set the path to the working tree. It can be an absolute path @@ -210,6 +226,26 @@ people via patch over e-mail. include::cmds-foreignscminterface.txt[] +Reset, restore and revert +~~~~~~~~~~~~~~~~~~~~~~~~~ +There are three commands with similar names: `git reset`, +`git restore` and `git revert`. + +* linkgit:git-revert[1] is about making a new commit that reverts the + changes made by other commits. + +* linkgit:git-restore[1] is about restoring files in the working tree + from either the index or another commit. This command does not + update your branch. The command can also be used to restore files in + the index from another commit. + +* linkgit:git-reset[1] is about updating your branch, moving the tip + in order to add or remove commits from the branch. This operation + changes the commit history. ++ +`git reset` can also be used to restore the index, overlapping with +`git restore`. + Low-level commands (plumbing) ----------------------------- @@ -249,8 +285,8 @@ In general, the interrogate commands do not touch the files in the working tree. -Synching repositories -~~~~~~~~~~~~~~~~~~~~~ +Syncing repositories +~~~~~~~~~~~~~~~~~~~~ include::cmds-synchingrepositories.txt[] @@ -402,11 +438,11 @@ Git so take care if using a foreign front-end. of Git object directories which can be used to search for Git objects. New objects will not be written to these directories. + - Entries that begin with `"` (double-quote) will be interpreted - as C-style quoted paths, removing leading and trailing - double-quotes and respecting backslash escapes. E.g., the value - `"path-with-\"-and-:-in-it":vanilla-path` has two paths: - `path-with-"-and-:-in-it` and `vanilla-path`. +Entries that begin with `"` (double-quote) will be interpreted +as C-style quoted paths, removing leading and trailing +double-quotes and respecting backslash escapes. E.g., the value +`"path-with-\"-and-:-in-it":vanilla-path` has two paths: +`path-with-"-and-:-in-it` and `vanilla-path`. `GIT_DIR`:: If the `GIT_DIR` environment variable is set then it @@ -457,16 +493,45 @@ Git so take care if using a foreign front-end. details. This variable has lower precedence than other path variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... +`GIT_DEFAULT_HASH_ALGORITHM`:: + 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". + Git Commits ~~~~~~~~~~~ `GIT_AUTHOR_NAME`:: + The human-readable name used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.name` and + `author.name` configuration settings. + `GIT_AUTHOR_EMAIL`:: + The email address used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.email` and + `author.email` configuration settings. + `GIT_AUTHOR_DATE`:: + The date used for the author identity when creating commit or tag objects, or + when writing reflogs. See linkgit:git-commit[1] for valid formats. + `GIT_COMMITTER_NAME`:: + The human-readable name used in the committer identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.name` and + `committer.name` configuration settings. + `GIT_COMMITTER_EMAIL`:: + The email address used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.email` and + `committer.email` configuration settings. + `GIT_COMMITTER_DATE`:: -'EMAIL':: - see linkgit:git-commit-tree[1] + The date used for the committer identity when creating commit or tag objects, or + when writing reflogs. See linkgit:git-commit[1] for valid formats. + +`EMAIL`:: + The email address used in the author and committer identities if no other + relevant environment variable or configuration setting has been set. Git Diffs ~~~~~~~~~ @@ -522,6 +587,10 @@ other a pager. See also the `core.pager` option in linkgit:git-config[1]. +`GIT_PROGRESS_DELAY`:: + A number controlling how many seconds to delay before showing + optional progress indicators. Defaults to 2. + `GIT_EDITOR`:: This environment variable overrides `$EDITOR` and `$VISUAL`. It is used by several Git commands when, on interactive mode, @@ -536,7 +605,6 @@ other The command-line parameters passed to the configured command are determined by the ssh variant. See `ssh.variant` option in linkgit:git-config[1] for details. - + `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted by the shell, which allows additional arguments to be included. @@ -599,8 +667,8 @@ trace messages into this file descriptor. + Alternatively, if the variable is set to an absolute path (starting with a '/' character), Git will interpret this -as a file path and will try to write the trace messages -into it. +as a file path and will try to append the trace messages +to it. + Unsetting the variable, or setting it to empty, "0" or "false" (case insensitive) disables trace messages. @@ -661,6 +729,54 @@ of clones and fetches. When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump data (that is, only dump info lines and headers). +`GIT_TRACE2`:: + Enables more detailed trace messages from the "trace2" library. + Output from `GIT_TRACE2` is a simple text-based format for human + readability. ++ +If this variable is set to "1", "2" or "true" (comparison +is case insensitive), trace messages will be printed to +stderr. ++ +If the variable is set to an integer value greater than 2 +and lower than 10 (strictly) then Git will interpret this +value as an open file descriptor and will try to write the +trace messages into this file descriptor. ++ +Alternatively, if the variable is set to an absolute path +(starting with a '/' character), Git will interpret this +as a file path and will try to append the trace messages +to it. If the path already exists and is a directory, the +trace messages will be written to files (one per process) +in that directory, named according to the last component +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 +to open the path as a Unix Domain Socket. The socket type +can be either `stream` or `dgram`. ++ +Unsetting the variable, or setting it to empty, "0" or +"false" (case insensitive) disables trace messages. ++ +See link:technical/api-trace2.html[Trace2 documentation] +for full details. + + +`GIT_TRACE2_EVENT`:: + This setting writes a JSON-based format that is suited for machine + interpretation. + See `GIT_TRACE2` for available trace output options and + link:technical/api-trace2.html[Trace2 documentation] for full details. + +`GIT_TRACE2_PERF`:: + In addition to the text-based messages available in `GIT_TRACE2`, this + setting writes a column-based format for understanding nesting + regions. + See `GIT_TRACE2` for available trace output options and + link:technical/api-trace2.html[Trace2 documentation] for full details. + `GIT_REDACT_COOKIES`:: This can be set to a comma-separated list of strings. When a curl trace is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header @@ -858,7 +974,9 @@ Reporting Bugs Report bugs to the Git mailing list <git@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be -subscribed to the list to send a message there. +subscribed to the list to send a message there. See the list archive +at https://lore.kernel.org/git for previous bug reports and other +discussions. Issues which are security relevant should be disclosed privately to the Git Security mailing list <git-security@googlegroups.com>. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 92010b062e..2d0a03715b 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -18,7 +18,7 @@ A `gitattributes` file is a simple text file that gives Each line in `gitattributes` file is of form: - pattern attr1 attr2 ... + pattern attr1 attr2 ... That is, a pattern followed by an attributes list, separated by whitespaces. Leading and trailing whitespaces are @@ -112,7 +112,8 @@ Checking-out and checking-in These attributes affect how the contents stored in the repository are copied to the working tree files when commands -such as 'git checkout' and 'git merge' run. They also affect how +such as 'git switch', 'git checkout' and 'git merge' run. +They also affect how Git stores the contents you prepare in the working tree in the repository upon 'git add' and 'git commit'. @@ -124,7 +125,9 @@ 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 `core.autocrlf` overrides `core.eol` +Note that setting `core.autocrlf` to `true` or `input` overrides +`core.eol` (see the definitions of those options in +linkgit:git-config[1]). Set:: @@ -290,10 +293,10 @@ web front ends do not visualize the contents of these files by default. In these cases you can tell Git the encoding of a file in the working directory with the `working-tree-encoding` attribute. If a file with this -attribute is added to Git, then Git reencodes the content from the +attribute is added to Git, then Git re-encodes the content from the specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded content in its internal data structure (called "the index"). On checkout -the content is reencoded back to the specified encoding. +the content is re-encoded back to the specified encoding. Please note that using the `working-tree-encoding` attribute may have a number of pitfalls: @@ -303,21 +306,21 @@ number of pitfalls: attribute. If you decide to use the `working-tree-encoding` attribute in your repository, then it is strongly recommended to ensure that all clients working with the repository support it. - - For example, Microsoft Visual Studio resources files (`*.rc`) or - PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16. - If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with - a `working-tree-encoding` enabled Git client, then `foo.ps1` will be - stored as UTF-8 internally. A client without `working-tree-encoding` - support will checkout `foo.ps1` as UTF-8 encoded file. This will - typically cause trouble for the users of this file. - - If a Git client, that does not support the `working-tree-encoding` - attribute, adds a new file `bar.ps1`, then `bar.ps1` will be - stored "as-is" internally (in this example probably as UTF-16). - A client with `working-tree-encoding` support will interpret the - internal contents as UTF-8 and try to convert it to UTF-16 on checkout. - That operation will fail and cause an error. ++ +For example, Microsoft Visual Studio resources files (`*.rc`) or +PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16. +If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with +a `working-tree-encoding` enabled Git client, then `foo.ps1` will be +stored as UTF-8 internally. A client without `working-tree-encoding` +support will checkout `foo.ps1` as UTF-8 encoded file. This will +typically cause trouble for the users of this file. ++ +If a Git client that does not support the `working-tree-encoding` +attribute adds a new file `bar.ps1`, then `bar.ps1` will be +stored "as-is" internally (in this example probably as UTF-16). +A client with `working-tree-encoding` support will interpret the +internal contents as UTF-8 and try to convert it to UTF-16 on checkout. +That operation will fail and cause an error. - Reencoding content to non-UTF encodings can cause errors as the conversion might not be UTF-8 round trip safe. If you suspect your @@ -344,7 +347,9 @@ automatic line ending conversion based on your platform. Use the following attributes if your '*.ps1' files are UTF-16 little endian encoded without BOM and you want Git to use Windows line endings -in the working directory. Please note, it is highly recommended to +in the working directory (use `UTF-16LE-BOM` instead of `UTF-16LE` if +you want UTF-16 little endian with BOM). +Please note, it is highly recommended to explicitly define the line endings with `eol` if the `working-tree-encoding` attribute is used to avoid ambiguity. @@ -493,7 +498,7 @@ command. This is achieved by using the long-running process protocol When Git encounters the first file that needs to be cleaned or smudged, it starts the filter and performs the handshake. In the handshake, the welcome message sent by Git is "git-filter-client", only version 2 is -suppported, and the supported capabilities are "clean", "smudge", and +supported, and the supported capabilities are "clean", "smudge", and "delay". Afterwards Git sends a list of "key=value" pairs terminated with @@ -805,6 +810,10 @@ patterns are available: - `css` suitable for cascading style sheets. +- `dts` suitable for devicetree (DTS) files. + +- `elixir` suitable for source code in the Elixir language. + - `fortran` suitable for source code in the Fortran language. - `fountain` suitable for Fountain documents. @@ -815,7 +824,9 @@ patterns are available: - `java` suitable for source code in the Java language. -- `matlab` suitable for source code in the MATLAB language. +- `markdown` suitable for Markdown documents. + +- `matlab` suitable for source code in the MATLAB and Octave languages. - `objc` suitable for source code in the Objective-C language. @@ -829,6 +840,8 @@ patterns are available: - `ruby` suitable for source code in the Ruby language. +- `rust` suitable for source code in the Rust language. + - `tex` suitable for source code for LaTeX documents. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 592e06d839..92e4ba6a2f 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -37,6 +37,12 @@ arguments. Here are the rules: 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. + + * Because `--` disambiguates revisions and paths in some commands, it + cannot be used for those commands to separate options and revisions. + You can use `--end-of-options` for this (it also works for commands + that do not distinguish between revisions in paths, in which case it + is simply an alias for `--`). + When writing a script that is expected to handle random user-input, it is a good practice to make it explicit which arguments are which by placing @@ -47,8 +53,8 @@ disambiguating `--` at appropriate places. things: + -------------------------------- -$ git checkout -- *.c -$ git checkout -- \*.c +$ git restore *.c +$ git restore \*.c -------------------------------- + The former lets your shell expand the fileglob, and you are asking @@ -120,6 +126,11 @@ usage: git describe [<options>] <commit-ish>* --long always use long format --abbrev[=<n>] use <n> digits to display SHA-1s --------------------------------------------- ++ +Note that some subcommand (e.g. `git grep`) may behave differently +when there are things on the command line other than `-h`, but `git +subcmd -h` without anything else on the command line is meant to +consistently give the usage. --help-all:: Some Git commands take options that are only used for plumbing or that @@ -205,10 +216,22 @@ only affects the files in the working tree, but with entries, and with `--cached`, it modifies only the index entries. -See also http://marc.info/?l=git&m=116563135620359 and -http://marc.info/?l=git&m=119150393620273 for further +See also https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/ and +https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/ for further information. +Some other commands that also work on files in the working tree and/or +in the index can take `--staged` and/or `--worktree`. + +* `--staged` is exactly like `--cached`, which is used to ask a + command to only work on the index, not the working tree. + +* `--worktree` is the opposite, to ask a command to work on the + working tree only, not the index. + +* The two options can be specified together to ask a command to work + on both the index and the working tree. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index e29a9effcc..c0b95256cc 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -741,7 +741,7 @@ used earlier, and create a branch in it. You do that by simply just saying that you want to check out a new branch: ------------ -$ git checkout -b mybranch +$ git switch -c mybranch ------------ will create a new branch based at the current `HEAD` position, and switch @@ -751,11 +751,11 @@ to it. ================================================ If you make the decision to start your new branch at some other point in the history than the current `HEAD`, you can do so by -just telling 'git checkout' what the base of the checkout would be. +just telling 'git switch' what the base of the checkout would be. In other words, if you have an earlier tag or branch, you'd just do ------------ -$ git checkout -b mybranch earlier-commit +$ git switch -c mybranch earlier-commit ------------ and it would create the new branch `mybranch` at the earlier commit, @@ -765,7 +765,7 @@ and check out the state at that time. You can always just jump back to your original `master` branch by doing ------------ -$ git checkout master +$ git switch master ------------ (or any other branch-name, for that matter) and if you forget which @@ -794,7 +794,7 @@ $ git branch <branchname> [startingpoint] which will simply _create_ the branch, but will not do anything further. You can then later -- once you decide that you want to actually develop -on that branch -- switch to that branch with a regular 'git checkout' +on that branch -- switch to that branch with a regular 'git switch' with the branchname as the argument. @@ -808,7 +808,7 @@ being the same as the original `master` branch, let's make sure we're in that branch, and do some work there. ------------------------------------------------ -$ git checkout mybranch +$ git switch mybranch $ echo "Work, work, work" >>hello $ git commit -m "Some work." -i hello ------------------------------------------------ @@ -825,7 +825,7 @@ does some work in the original branch, and simulate that by going back to the master branch, and editing the same file differently there: ------------ -$ git checkout master +$ git switch master ------------ Here, take a moment to look at the contents of `hello`, and notice how they @@ -958,7 +958,7 @@ to the `master` branch. Let's go back to `mybranch`, and run 'git merge' to get the "upstream changes" back to your branch. ------------ -$ git checkout mybranch +$ git switch mybranch $ git merge -m "Merge upstream changes." master ------------ @@ -1133,9 +1133,8 @@ Remember, before running 'git merge', our `master` head was at work." commit. ------------ -$ git checkout mybranch -$ git reset --hard master^2 -$ git checkout master +$ git switch -C mybranch master^2 +$ git switch master $ git reset --hard master^ ------------ diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index f970196bc1..9e481aec85 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -131,7 +131,15 @@ context would not match: 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. +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>.*` +options. + +If the "pattern" URL does include a path component, then this too must match +exactly: the context `https://example.com/bar/baz.git` will match a config +entry for `https://example.com/bar/baz.git` (in addition to matching the config +entry for `https://example.com`) but will not match a config entry for +`https://example.com/bar`. CONFIGURATION OPTIONS @@ -180,8 +188,110 @@ CUSTOM HELPERS -------------- You can write your own custom helpers to interface with any system in -which you keep credentials. See the documentation for Git's -link:technical/api-credentials.html[credentials API] for details. +which you keep credentials. + +Credential helpers are programs executed by Git to fetch or save +credentials from and to long-term storage (where "long-term" is simply +longer than a single Git process; e.g., credentials may be stored +in-memory for a few minutes, or indefinitely on disk). + +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by Git into a command to be executed using +these rules: + + 1. If the helper string begins with "!", it is considered a shell + snippet, and everything after the "!" becomes the command. + + 2. Otherwise, if the helper string begins with an absolute path, the + verbatim helper string becomes the command. + + 3. Otherwise, the string "git credential-" is prepended to the helper + string, and the result becomes the command. + +The resulting command then has an "operation" argument appended to it +(see below for details), and the result is executed by the shell. + +Here are some example specifications: + +---------------------------------------------------- +# run "git credential-foo" +[credential] + helper = foo + +# same as above, but pass an argument to the helper +[credential] + helper = "foo --bar=baz" + +# the arguments are parsed by the shell, so use shell +# quoting if necessary +[credential] + helper = "foo --bar='whitespace arg'" + +# you can also use an absolute path, which will not use the git wrapper +[credential] + helper = "/path/to/my/helper --with-arguments" + +# or you can specify your own shell snippet +[credential "https://example.com"] + username = your_user + helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f" +---------------------------------------------------- + +Generally speaking, rule (3) above is the simplest for users to specify. +Authors of credential helpers should make an effort to assist their +users by naming their program "git-credential-$NAME", and putting it in +the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a +user to enable it with `git config credential.helper $NAME`. + +When a helper is executed, it will have one "operation" argument +appended to its command line, which is one of: + +`get`:: + + Return a matching credential, if any exists. + +`store`:: + + Store the credential, if applicable to the helper. + +`erase`:: + + Remove a matching credential, 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 +`git credential` plumbing command (see the section `INPUT/OUTPUT +FORMAT` in linkgit:git-credential[1] for a detailed specification). + +For a `get` operation, the helper should produce a list of attributes on +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. + +While it is possible to override all attributes, well behaving helpers +should refrain from doing so for any attribute other than username and +password. + +If a helper outputs a `quit` attribute with a value of `true` or `1`, +no further helpers will be consulted, nor will the user be prompted +(if no credential has been provided, the operation will then fail). + +Similarly, no more helpers will be consulted once both username and +password had been provided. + +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 a helper receives any other operation, it should silently ignore the +request. This leaves room for future operations to be added (older +helpers will just ignore the new requests). GIT --- diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index c0a60f3158..c970d9fe43 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -242,7 +242,8 @@ 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. +expensive. To speed things up binary files without textconv filters +will be ignored. When `-S` or `-G` are used without `--pickaxe-all`, only filepairs that match their respective criterion are kept in the output. When diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt index 9f2528fc8c..1bd919f92b 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt @@ -41,7 +41,7 @@ following commands. * linkgit:git-log[1] to see what happened. - * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch + * linkgit:git-switch[1] and linkgit:git-branch[1] to switch branches. * linkgit:git-add[1] to manage the index file. @@ -51,8 +51,7 @@ following commands. * linkgit:git-commit[1] to advance the current branch. - * linkgit:git-reset[1] and linkgit:git-checkout[1] (with - pathname parameters) to undo changes. + * linkgit:git-restore[1] to undo changes. * linkgit:git-merge[1] to merge between local branches. @@ -80,9 +79,9 @@ $ git tag v2.43 <2> Create a topic branch and develop.:: + ------------ -$ git checkout -b alsa-audio <1> +$ git switch -c alsa-audio <1> $ edit/compile/test -$ git checkout -- curses/ux_audio_oss.c <2> +$ git restore curses/ux_audio_oss.c <2> $ git add curses/ux_audio_alsa.c <3> $ edit/compile/test $ git diff HEAD <4> @@ -90,7 +89,7 @@ $ git commit -a -s <5> $ edit/compile/test $ git diff HEAD^ <6> $ git commit -a --amend <7> -$ git checkout master <8> +$ git switch master <8> $ git merge alsa-audio <9> $ git log --since='3 days ago' <10> $ git log v2.43.. curses/ <11> @@ -148,11 +147,11 @@ Clone the upstream and work on it. Feed changes to upstream.:: ------------ $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 $ cd my2.6 -$ git checkout -b mine master <1> +$ git switch -c mine master <1> $ edit/compile/test; git commit -a -s <2> $ git format-patch master <3> $ git send-email --to="person <email@example.com>" 00*.patch <4> -$ git checkout master <5> +$ git switch master <5> $ git pull <6> $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7> $ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8> @@ -194,7 +193,7 @@ satellite$ edit/compile/test/commit satellite$ git push origin <4> mothership$ cd frotz -mothership$ git checkout master +mothership$ git switch master mothership$ git merge satellite/master <5> ------------ + @@ -216,7 +215,7 @@ machine into the master branch. Branch off of a specific tag.:: + ------------ -$ git checkout -b private2.6.14 v2.6.14 <1> +$ git switch -c private2.6.14 v2.6.14 <1> $ edit/compile/test; git commit -a $ git checkout master $ git cherry-pick v2.6.14..private2.6.14 <2> @@ -274,14 +273,14 @@ $ mailx <3> & s 2 3 4 5 ./+to-apply & s 7 8 ./+hold-linus & q -$ git checkout -b topic/one master +$ git switch -c topic/one master $ git am -3 -i -s ./+to-apply <4> $ compile/test -$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5> -$ git checkout topic/one && git rebase master <6> -$ git checkout pu && git reset --hard next <7> +$ git switch -c hold/linus && git am -3 -i -s ./+hold-linus <5> +$ git switch topic/one && git rebase master <6> +$ git switch -C pu next <7> $ git merge topic/one topic/two && git merge hold/linus <8> -$ git checkout maint +$ git switch maint $ git cherry-pick master~4 <9> $ compile/test $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt new file mode 100644 index 0000000000..370d62dae4 --- /dev/null +++ b/Documentation/gitfaq.txt @@ -0,0 +1,355 @@ +gitfaq(7) +========= + +NAME +---- +gitfaq - Frequently asked questions about using Git + +SYNOPSIS +-------- +gitfaq + +DESCRIPTION +----------- + +The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`, +and a user, A U Thor, who has the account `author` on the hosting provider +`git.example.org`. + +Configuration +------------- + +[[user-name]] +What should I put in `user.name`?:: + You should put your personal name, generally a form using a given name + and family name. For example, the current maintainer of Git uses "Junio + C Hamano". This will be the name portion that is stored in every commit + you make. ++ +This configuration doesn't have any effect on authenticating to remote services; +for that, see `credential.username` in linkgit:git-config[1]. + +[[http-postbuffer]] +What does `http.postBuffer` really do?:: + This option changes the size of the buffer that Git uses when pushing + data to a remote over HTTP or HTTPS. If the data is larger than this + size, libcurl, which handles the HTTP support for Git, will use chunked + transfer encoding since it isn't known ahead of time what the size of + the pushed data will be. ++ +Leaving this value at the default size is fine unless you know that either the +remote server or a proxy in the middle doesn't support HTTP/1.1 (which +introduced the chunked transfer encoding) or is known to be broken with chunked +data. This is often (erroneously) suggested as a solution for generic push +problems, but since almost every server and proxy supports at least HTTP/1.1, +raising this value usually doesn't solve most push problems. A server or proxy +that didn't correctly support HTTP/1.1 and chunked transfer encoding wouldn't be +that useful on the Internet today, since it would break lots of traffic. ++ +Note that increasing this value will increase the memory used on every relevant +push that Git does over HTTP or HTTPS, since the entire buffer is allocated +regardless of whether or not it is all used. Thus, it's best to leave it at the +default unless you are sure you need a different value. + +[[configure-editor]] +How do I configure a different editor?:: + If you haven't specified an editor specifically for Git, it will by default + use the editor you've configured using the `VISUAL` or `EDITOR` environment + variables, or if neither is specified, the system default (which is usually + `vi`). Since some people find `vi` difficult to use or prefer a different + editor, it may be desirable to change the editor used. ++ +If you want to configure a general editor for most programs which need one, you +can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain +a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate +value. For example, if you prefer the editor `nano`, then you could write the +following: ++ +---- +export VISUAL=nano +---- ++ +If you want to configure an editor specifically for Git, you can either set the +`core.editor` configuration value or the `GIT_EDITOR` environment variable. You +can see linkgit:git-var[1] for details on the order in which these options are +consulted. ++ +Note that in all cases, the editor value will be passed to the shell, so any +arguments containing spaces should be appropriately quoted. Additionally, if +your editor normally detaches from the terminal when invoked, you should specify +it with an argument that makes it not do that, or else Git will not see any +changes. An example of a configuration addressing both of these issues on +Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`, +which quotes the filename with spaces and specifies the `--nofork` option to +avoid backgrounding the process. + +Credentials +----------- + +[[http-credentials]] +How do I specify my credentials when pushing over HTTP?:: + The easiest way to do this is to use a credential helper via the + `credential.helper` configuration. Most systems provide a standard + choice to integrate with the system credential manager. For example, + Git for Windows provides the `wincred` credential manager, macOS has the + `osxkeychain` credential manager, and Unix systems with a standard + desktop environment can use the `libsecret` credential manager. All of + these store credentials in an encrypted store to keep your passwords or + tokens secure. ++ +In addition, you can use the `store` credential manager which stores in a file +in your home directory, or the `cache` credential manager, which does not +permanently store your credentials, but does prevent you from being prompted for +them for a certain period of time. ++ +You can also just enter your password when prompted. While it is possible to +place the password (which must be percent-encoded) in the URL, this is not +particularly secure and can lead to accidental exposure of credentials, so it is +not recommended. + +[[http-credentials-environment]] +How do I read a password or token from an environment variable?:: + The `credential.helper` configuration option can also take an arbitrary + shell command that produces the credential protocol on standard output. + This is useful when passing credentials into a container, for example. ++ +Such a shell command can be specified by starting the option value with an +exclamation point. If your password or token were stored in the `GIT_TOKEN`, +you could run the following command to set your credential helper: ++ +---- +$ git config credential.helper \ + '!f() { echo username=author; echo "password=$GIT_TOKEN"; };f' +---- + +[[http-reset-credentials]] +How do I change the password or token I've saved in my credential manager?:: + Usually, if the password or token is invalid, Git will erase it and + prompt for a new one. However, there are times when this doesn't always + happen. To change the password or token, you can erase the existing + credentials and then Git will prompt for new ones. To erase + credentials, use a syntax like the following (substituting your username + and the hostname): ++ +---- +$ echo url=https://author@git.example.org | git credential reject +---- + +[[multiple-accounts-http]] +How do I use multiple accounts with the same hosting provider using HTTP?:: + Usually the easiest way to distinguish between these accounts is to use + the username in the URL. For example, if you have the accounts `author` + and `committer` on `git.example.org`, you can use the URLs + https://author@git.example.org/org1/project1.git and + https://committer@git.example.org/org2/project2.git. This way, when you + use a credential helper, it will automatically try to look up the + correct credentials for your account. If you already have a remote set + up, you can change the URL with something like `git remote set-url + origin https://author@git.example.org/org1/project1.git` (see + linkgit:git-remote[1] for details). + +[[multiple-accounts-ssh]] +How do I use multiple accounts with the same hosting provider using SSH?:: + With most hosting providers that support SSH, a single key pair uniquely + identifies a user. Therefore, to use multiple accounts, it's necessary + to create a key pair for each account. If you're using a reasonably + modern OpenSSH version, you can create a new key pair with something + like `ssh-keygen -t ed25519 -f ~/.ssh/id_committer`. You can then + register the public key (in this case, `~/.ssh/id_committer.pub`; note + the `.pub`) with the hosting provider. ++ +Most hosting providers use a single SSH account for pushing; that is, all users +push to the `git` account (e.g., `git@git.example.org`). If that's the case for +your provider, you can set up multiple aliases in SSH to make it clear which key +pair to use. For example, you could write something like the following in +`~/.ssh/config`, substituting the proper private key file: ++ +---- +# This is the account for author on git.example.org. +Host example_author + HostName git.example.org + User git + # This is the key pair registered for author with git.example.org. + IdentityFile ~/.ssh/id_author + IdentitiesOnly yes +# This is the account for committer on git.example.org. +Host example_committer + HostName git.example.org + User git + # This is the key pair registered for committer with git.example.org. + IdentityFile ~/.ssh/id_committer + IdentitiesOnly yes +---- ++ +Then, you can adjust your push URL to use `git@example_author` or +`git@example_committer` instead of `git@example.org` (e.g., `git remote set-url +git@example_author:org1/project1.git`). + +Common Issues +------------- + +[[last-commit-amend]] +I've made a mistake in the last commit. How do I change it?:: + You can make the appropriate change to your working tree, run `git add + <file>` or `git rm <file>`, as appropriate, to stage it, and then `git + commit --amend`. Your change will be included in the commit, and you'll + be prompted to edit the commit message again; if you wish to use the + original message verbatim, you can use the `--no-edit` option to `git + commit` in addition, or just save and quit when your editor opens. + +[[undo-previous-change]] +I've made a change with a bug and it's been included in the main branch. How should I undo it?:: + The usual way to deal with this is to use `git revert`. This preserves + the history that the original change was made and was a valuable + contribution, but also introduces a new commit that undoes those changes + because the original had a problem. The commit message of the revert + indicates the commit which was reverted and is usually edited to include + an explanation as to why the revert was made. + +[[ignore-tracked-files]] +How do I ignore changes to a tracked file?:: + Git doesn't provide a way to do this. The reason is that if Git needs + to overwrite this file, such as during a checkout, it doesn't know + whether the changes to the file are precious and should be kept, or + whether they are irrelevant and can safely be destroyed. Therefore, it + has to take the safe route and always preserve them. ++ +It's tempting to try to use certain features of `git update-index`, namely the +assume-unchanged and skip-worktree bits, but these don't work properly for this +purpose and shouldn't be used this way. ++ +If your goal is to modify a configuration file, it can often be helpful to have +a file checked into the repository which is a template or set of defaults which +can then be copied alongside and modified as appropriate. This second, modified +file is usually ignored to prevent accidentally committing it. + +[[files-in-.gitignore-are-tracked]] +I asked Git to ignore various files, yet they are still tracked:: + A `gitignore` file ensures that certain file(s) which are not + tracked by Git remain untracked. However, sometimes particular + file(s) may have been tracked before adding them into the + `.gitignore`, hence they still remain tracked. To untrack and + ignore files/patterns, use `git rm --cached <file/pattern>` + and add a pattern to `.gitignore` that matches the <file>. + See linkgit:gitignore[5] for details. + +[[fetching-and-pulling]] +How do I know if I want to do a fetch or a pull?:: + A fetch stores a copy of the latest changes from the remote + repository, without modifying the working tree or current branch. + You can then at your leisure inspect, merge, rebase on top of, or + ignore the upstream changes. A pull consists of a fetch followed + immediately by either a merge or rebase. See linkgit:git-pull[1]. + +Hooks +----- + +[[restrict-with-hooks]] +How do I use hooks to prevent users from making certain changes?:: + The only safe place to make these changes is on the remote repository + (i.e., the Git server), usually in the `pre-receive` hook or in a + continuous integration (CI) system. These are the locations in which + policy can be enforced effectively. ++ +It's common to try to use `pre-commit` hooks (or, for commit messages, +`commit-msg` hooks) to check these things, which is great if you're working as a +solo developer and want the tooling to help you. However, using hooks on a +developer machine is not effective as a policy control because a user can bypass +these hooks with `--no-verify` without being noticed (among various other ways). +Git assumes that the user is in control of their local repositories and doesn't +try to prevent this or tattle on the user. ++ +In addition, some advanced users find `pre-commit` hooks to be an impediment to +workflows that use temporary commits to stage work in progress or that create +fixup commits, so it's better to push these kinds of checks to the server +anyway. + +Cross-Platform Issues +--------------------- + +[[windows-text-binary]] +I'm on Windows and my text files are detected as binary.:: + Git works best when you store text files as UTF-8. Many programs on + Windows support UTF-8, but some do not and only use the little-endian + UTF-16 format, which Git detects as binary. If you can't use UTF-8 with + your programs, you can specify a working tree encoding that indicates + which encoding your files should be checked out with, while still + storing these files as UTF-8 in the repository. This allows tools like + linkgit:git-diff[1] to work as expected, while still allowing your tools + to work. ++ +To do so, you can specify a linkgit:gitattributes[5] pattern with the +`working-tree-encoding` attribute. For example, the following pattern sets all +C files to use UTF-16LE-BOM, which is a common encoding on Windows: ++ +---- +*.c working-tree-encoding=UTF-16LE-BOM +---- ++ +You will need to run `git add --renormalize` to have this take effect. Note +that if you are making these changes on a project that is used across platforms, +you'll probably want to make it in a per-user configuration file or in the one +in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in the +repository will apply to all users of the repository. ++ +See the following entry for information about normalizing line endings as well, +and see linkgit:gitattributes[5] for more information about attribute files. + +[[windows-diff-control-m]] +I'm on Windows and git diff shows my files as having a `^M` at the end.:: + By default, Git expects files to be stored with Unix line endings. As such, + the carriage return (`^M`) that is part of a Windows line ending is shown + because it is considered to be trailing whitespace. Git defaults to showing + trailing whitespace only on new lines, not existing ones. ++ +You can store the files in the repository with Unix line endings and convert +them automatically to your platform's line endings. To do that, set the +configuration option `core.eol` to `native` and see the following entry for +information about how to configure files as text or binary. ++ +You can also control this behavior with the `core.whitespace` setting if you +don't wish to remove the carriage returns from your line endings. + +[[recommended-storage-settings]] +What's the recommended way to store files in Git?:: + While Git can store and handle any file of any type, there are some + settings that work better than others. In general, we recommend that + text files be stored in UTF-8 without a byte-order mark (BOM) with LF + (Unix-style) endings. We also recommend the use of UTF-8 (again, + without BOM) in commit messages. These are the settings that work best + across platforms and with tools such as `git diff` and `git merge`. ++ +Additionally, if you have a choice between storage formats that are text based +or non-text based, we recommend storing files in the text format and, if +necessary, transforming them into the other format. For example, a text-based +SQL dump with one record per line will work much better for diffing and merging +than an actual database file. Similarly, text-based formats such as Markdown +and AsciiDoc will work better than binary formats such as Microsoft Word and +PDF. ++ +Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or +build products in the repository is generally not recommended. Dependencies and +build products are best stored on an artifact or package server with only +references, URLs, and hashes stored in the repository. ++ +We also recommend setting a linkgit:gitattributes[5] file to explicitly mark +which files are text and which are binary. If you want Git to guess, you can +set the attribute `text=auto`. For example, the following might be appropriate +in some projects: ++ +---- +# By default, guess. +* text=auto +# Mark all C files as text. +*.c text +# Mark all JPEG files as binary. +*.jpg binary +---- ++ +These settings help tools pick the right format for output such as patches and +result in files being checked out in the appropriate line ending for the +platform. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 959044347e..81f2a87e88 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -99,6 +99,32 @@ All the `git commit` hooks are invoked with the environment variable `GIT_EDITOR=:` if the command will not bring up an editor to modify the commit message. +The default 'pre-commit' hook, when enabled--and with the +`hooks.allownonascii` config option unset or set to false--prevents +the use of non-ASCII filenames. + +pre-merge-commit +~~~~~~~~~~~~~~~~ + +This hook is invoked by linkgit:git-merge[1], and can be bypassed +with the `--no-verify` option. It takes no parameters, and is +invoked after the merge has been carried out successfully and before +obtaining the proposed commit log message to +make a commit. Exiting with a non-zero status from this script +causes the `git merge` command to abort before creating a commit. + +The default 'pre-merge-commit' hook, when enabled, runs the +'pre-commit' hook, if the latter is enabled. + +This hook is invoked with the environment variable +`GIT_EDITOR=:` if the command will not bring up an editor +to modify the commit message. + +If the merge cannot be carried out automatically, the conflicts +need to be resolved and the result committed separately (see +linkgit:git-merge[1]). At that point, this hook will not be executed, +but the 'pre-commit' hook will, if it is enabled. + prepare-commit-msg ~~~~~~~~~~~~~~~~~~ @@ -161,12 +187,13 @@ rebased, and is not set when rebasing the current branch. post-checkout ~~~~~~~~~~~~~ -This hook is invoked when a linkgit:git-checkout[1] is run after having updated the +This hook is invoked when a linkgit:git-checkout[1] or +linkgit:git-switch[1] is run after having updated the worktree. The hook is given three parameters: the ref of the previous HEAD, the ref of the new HEAD (which may or may not have changed), and a flag indicating whether the checkout was a branch checkout (changing branches, flag=1) or a file checkout (retrieving a file from the index, flag=0). -This hook cannot affect the outcome of `git checkout`. +This hook cannot affect the outcome of `git switch` or `git checkout`. It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is used. The first parameter given to the hook is the null-ref, the second the @@ -402,7 +429,8 @@ exit with a zero status. For example, the hook can simply run `git read-tree -u -m HEAD "$1"` in order to emulate `git fetch` that is run in the reverse direction with `git push`, as the two-tree form of `git read-tree -u -m` is -essentially the same as `git checkout` that switches branches while +essentially the same as `git switch` or `git checkout` +that switches branches while keeping the local changes in the working tree that do not interfere with the difference between the branches. @@ -419,10 +447,12 @@ post-rewrite This hook is invoked by commands that rewrite commits (linkgit:git-commit[1] when called with `--amend` and -linkgit:git-rebase[1]; currently `git filter-branch` does 'not' call -it!). Its first argument denotes the command it was invoked by: -currently one of `amend` or `rebase`. Further command-dependent -arguments may be passed in the future. +linkgit:git-rebase[1]; however, full-history (re)writing tools like +linkgit:git-fast-import[1] or +https://github.com/newren/git-filter-repo[git-filter-repo] typically +do not call it!). Its first argument denotes the command it was +invoked by: currently one of `amend` or `rebase`. Further +command-dependent arguments may be passed in the future. The hook receives a list of the rewritten commits on stdin, in the format @@ -460,9 +490,16 @@ fsmonitor-watchman ~~~~~~~~~~~~~~~~~~ This hook is invoked when the configuration option `core.fsmonitor` is -set to `.git/hooks/fsmonitor-watchman`. It takes two arguments, a version -(currently 1) and the time in elapsed nanoseconds since midnight, -January 1, 1970. +set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2` +depending on the version of the hook to use. + +Version 1 takes two arguments, a version (1) and the time in elapsed +nanoseconds since midnight, January 1, 1970. + +Version 2 takes two arguments, a version (2) and a token that is used +for identifying changes since the token. For watchman this would be +a clock id. This version must output to stdout the new token followed +by a NUL before the list of files. The hook should output to stdout the list of all files in the working directory that may have changed since the requested time. The logic @@ -485,12 +522,79 @@ The exit status determines whether git will use the data from the hook to limit its search. On error, it will fall back to verifying all files and folders. +p4-changelist +~~~~~~~~~~~~~ + +This hook is invoked by `git-p4 submit`. + +The `p4-changelist` hook is executed after the changelist +message has been edited by the user. It can be bypassed with the +`--no-verify` option. It takes a single parameter, the name +of the file that holds the proposed changelist text. Exiting +with a non-zero status causes the command to abort. + +The hook is allowed to edit the changelist file and can be used +to normalize the text into some project standard format. It can +also be used to refuse the Submit after inspect the message file. + +Run `git-p4 submit --help` for details. + +p4-prepare-changelist +~~~~~~~~~~~~~~~~~~~~~ + +This hook is invoked by `git-p4 submit`. + +The `p4-prepare-changelist` hook is executed right after preparing +the default changelist message and before the editor is started. +It takes one parameter, the name of the file that contains the +changelist text. Exiting with a non-zero status from the script +will abort the process. + +The purpose of the hook is to edit the message file in place, +and it is not supressed by the `--no-verify` option. This hook +is called even if `--prepare-p4-only` is set. + +Run `git-p4 submit --help` for details. + +p4-post-changelist +~~~~~~~~~~~~~~~~~~ + +This hook is invoked by `git-p4 submit`. + +The `p4-post-changelist` hook is invoked after the submit has +successfully occured in P4. It takes no parameters and is meant +primarily for notification and cannot affect the outcome of the +git p4 submit action. + +Run `git-p4 submit --help` for details. + p4-pre-submit ~~~~~~~~~~~~~ This hook is invoked by `git-p4 submit`. It takes no parameters and nothing from standard input. Exiting with non-zero status from this script prevent -`git-p4 submit` from launching. Run `git-p4 submit --help` for details. +`git-p4 submit` from launching. It can be bypassed with the `--no-verify` +command line option. Run `git-p4 submit --help` for details. + + + +post-index-change +~~~~~~~~~~~~~~~~~ + +This hook is invoked when the index is written in read-cache.c +do_write_locked_index. + +The first parameter passed to the hook is the indicator for the +working directory being updated. "1" meaning working directory +was updated or "0" when the working directory was not updated. + +The second parameter passed to the hook is the indicator for whether +or not the index was updated and the skip-worktree bit could have +changed. "1" meaning skip-worktree bits could have been updated +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. GIT --- diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index d107daaffd..d47b1ae296 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -89,28 +89,28 @@ PATTERN FORMAT Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". - - If the pattern ends with a slash, it is removed for the - purpose of the following description, but it would only find - a match with a directory. In other words, `foo/` will match a - directory `foo` and paths underneath it, but will not match a - regular file or a symbolic link `foo` (this is consistent - with the way how pathspec works in general in Git). - - - If the pattern does not contain a slash '/', Git treats it as - a shell glob pattern and checks for a match against the - pathname relative to the location of the `.gitignore` file - (relative to the toplevel of the work tree if not from a - `.gitignore` file). - - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches - anything except "`/`", "`?`" matches any one character except "`/`" - and "`[]`" matches one character in a selected range. See - fnmatch(3) and the FNM_PATHNAME flag for a more detailed - description. - - - A leading slash matches the beginning of the pathname. - For example, "/{asterisk}.c" matches "cat-file.c" but not - "mozilla-sha1/sha1.c". + - 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 + pattern, then the pattern is relative to the directory level of the + particular `.gitignore` file itself. Otherwise the pattern may also + match at any level below the `.gitignore` level. + + - If there is a separator at the end of the pattern then the pattern + will only match directories, otherwise the pattern can match both + files and directories. + + - For example, a pattern `doc/frotz/` matches `doc/frotz` directory, + but not `a/doc/frotz` directory; however `frotz/` matches `frotz` + and `a/frotz` that is a directory (all paths are relative from + the `.gitignore` file). + + - An asterisk "`*`" matches anything except a slash. + The character "`?`" matches any one character except "`/`". + The range notation, e.g. `[a-zA-Z]`, can be used to match + one of the characters in a range. See fnmatch(3) and the + FNM_PATHNAME flag for a more detailed description. Two consecutive asterisks ("`**`") in patterns matched against full pathname may have special meaning: @@ -129,7 +129,16 @@ full pathname may have special meaning: matches zero or more directories. For example, "`a/**/b`" matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on. - - Other consecutive asterisks are considered invalid. + - Other consecutive asterisks are considered regular asterisks and + will match according to the previous rules. + +CONFIGURATION +------------- + +The optional configuration variable `core.excludesFile` indicates a path to a +file containing patterns of file names to exclude, similar to +`$GIT_DIR/info/exclude`. Patterns in the exclude file are used in addition to +those in `$GIT_DIR/info/exclude`. NOTES ----- @@ -143,6 +152,28 @@ To stop tracking a file that is currently tracked, use EXAMPLES -------- + - The pattern `hello.*` matches any file or folder + 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.*`; + the pattern now matches `hello.txt`, `hello.c` but not + `a/hello.java`. + + - The pattern `foo/` will match a directory `foo` and + paths underneath it, but will not match a regular file + or a symbolic link `foo` (this is consistent with the + way how pathspec works in general in Git) + + - The pattern `doc/frotz` and `/doc/frotz` have the same effect + in any `.gitignore` file. In other words, a leading slash + 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. + -------------------------------------------------------------- $ git status [...] diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 244cd01493..c653ebb6a8 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -105,8 +105,12 @@ linkgit:git-rev-list[1] for a complete list. (or the function name regex <funcname>) within the <file>. You may not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only - give zero or one positive revision arguments. - You can specify this option more than once. + give zero or one positive revision arguments, and + <start> and <end> (or <funcname>) must exist in the starting revision. + You can specify this option more than once. Implies `--patch`. + Patch output can be suppressed using `--no-patch`, but other diff formats + (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`, + `--name-only`, `--name-status`, `--check`) are not currently implemented. + *Note:* gitk (unlike linkgit:git-log[1]) currently only understands this option if you specify it "glued together" with its argument. Do @@ -168,12 +172,12 @@ Files ----- User configuration and preferences are stored at: -* '$XDG_CONFIG_HOME/git/gitk' if it exists, otherwise -* '$HOME/.gitk' if it exists +* `$XDG_CONFIG_HOME/git/gitk` if it exists, otherwise +* `$HOME/.gitk` if it exists -If neither of the above exist then '$XDG_CONFIG_HOME/git/gitk' is created and +If neither of the above exist then `$XDG_CONFIG_HOME/git/gitk` is created and used by default. If '$XDG_CONFIG_HOME' is not set it defaults to -'$HOME/.config' in all cases. +`$HOME/.config` in all cases. History ------- diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 4d63def206..67275fd187 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -44,9 +44,8 @@ submodule.<name>.update:: 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. Note that the - '!command' form is intentionally ignored here for security - reasons. + linkgit:git-submodule[1] for their meaning. For security + reasons, the '!command' form is not accepted here. submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. @@ -67,7 +66,8 @@ submodule.<name>.fetchRecurseSubmodules:: submodule.<name>.ignore:: Defines under what circumstances "git status" and the diff family show a submodule as modified. The following values are supported: - ++ +-- all;; The submodule will never be considered modified (but will nonetheless show up in the output of status and commit when it has been staged). @@ -80,16 +80,18 @@ submodule.<name>.ignore:: Committed differences and modifications to tracked files will show up. - none;; No modifiations to submodules are ignored, all of committed + none;; No modifications to submodules are ignored, all of committed differences, and modifications to tracked and untracked files are shown. This is the default option. - If this option is also present in the submodules entry in .git/config - of the superproject, the setting there will override the one found in - .gitmodules. - Both settings can be overridden on the command line by using the - "--ignore-submodule" option. The 'git submodule' commands are not - affected by this setting. +If this option is also present in the submodules entry in .git/config +of the superproject, the setting there will override the one found in +.gitmodules. + +Both settings can be overridden on the command line by using the +"--ignore-submodules" option. The 'git submodule' commands are not +affected by this setting. +-- submodule.<name>.shallow:: When set to true, a clone of this submodule will be performed as a @@ -102,22 +104,23 @@ EXAMPLES Consider the following .gitmodules file: - [submodule "libfoo"] - path = include/foo - url = git://foo.com/git/lib.git - - [submodule "libbar"] - path = include/bar - url = git://bar.com/git/lib.git +---- +[submodule "libfoo"] + path = include/foo + url = git://foo.com/git/lib.git +[submodule "libbar"] + path = include/bar + url = git://bar.com/git/lib.git +---- This defines two submodules, `libfoo` and `libbar`. These are expected to -be checked out in the paths 'include/foo' and 'include/bar', and for both +be checked out in the paths `include/foo` and `include/bar`, and for both submodules a URL is specified which can be used for cloning the submodules. SEE ALSO -------- -linkgit:git-submodule[1] linkgit:git-config[1] +linkgit:git-submodule[1], linkgit:gitsubmodules[7], linkgit:git-config[1] GIT --- diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 9d1459aac6..f48a031dc3 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -1,4 +1,4 @@ -gitremote-helpers(1) +gitremote-helpers(7) ==================== NAME @@ -297,9 +297,13 @@ Supported if the helper has the "option" capability. same batch are complete. Only objects which were reported in the output of 'list' with a sha1 may be fetched this way. + -Optionally may output a 'lock <file>' line indicating a file under -GIT_DIR/objects/pack which is keeping a pack until refs can be -suitably updated. +Optionally may output a 'lock <file>' line indicating the full path of +a file under `$GIT_DIR/objects/pack` which is keeping a pack until +refs can be suitably updated. The path must end with `.keep`. This is +a mechanism to name a <pack,idx,keep> tuple by giving only the keep +component. The kept pack will not be deleted by a concurrent repack, +even though its objects may not be referenced until the fetch completes. +The `.keep` file will be deleted at the conclusion of the fetch. + If option 'check-connectivity' is requested, the helper must output 'connectivity-ok' if the clone is self-contained and connected. @@ -468,7 +472,7 @@ set by Git if the remote helper has the 'option' capability. 'option dry-run' {'true'|'false'}: If true, pretend the operation completed successfully, - but don't actually change any repository data. For most + but don't actually change any repository data. For most helpers this only applies to the 'push', if supported. 'option servpath <c-style-quoted-path>':: @@ -505,6 +509,11 @@ set by Git if the remote helper has the 'option' capability. Indicate that only the objects wanted need to be fetched, not their dependents. +'option atomic' {'true'|'false'}:: + When pushing, request the remote server to update refs in a single atomic + transaction. If successful, all refs will be updated, or none will. If the + remote side does not support this capability, the push will fail. + SEE ALSO -------- linkgit:git-remote[1] @@ -513,8 +522,6 @@ linkgit:git-remote-ext[1] linkgit:git-remote-fd[1] -linkgit:git-remote-testgit[1] - linkgit:git-fast-import[1] GIT diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index e85148f05e..1a2ef4c150 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -59,7 +59,7 @@ objects/[0-9a-f][0-9a-f]:: here are often called 'unpacked' (or 'loose') objects. objects/pack:: - Packs (files that store many object in compressed form, + Packs (files that store many objects in compressed form, along with index files to allow them to be randomly accessed) are found in this directory. @@ -84,7 +84,7 @@ objects/info/alternates:: to the object database, not to the repository!) in your alternates file, but it will not work if you use absolute paths unless the absolute path in filesystem and web URL - is the same. See also 'objects/info/http-alternates'. + is the same. See also `objects/info/http-alternates`. objects/info/http-alternates:: This file records URLs to alternate object stores that @@ -95,8 +95,10 @@ refs:: References are stored in subdirectories of this directory. The 'git prune' command knows to preserve objects reachable from refs found in this directory and - its subdirectories. This directory is ignored if $GIT_COMMON_DIR - is set and "$GIT_COMMON_DIR/refs" will be used instead. + its subdirectories. + This directory is ignored (except refs/bisect, + refs/rewritten and refs/worktree) if $GIT_COMMON_DIR is + set and "$GIT_COMMON_DIR/refs" will be used instead. refs/heads/`name`:: records tip-of-the-tree commit objects of branch `name` @@ -143,6 +145,11 @@ config:: if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be used instead. +config.worktree:: + Working directory specific configuration file for the main + working directory in multiple working directory setup (see + linkgit:git-worktree[1]). + branches:: A slightly deprecated way to store shorthands to be used to specify a URL to 'git fetch', 'git pull' and 'git push'. @@ -165,6 +172,11 @@ hooks:: each hook. This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/hooks" will be used instead. +common:: + When multiple working trees are used, most of files in + $GIT_DIR are per-worktree with a few known exceptions. All + files under 'common' however will be shared between all + working trees. index:: The current index file for the repository. It is @@ -228,8 +240,8 @@ remotes:: logs:: Records of changes made to refs are stored in this directory. See linkgit:git-update-ref[1] for more information. This - directory is ignored if $GIT_COMMON_DIR is set and - "$GIT_COMMON_DIR/logs" will be used instead. + directory is ignored (except logs/HEAD) if $GIT_COMMON_DIR is + set and "$GIT_COMMON_DIR/logs" will be used instead. logs/refs/heads/`name`:: Records all changes made to the branch tip named `name`. @@ -275,6 +287,11 @@ worktrees/<id>/locked:: or manually by `git worktree prune`. The file may contain a string explaining why the repository is locked. +worktrees/<id>/config.worktree:: + Working directory specific configuration file. + +include::technical/repository-version.txt[] + SEE ALSO -------- linkgit:git-init[1], diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt index 1f6cceaefb..d407b7dee1 100644 --- a/Documentation/gitrevisions.txt +++ b/Documentation/gitrevisions.txt @@ -19,9 +19,10 @@ walk the revision graph (such as linkgit:git-log[1]), all commits which are reachable from that commit. For commands that walk the revision graph one can also specify a range of revisions explicitly. -In addition, some Git commands (such as linkgit:git-show[1]) also take -revision parameters which denote other objects than commits, e.g. blobs -("files") or trees ("directories of files"). +In addition, some Git commands (such as linkgit:git-show[1] and +linkgit:git-push[1]) can also take revision parameters which denote +other objects than commits, e.g. blobs ("files") or trees +("directories of files"). include::revisions.txt[] diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index 504c5f1a88..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -3,7 +3,7 @@ gitsubmodules(7) NAME ---- -gitsubmodules - mounting one repository inside another +gitsubmodules - Mounting one repository inside another SYNOPSIS -------- @@ -169,11 +169,15 @@ ACTIVE SUBMODULES A submodule is considered active, - (a) if `submodule.<name>.active` is set to `true` - or - (b) if the submodule's path matches the pathspec in `submodule.active` - or - (c) if `submodule.<name>.url` is set. + 1. if `submodule.<name>.active` is set to `true` ++ +or + + 2. if the submodule's path matches the pathspec in `submodule.active` ++ +or + + 3. if `submodule.<name>.url` is set. and these are evaluated in this order. @@ -189,11 +193,11 @@ For example: url = https://example.org/baz In the above config only the submodule 'bar' and 'baz' are active, -'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because -(a) takes precedence over (c) +'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because +(1) takes precedence over (3) -Note that (c) is a historical artefact and will be ignored if the -(a) and (b) specify that the submodule is not active. In other words, +Note that (3) is a historical artefact and will be ignored if the +(1) and (2) specify that the submodule is not active. In other words, if we have a `submodule.<name>.active` set to `false` or if the submodule's path is excluded in the pathspec in `submodule.active`, the url doesn't matter whether it is present or not. This is illustrated in @@ -267,7 +271,8 @@ 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. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index e0976f6017..8bdb7d0bd3 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -370,13 +370,13 @@ situation: $ git status On branch master Changes to be committed: - (use "git reset HEAD <file>..." to unstage) + (use "git restore --staged <file>..." to unstage) new file: closing.txt Changes not staged for commit: (use "git add <file>..." to update what will be committed) - (use "git checkout -- <file>..." to discard changes in working directory) + (use "git restore <file>..." to discard changes in working directory) modified: file.txt diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 242de31cb6..59ef5cef1f 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -110,7 +110,7 @@ $ git status On branch master Changes to be committed: Your branch is up to date with 'origin/master'. - (use "git reset HEAD <file>..." to unstage) + (use "git restore --staged <file>..." to unstage) modified: file1 modified: file2 @@ -207,7 +207,7 @@ automatically. The asterisk marks the branch you are currently on; type ------------------------------------------------ -$ git checkout experimental +$ git switch experimental ------------------------------------------------ to switch to the experimental branch. Now edit a file, commit the @@ -216,7 +216,7 @@ change, and switch back to the master branch: ------------------------------------------------ (edit file) $ git commit -a -$ git checkout master +$ git switch master ------------------------------------------------ Check that the change you made is no longer visible, since it was diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 9c8982ec98..7963a79ba9 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -19,10 +19,12 @@ end of a line is ignored. See *perlsyn*(1) for details. An example: - # gitweb configuration file for http://git.example.org - # - our $projectroot = "/srv/git"; # FHS recommendation - our $site_name = 'Example.org >> Repos'; +------------------------------------------------ +# gitweb configuration file for http://git.example.org +# +our $projectroot = "/srv/git"; # FHS recommendation +our $site_name = 'Example.org >> Repos'; +------------------------------------------------ The configuration file is used to override the default settings that @@ -48,11 +50,11 @@ following order: * built-in values (some set during build stage), * common system-wide configuration file (defaults to - '/etc/gitweb-common.conf'), + `/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 - then fallback system-wide configuration file (defaults to '/etc/gitweb.conf'). + then fallback system-wide configuration file (defaults to `/etc/gitweb.conf`). Values obtained in later configuration files override values obtained earlier in the above sequence. @@ -80,7 +82,7 @@ You can include other configuration file using read_config_file() subroutine. For example, one might want to put gitweb configuration related to access control for viewing repositories via Gitolite (one of Git repository management tools) in a separate file, e.g. in -'/etc/gitweb-gitolite.conf'. To include it, put +`/etc/gitweb-gitolite.conf`. To include it, put -------------------------------------------------- read_config_file("/etc/gitweb-gitolite.conf"); @@ -140,7 +142,7 @@ and its path_info based equivalent http://git.example.com/gitweb.cgi/foo/bar.git ------------------------------------------------ + -will map to the path '/srv/git/foo/bar.git' on the filesystem. +will map to the path `/srv/git/foo/bar.git` on the filesystem. $projects_list:: Name of a plain text file listing projects, or a name of directory @@ -205,8 +207,8 @@ subsection on linkgit:gitweb[1] manpage. $strict_export:: Only allow viewing of repositories also shown on the overview page. - This for example makes `$gitweb_export_ok` file decide if repository is - available and not only if it is shown. If `$gitweb_list` points to + This for example makes `$export_ok` file decide if repository is + available and not only if it is shown. If `$projects_list` points to file with list of project, only those repositories listed would be available for gitweb. Can be set during building gitweb via `GITWEB_STRICT_EXPORT`. By default this variable is not set, which @@ -232,9 +234,9 @@ $GIT:: $mimetypes_file:: File to use for (filename extension based) guessing of MIME types before - trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken + trying `/etc/mime.types`. *NOTE* that this path, if relative, is taken as relative to the current Git repository, not to CGI script. If unset, - only '/etc/mime.types' is used (if present on filesystem). If no mimetypes + only `/etc/mime.types` is used (if present on filesystem). If no mimetypes file is found, mimetype guessing based on extension of file is disabled. Unset by default. @@ -295,8 +297,8 @@ relative to base URI of gitweb. + This list should contain the URI of gitweb's standard stylesheet. The default URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS` -makefile variable. Its default value is 'static/gitweb.css' -(or 'static/gitweb.min.css' if the `CSSMIN` variable is defined, +makefile variable. Its default value is `static/gitweb.css` +(or `static/gitweb.min.css` if the `CSSMIN` variable is defined, i.e. if CSS minifier is used during build). + *Note*: there is also a legacy `$stylesheet` configuration variable, which was @@ -309,7 +311,7 @@ $logo:: is displayed in the top right corner of each gitweb page and used as a logo for the Atom feed. Relative to the base URI of gitweb (as a path). Can be adjusted when building gitweb using `GITWEB_LOGO` variable - By default set to 'static/git-logo.png'. + By default set to `static/git-logo.png`. $favicon:: Points to the location where you put 'git-favicon.png' on your web @@ -318,7 +320,7 @@ $favicon:: may display them in the browser's URL bar and next to the site name in bookmarks. Relative to the base URI of gitweb. Can be adjusted at build time using `GITWEB_FAVICON` variable. - By default set to 'static/git-favicon.png'. + By default set to `static/git-favicon.png`. $javascript:: Points to the location where you put 'gitweb.js' on your web server, @@ -326,7 +328,7 @@ $javascript:: Relative to the base URI of gitweb. Can be set at build time using the `GITWEB_JS` build-time configuration variable. + -The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if +The default value is either `static/gitweb.js`, or `static/gitweb.min.js` if the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used at build time. *Note* that this single file is generated from multiple individual JavaScript "modules". @@ -357,6 +359,7 @@ $home_link_str:: + For example, the following setting produces a breadcrumb trail like "home / dev / projects / ..." where "projects" is the home link. ++ ---------------------------------------------------------------------------- our @extra_breadcrumbs = ( [ 'home' => 'https://www.example.org/' ], @@ -441,7 +444,7 @@ $default_blob_plain_mimetype:: doesn't result in some other type; by default "text/plain". Gitweb guesses mimetype of a file to display based on extension of its filename, using `$mimetypes_file` (if set and file exists) - and '/etc/mime.types' files (see *mime.types*(5) manpage; only + and `/etc/mime.types` files (see *mime.types*(5) manpage; only filename extension rules are supported by gitweb). $default_text_plain_charset:: @@ -483,7 +486,7 @@ affects how "summary" pages look like, or load limiting). (for example one for `git://` protocol, and one for `http://` protocol). + -Note that per repository configuration can be set in '$GIT_DIR/cloneurl' +Note that per repository configuration can be set in `$GIT_DIR/cloneurl` file, or as values of multi-value `gitweb.url` configuration variable in project config. Per-repository configuration takes precedence over value composed from `@git_base_url_list` elements and project name. @@ -517,7 +520,7 @@ $maxload:: If the server load exceeds this value then gitweb will return "503 Service Unavailable" error. The server load is taken to be 0 if gitweb cannot determine its value. Currently it works only on Linux, - where it uses '/proc/loadavg'; the load there is the number of active + where it uses `/proc/loadavg`; the load there is the number of active tasks on the system -- processes that are actually running -- averaged over the last minute. + @@ -533,7 +536,7 @@ $omit_owner:: $per_request_config:: If this is set to code reference, it will be run once for each request. - You can set parts of configuration that change per session this way. + You can set parts of configuration that change per session this way. For example, one might use the following code in a gitweb configuration file + @@ -681,7 +684,7 @@ compressed tar archive) and "zip"; please consult gitweb sources for a definitive list. By default only "tgz" is offered. + This feature can be configured on a per-repository basis via -repository's `gitweb.blame` configuration variable, which contains +repository's `gitweb.snapshot` configuration variable, which contains a comma separated list of formats or "none" to disable snapshots. Unknown values are ignored. @@ -736,7 +739,7 @@ Currently available providers are *"gravatar"* and *"picon"*. Only one provider at a time can be selected ('default' is one element list). If an unknown provider is specified, the feature is disabled. *Note* that some providers might require extra Perl packages to be -installed; see 'gitweb/INSTALL' for more details. +installed; see `gitweb/INSTALL` for more details. + This feature can be configured on a per-repository basis via repository's `gitweb.avatar` configuration variable. @@ -783,9 +786,9 @@ forks:: subdirectories of project root (basename) to be forks of existing projects. For each project +$projname.git+, projects in the +$projname/+ directory and its subdirectories will not be - shown in the main projects list. Instead, a \'\+' mark is shown - next to +$projname+, which links to a "forks" view that lists all - the forks (all projects in +$projname/+ subdirectory). Additionally + shown in the main projects list. Instead, a \'+' mark is shown + next to `$projname`, which links to a "forks" view that lists all + the forks (all projects in `$projname/` subdirectory). Additionally a "forks" view for a project is linked from project summary page. + If the project list is taken from a file (+$projects_list+ points to a @@ -901,14 +904,16 @@ To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and "zip" snapshots), while allowing individual projects to turn them off, put the following in your GITWEB_CONFIG file: - $feature{'blame'}{'default'} = [1]; - $feature{'blame'}{'override'} = 1; +-------------------------------------------------------------------------------- +$feature{'blame'}{'default'} = [1]; +$feature{'blame'}{'override'} = 1; - $feature{'pickaxe'}{'default'} = [1]; - $feature{'pickaxe'}{'override'} = 1; +$feature{'pickaxe'}{'default'} = [1]; +$feature{'pickaxe'}{'override'} = 1; - $feature{'snapshot'}{'default'} = ['zip', 'tgz']; - $feature{'snapshot'}{'override'} = 1; +$feature{'snapshot'}{'default'} = ['zip', 'tgz']; +$feature{'snapshot'}{'override'} = 1; +-------------------------------------------------------------------------------- If you allow overriding for the snapshot feature, you can specify which snapshot formats are globally disabled. You can also add any command-line diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 88450589af..3cc9b034c4 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -28,15 +28,14 @@ Gitweb provides a web interface to Git repositories. Its features include: revisions one at a time, viewing the history of the repository. * Finding commits which commit messages matches given search term. -See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or -http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, +See http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, browsed using gitweb itself. CONFIGURATION ------------- Various aspects of gitweb's behavior can be controlled through the configuration -file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5] +file `gitweb_config.perl` or `/etc/gitweb.conf`. See the linkgit:gitweb.conf[5] for details. Repositories @@ -51,7 +50,7 @@ projects' root" subsection). our $projectroot = '/path/to/parent/directory'; ----------------------------------------------------------------------- -The default value for `$projectroot` is '/pub/git'. You can change it during +The default value for `$projectroot` is `/pub/git`. You can change it during building gitweb via `GITWEB_PROJECTROOT` build configuration variable. By default all Git repositories under `$projectroot` are visible and available @@ -231,7 +230,7 @@ Unnamed repository; edit this file to name it for gitweb. ------------------------------------------------------------------------------- + from the template during repository creation, usually installed in -'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo +`/usr/share/git-core/templates/`. You can use the `gitweb.description` repo configuration variable, but the file takes precedence. category (or `gitweb.category`):: @@ -407,7 +406,7 @@ in the instructions so they can be included in a future release. Apache as CGI ~~~~~~~~~~~~~ Apache must be configured to support CGI scripts in the directory in -which gitweb is installed. Let's assume that it is '/var/www/cgi-bin' +which gitweb is installed. Let's assume that it is `/var/www/cgi-bin` directory. ----------------------------------------------------------------------- @@ -431,7 +430,7 @@ You can use mod_perl with gitweb. You must install Apache::Registry (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable this support. -Assuming that gitweb is installed to '/var/www/perl', the following +Assuming that gitweb is installed to `/var/www/perl`, the following Apache configuration (for mod_perl 2.x) is suitable. ----------------------------------------------------------------------- @@ -456,7 +455,7 @@ Apache with FastCGI ~~~~~~~~~~~~~~~~~~~ Gitweb works with Apache and FastCGI. First you need to rename, copy or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is -installed in '/usr/share/gitweb' directory. The following Apache +installed in `/usr/share/gitweb` directory. The following Apache configuration is suitable (UNTESTED!) ----------------------------------------------------------------------- @@ -503,22 +502,22 @@ 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`, +`/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 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. Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the -named file (i.e. in this example '/etc/gitweb.conf') as a configuration for +named file (i.e. in this example `/etc/gitweb.conf`) as a configuration for gitweb. You don't really need it in above example; it is required only if your configuration file is in different place than built-in (during -compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See +compiling gitweb) 'gitweb_config.perl' or `/etc/gitweb.conf`. See linkgit:gitweb.conf[5] for details, especially information about precedence rules. If you use the rewrite rules from the example you *might* also need something like the following in your gitweb configuration file -('/etc/gitweb.conf' following example): +(`/etc/gitweb.conf` following example): ---------------------------------------------------------------------------- @stylesheets = ("/some/absolute/path/gitweb.css"); $my_uri = "/"; @@ -575,7 +574,7 @@ like this: Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` environment variable from a web server, so you need to put the following -line in gitweb configuration file ('/etc/gitweb.conf' in above example): +line in gitweb configuration file (`/etc/gitweb.conf` in above example): -------------------------------------------------------------------------- $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; -------------------------------------------------------------------------- @@ -585,7 +584,7 @@ referenced by `$per_request_config`; These configurations enable two things. First, each unix user (`<user>`) of the server will be able to browse through gitweb Git repositories found in -'~/public_git/' with the following url: +`~/public_git/` with the following url: http://git.example.org/~<user>/ @@ -596,7 +595,7 @@ If you already use `mod_userdir` in your virtual host or you don't want to use the \'~' as first character, just comment or remove the second rewrite rule, and uncomment one of the following according to what you want. -Second, repositories found in '/pub/scm/' and '/var/git/' will be accessible +Second, repositories found in `/pub/scm/` and `/var/git/` will be accessible through `http://git.example.org/scm/` and `http://git.example.org/var/`. You can add as many project roots as you want by adding rewrite rules like the third and the fourth. @@ -614,7 +613,7 @@ that it consumes and produces URLs in the form http://git.example.com/project.git/shortlog/sometag i.e. without 'gitweb.cgi' part, by using a configuration such as the -following. This configuration assumes that '/var/www/gitweb' is the +following. This configuration assumes that `/var/www/gitweb` is the DocumentRoot of your webserver, contains the gitweb.cgi script and complementary static files (stylesheet, favicon, JavaScript): @@ -645,9 +644,9 @@ parameter. `@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" access to your project .git dirs (described in "Single URL for gitweb and for fetching" section). A possible workaround for the latter is the -following: in your project root dir (e.g. '/pub/git') have the projects -named *without* a .git extension (e.g. '/pub/git/project' instead of -'/pub/git/project.git') and configure Apache as follows: +following: in your project root dir (e.g. `/pub/git`) have the projects +named *without* a .git extension (e.g. `/pub/git/project` instead of +`/pub/git/project.git`) and configure Apache as follows: ---------------------------------------------------------------------------- <VirtualHost *:80> ServerAlias git.example.com @@ -681,7 +680,7 @@ cloned), while will provide human-friendly gitweb access. This solution is not 100% bulletproof, in the sense that if some project has -a named ref (branch, tag) starting with 'git/', then paths such as +a named ref (branch, tag) starting with `git/`, then paths such as http://git.example.com/project/command/abranch..git/abranch @@ -697,7 +696,7 @@ SEE ALSO -------- linkgit:gitweb.conf[5], linkgit:git-instaweb[1] -'gitweb/README', 'gitweb/INSTALL' +`gitweb/README`, `gitweb/INSTALL` GIT --- diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index ca11c7bdaf..abc0dc6bc7 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -301,8 +301,7 @@ topics on 'next': .Rewind and rebuild next [caption="Recipe: "] ===================================== -* `git checkout next` -* `git reset --hard master` +* `git switch -C next master` * `git merge ai/topic_in_next1` * `git merge ai/topic_in_next2` * ... diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 0d2aa48c63..090c888335 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -255,7 +255,7 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_object]]object:: The unit of storage in Git. It is uniquely identified by the <<def_SHA1,SHA-1>> of its contents. Consequently, an - object can not be changed. + object cannot be changed. [[def_object_database]]object database:: Stores a set of "objects", and an individual <<def_object,object>> is @@ -287,6 +287,15 @@ This commit is referred to as a "merge commit", or sometimes just a origin/name-of-upstream-branch, which you can see using `git branch -r`. +[[def_overlay]]overlay:: + Only update and add files to the working directory, but don't + delete them, similar to how 'cp -R' would update the contents + in the destination directory. This is the default mode in a + <<def_checkout,checkout>> when checking out files from the + <<def_index,index>> or a <<def_tree-ish,tree-ish>>. In + contrast, no-overlay mode also deletes tracked files not + present in the source, similar to 'rsync --delete'. + [[def_pack]]pack:: A set of objects which have been compressed into one file (to save space or to transmit them efficiently). @@ -404,6 +413,8 @@ these forms: - "`!ATTR`" requires that the attribute `ATTR` be unspecified. + +Note that when matching against a tree object, attributes are still +obtained from working tree, not from the given tree object. exclude;; After a path matches any non-exclude pathspec, it will be run diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index ca4378740c..73be8b49f8 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -154,15 +154,17 @@ by doing the following: - Anything unobvious that is applicable to 'master' (in other words, does not depend on anything that is still in 'next' and not in 'master') is applied to a new topic branch that - is forked from the tip of 'master'. This includes both + is forked from the tip of 'master' (or the last feature release, + which is a bit older than 'master'). This includes both enhancements and unobvious fixes to 'master'. A topic branch is named as ai/topic where "ai" is two-letter string named after author's initial and "topic" is a descriptive name of the topic (in other words, "what's the series is about"). - An unobvious fix meant for 'maint' is applied to a new - topic branch that is forked from the tip of 'maint'. The - topic is named as ai/maint-topic. + topic branch that is forked from the tip of 'maint' (or the + oldest and still relevant maintenance branch). The + topic may be named as ai/maint-topic. - Changes that pertain to an existing topic are applied to the branch, but: @@ -174,24 +176,40 @@ by doing the following: - Replacement patches to an existing topic are accepted only for commits not in 'next'. - The above except the "replacement" are all done with: + The initial round is done with: $ git checkout ai/topic ;# or "git checkout -b ai/topic master" $ git am -sc3 mailbox - while patch replacement is often done by: + and replacing an existing topic with subsequent round is done with: - $ git format-patch ai/topic~$n..ai/topic ;# export existing + $ git checkout master...ai/topic ;# try to reapply to the same base + $ git am -sc3 mailbox + + to prepare the new round on a detached HEAD, and then + + $ git range-diff @{-1}... + $ git diff @{-1} - then replace some parts with the new patch, and reapplying: + to double check what changed since the last round, and finally - $ git checkout ai/topic - $ git reset --hard ai/topic~$n - $ git am -sc3 -s 000*.txt + $ git checkout -B @{-1} + + to conclude (the last step is why a topic already in 'next' is + not replaced but updated incrementally). + + Whether it is the initial round or a subsequent round, the topic + may not build even in isolation, or may break the build when + merged to integration branches due to bugs. There may already + be obvious and trivial improvements suggested on the list. The + maintainer often adds an extra commit, with "SQUASH???" in its + title, to fix things up, before publishing the integration + branches to make it usable by other developers for testing. + These changes are what the maintainer is not 100% committed to + (trivial typofixes etc. are often squashed directly into the + patches that need fixing, without being applied as a separate + "SQUASH???" commit), so that they can be removed easily as needed. - The full test suite is always run for 'maint' and 'master' - after patch application; for topic branches the tests are run - as time permits. - Merge maint to master as needed: @@ -371,6 +389,14 @@ Some observations to be made. be included in the next feature release. Being in the 'master' branch typically is. + * Due to the nature of "SQUASH???" fix-ups, if the original author + agrees with the suggested changes, it is OK to squash them to + appropriate patches in the next round (when the suggested change + is small enough, the author should not even bother with + "Helped-by"). It is also OK to drop them from the next round + when the original author does not agree with the suggestion, but + the author is expected to say why somewhere in the discussion. + Appendix -------- diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt index bd1027433b..81be0d6115 100644 --- a/Documentation/howto/separating-topic-branches.txt +++ b/Documentation/howto/separating-topic-branches.txt @@ -81,7 +81,7 @@ After I am done, I'd try a pretend-merge between "topicA" and o---o---o---o---o---o The last diff better not to show anything other than cleanups -for crufts. Then I can finally clean things up: +for cruft. Then I can finally clean things up: $ git branch -D topic $ git reset --hard HEAD^ ;# nuke pretend merge diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index f44e5e9458..bfe6f9b500 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -244,8 +244,8 @@ Using a proxy: -------------- If you have to access the WebDAV server from behind an HTTP(S) proxy, -set the variable 'all_proxy' to 'http://proxy-host.com:port', or -'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man +set the variable 'all_proxy' to `http://proxy-host.com:port`, or +`http://login-on-proxy:passwd-on-proxy@proxy-host.com:port`. See 'man curl' for details. diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index a5193b1e5c..89821ec74f 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -80,7 +80,7 @@ case "$1" in info "The branch '$1' is new..." else # updating -- make sure it is a fast-forward - mb=$(git-merge-base "$2" "$3") + mb=$(git merge-base "$2" "$3") case "$mb,$2" in "$2,$mb") info "Update is fast-forward" ;; *) noff=y; info "This is not a fast-forward update.";; diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 1ae8d1214e..a499a94ac2 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -33,7 +33,7 @@ Here is the command sequence you need: ---------------- $ git remote add -f Bproject /path/to/B <1> -$ git merge -s ours --no-commit Bproject/master <2> +$ git merge -s ours --no-commit --allow-unrelated-histories Bproject/master <2> $ git read-tree --prefix=dir-B/ -u Bproject/master <3> $ git commit -m "Merge B project as our subdirectory" <4> diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl deleted file mode 100644 index b4d315cb8c..0000000000 --- a/Documentation/manpage-1.72.xsl +++ /dev/null @@ -1,14 +0,0 @@ -<!-- manpage-1.72.xsl: - special settings for manpages rendered from asciidoc+docbook - handles peculiarities in docbook-xsl 1.72.0 --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<xsl:import href="manpage-base.xsl"/> - -<!-- these are the special values for the roff control characters - needed for docbook-xsl 1.72.0 --> -<xsl:param name="git.docbook.backslash">▓</xsl:param> -<xsl:param name="git.docbook.dot" >⌂</xsl:param> - -</xsl:stylesheet> diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl deleted file mode 100644 index a264fa6160..0000000000 --- a/Documentation/manpage-base.xsl +++ /dev/null @@ -1,35 +0,0 @@ -<!-- manpage-base.xsl: - special formatting for manpages rendered from asciidoc+docbook --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- these params silence some output from xmlto --> -<xsl:param name="man.output.quietly" select="1"/> -<xsl:param name="refentry.meta.get.quietly" select="1"/> - -<!-- convert asciidoc callouts to man page format; - git.docbook.backslash and git.docbook.dot params - must be supplied by another XSL file or other means --> -<xsl:template match="co"> - <xsl:value-of select="concat( - $git.docbook.backslash,'fB(', - substring-after(@id,'-'),')', - $git.docbook.backslash,'fR')"/> -</xsl:template> -<xsl:template match="calloutlist"> - <xsl:value-of select="$git.docbook.dot"/> - <xsl:text>sp </xsl:text> - <xsl:apply-templates/> - <xsl:text> </xsl:text> -</xsl:template> -<xsl:template match="callout"> - <xsl:value-of select="concat( - $git.docbook.backslash,'fB', - substring-after(@arearefs,'-'), - '. ',$git.docbook.backslash,'fR')"/> - <xsl:apply-templates/> - <xsl:value-of select="$git.docbook.dot"/> - <xsl:text>br </xsl:text> -</xsl:template> - -</xsl:stylesheet> diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl index 608eb5df62..e13db85693 100644 --- a/Documentation/manpage-bold-literal.xsl +++ b/Documentation/manpage-bold-literal.xsl @@ -1,17 +1,16 @@ <!-- manpage-bold-literal.xsl: special formatting for manpages rendered from asciidoc+docbook --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:d="http://docbook.org/ns/docbook" version="1.0"> <!-- render literal text as bold (instead of plain or monospace); this makes literal text easier to distinguish in manpages viewed on a tty --> -<xsl:template match="literal"> - <xsl:value-of select="$git.docbook.backslash"/> - <xsl:text>fB</xsl:text> +<xsl:template match="literal|d:literal"> + <xsl:text>\fB</xsl:text> <xsl:apply-templates/> - <xsl:value-of select="$git.docbook.backslash"/> - <xsl:text>fR</xsl:text> + <xsl:text>\fR</xsl:text> </xsl:template> </xsl:stylesheet> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl index a48f5b11f3..a9c7ec69f4 100644 --- a/Documentation/manpage-normal.xsl +++ b/Documentation/manpage-normal.xsl @@ -1,13 +1,26 @@ <!-- manpage-normal.xsl: - special settings for manpages rendered from asciidoc+docbook - handles anything we want to keep away from docbook-xsl 1.72.0 --> + special settings for manpages rendered from asciidoc+docbook --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> -<xsl:import href="manpage-base.xsl"/> -<!-- these are the normal values for the roff control characters --> -<xsl:param name="git.docbook.backslash">\</xsl:param> -<xsl:param name="git.docbook.dot" >.</xsl:param> +<!-- these params silence some output from xmlto --> +<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> </xsl:stylesheet> diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl deleted file mode 100644 index a63c7632a8..0000000000 --- a/Documentation/manpage-suppress-sp.xsl +++ /dev/null @@ -1,21 +0,0 @@ -<!-- manpage-suppress-sp.xsl: - special settings for manpages rendered from asciidoc+docbook - handles erroneous, inline .sp in manpage output of some - versions of docbook-xsl --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- attempt to work around spurious .sp at the tail of the line - that some versions of docbook stylesheets seem to add --> -<xsl:template match="simpara"> - <xsl:variable name="content"> - <xsl:apply-templates/> - </xsl:variable> - <xsl:value-of select="normalize-space($content)"/> - <xsl:if test="not(ancestor::authorblurb) and - not(ancestor::personblurb)"> - <xsl:text> </xsl:text> - </xsl:if> -</xsl:template> - -</xsl:stylesheet> diff --git a/Documentation/manpage.xsl b/Documentation/manpage.xsl new file mode 100644 index 0000000000..ef64bab17a --- /dev/null +++ b/Documentation/manpage.xsl @@ -0,0 +1,3 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl" /> +</xsl:stylesheet> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 63a3fc0954..80d4831662 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -3,9 +3,14 @@ Perform the merge and commit the result. This option can be used to override --no-commit. + -With --no-commit perform the merge but pretend the merge -failed and do not autocommit, to give the user a chance to -inspect and further tweak the merge result before committing. +With --no-commit perform the merge and stop just before creating +a merge commit, to give the user a chance to inspect and further +tweak the merge result before committing. ++ +Note that fast-forward updates do not create a merge commit and +therefore there is no way to stop those merges with --no-commit. +Thus, if you want to ensure your branch is not changed or updated +by the merge command, use --no-ff with --no-commit. --edit:: -e:: @@ -27,27 +32,41 @@ they run `git merge`. To make it easier to adjust such scripts to the updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be set to `no` at the beginning of them. ---ff:: - When the merge resolves as a fast-forward, only update the branch - pointer, without creating a merge commit. This is the default - behavior. +--cleanup=<mode>:: + This option determines how the merge message will be cleaned up before + committing. See linkgit:git-commit[1] for more details. In addition, if + the '<mode>' is given a value of `scissors`, scissors will be appended + to `MERGE_MSG` before being passed on to the commit machinery in the + case of a merge conflict. +--ff:: --no-ff:: - Create a merge commit even when the merge resolves as a - fast-forward. This is the default behaviour when merging an - annotated (and possibly signed) tag that is not stored in - its natural place in 'refs/tags/' hierarchy. - --ff-only:: - Refuse to merge and exit with a non-zero status unless the - current `HEAD` is already up to date or the merge can be - resolved as a fast-forward. + Specifies how a merge is handled when the merged-in history is + already a descendant of the current history. `--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. ++ +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 +merge commit). When not possible (when the merged-in history is not a +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. ++ +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. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign the resulting merge commit. The `keyid` argument is optional and defaults to the committer identity; if specified, - it must be stuck to the option without a space. + it must be stuck to the option without a space. `--no-gpg-sign` + is useful to countermand both `commit.gpgSign` configuration variable, + and earlier `--gpg-sign`. --log[=<n>]:: --no-log:: @@ -90,6 +109,12 @@ merge. + 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. + +--no-verify:: + This option bypasses the pre-merge and commit-msg hooks. + See also linkgit:githooks[5]. -s <strategy>:: --strategy=<strategy>:: @@ -135,6 +160,14 @@ ifndef::git-pull[] 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 + 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. + --allow-unrelated-histories:: By default, `git merge` command refuses to merge histories that do not share a common ancestor. This option can be diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index aa66cbe41e..2912de706b 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -32,7 +32,7 @@ The 'recursive' strategy can take the following options: ours;; This option forces conflicting hunks to be auto-resolved cleanly by favoring 'our' version. Changes from the other tree that do not - conflict with our side are reflected to the merge result. + conflict with our side are reflected in the merge result. For a binary file, the entire contents are taken from our side. + This should not be confused with the 'ours' merge strategy, which does not diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 6109ef09aa..547a552463 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -4,7 +4,7 @@ PRETTY FORMATS If the commit is a merge, and if the pretty-format is not 'oneline', 'email' or 'raw', an additional line is inserted before the 'Author:' line. This line begins with -"Merge: " and the sha1s of ancestral commits are printed, +"Merge: " and the hashes of ancestral commits are printed, separated by spaces. Note that the listed commits may not necessarily be the list of the *direct* parent commits if you have limited your view of history: for example, if you are @@ -20,20 +20,20 @@ built-in formats: * 'oneline' - <sha1> <title line> + <hash> <title line> + This is designed to be as compact as possible. * 'short' - commit <sha1> + commit <hash> Author: <author> <title line> * 'medium' - commit <sha1> + commit <hash> Author: <author> Date: <author date> @@ -43,7 +43,7 @@ This is designed to be as compact as possible. * 'full' - commit <sha1> + commit <hash> Author: <author> Commit: <committer> @@ -53,7 +53,7 @@ This is designed to be as compact as possible. * 'fuller' - commit <sha1> + commit <hash> Author: <author> AuthorDate: <author date> Commit: <committer> @@ -63,19 +63,36 @@ This is designed to be as compact as possible. <full commit message> +* 'reference' + + <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, +the date is formatted with `--date=short` unless another `--date` option +is explicitly specified. As with any `format:` with format +placeholders, its output is not affected by other options like +`--decorate` and `--walk-reflogs`. + * 'email' - From <sha1> <date> + From <hash> <date> From: <author> Date: <author date> Subject: [PATCH] <title line> <full commit message> +* 'mboxrd' ++ +Like 'email', but lines in the commit message starting with "From " +(preceded by zero or more ">") are quoted with ">" so they aren't +confused as starting a new commit. + * 'raw' + The 'raw' format shows the entire commit exactly as -stored in the commit object. Notably, the SHA-1s are +stored in the commit object. Notably, the hashes are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and 'parents' information show the true parent commits, without taking grafts or history @@ -102,115 +119,169 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff input.<< + The placeholders are: -- '%H': commit hash -- '%h': abbreviated commit hash -- '%T': tree hash -- '%t': abbreviated tree hash -- '%P': parent hashes -- '%p': abbreviated parent hashes -- '%an': author name -- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1] - or linkgit:git-blame[1]) -- '%ae': author email -- '%aE': author email (respecting .mailmap, see - linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- '%ad': author date (format respects --date= option) -- '%aD': author date, RFC2822 style -- '%ar': author date, relative -- '%at': author date, UNIX timestamp -- '%ai': author date, ISO 8601-like format -- '%aI': author date, strict ISO 8601 format -- '%cn': committer name -- '%cN': committer name (respecting .mailmap, see - linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- '%ce': committer email -- '%cE': committer email (respecting .mailmap, see - linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- '%cd': committer date (format respects --date= option) -- '%cD': committer date, RFC2822 style -- '%cr': committer date, relative -- '%ct': committer date, UNIX timestamp -- '%ci': committer date, ISO 8601-like format -- '%cI': committer date, strict ISO 8601 format -- '%d': ref names, like the --decorate option of linkgit:git-log[1] -- '%D': ref names without the " (", ")" wrapping. -- '%e': encoding -- '%s': subject -- '%f': sanitized subject line, suitable for a filename -- '%b': body -- '%B': raw body (unwrapped subject and body) +- Placeholders that expand to a single literal character: +'%n':: newline +'%%':: a raw '%' +'%x00':: print a byte from a hex code + +- Placeholders that affect formatting of later placeholders: +'%Cred':: switch color to red +'%Cgreen':: switch color to green +'%Cblue':: switch color to blue +'%Creset':: reset color +'%C(...)':: color specification, as described under Values in the + "CONFIGURATION FILE" section of linkgit:git-config[1]. By + default, colors are shown only when enabled for log output + (by `color.diff`, `color.ui`, or `--color`, and respecting + the `auto` settings of the former if we are going to a + terminal). `%C(auto,...)` is accepted as a historical + synonym for the default (e.g., `%C(auto,red)`). Specifying + `%C(always,...)` will show the colors even when color is + not otherwise enabled (though consider just using + `--color=always` to enable color for the whole output, + including this format and anything else git might color). + `auto` alone (i.e. `%C(auto)`) will turn on auto coloring + on the next placeholders until the color is switched + again. +'%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 + 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 + 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, + but padding spaces on the left +'%>>(<N>)', '%>>|(<N>)':: similar to '%>(<N>)', '%>|(<N>)' + 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>)' + respectively, but padding both sides + (i.e. the text is centered) + +- Placeholders that expand to information extracted from the commit: +'%H':: commit hash +'%h':: abbreviated commit hash +'%T':: tree hash +'%t':: abbreviated tree hash +'%P':: parent hashes +'%p':: abbreviated parent hashes +'%an':: author name +'%aN':: author name (respecting .mailmap, see linkgit:git-shortlog[1] + or linkgit:git-blame[1]) +'%ae':: author email +'%aE':: author email (respecting .mailmap, see linkgit:git-shortlog[1] + or linkgit:git-blame[1]) +'%al':: author email local-part (the part before the '@' sign) +'%aL':: author local-part (see '%al') respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) +'%ad':: author date (format respects --date= option) +'%aD':: author date, RFC2822 style +'%ar':: author date, relative +'%at':: author date, UNIX timestamp +'%ai':: author date, ISO 8601-like format +'%aI':: author date, strict ISO 8601 format +'%as':: author date, short format (`YYYY-MM-DD`) +'%cn':: committer name +'%cN':: committer name (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) +'%ce':: committer email +'%cE':: committer email (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) +'%cl':: author email local-part (the part before the '@' sign) +'%cL':: author local-part (see '%cl') respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) +'%cd':: committer date (format respects --date= option) +'%cD':: committer date, RFC2822 style +'%cr':: committer date, relative +'%ct':: committer date, UNIX timestamp +'%ci':: committer date, ISO 8601-like format +'%cI':: committer date, strict ISO 8601 format +'%cs':: committer date, short format (`YYYY-MM-DD`) +'%d':: ref names, like the --decorate option of linkgit:git-log[1] +'%D':: ref names without the " (", ")" wrapping. +'%S':: ref name given on the command line by which the commit was reached + (like `git log --source`), only works with `git log` +'%e':: encoding +'%s':: subject +'%f':: sanitized subject line, suitable for a filename +'%b':: body +'%B':: raw body (unwrapped subject and body) ifndef::git-rev-list[] -- '%N': commit notes +'%N':: commit notes endif::git-rev-list[] -- '%GG': raw verification message from GPG for a signed commit -- '%G?': 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 -- '%GS': show the name of the signer for a signed commit -- '%GK': show the key used to sign a signed commit -- '%gD': reflog selector, e.g., `refs/stash@{1}` or - `refs/stash@{2 minutes ago`}; the format follows the rules described - for the `-g` option. The portion before the `@` is the refname as - given on the command line (so `git log -g refs/heads/master` would - yield `refs/heads/master@{0}`). -- '%gd': shortened reflog selector; same as `%gD`, but the refname - portion is shortened for human readability (so `refs/heads/master` - becomes just `master`). -- '%gn': reflog identity name -- '%gN': reflog identity name (respecting .mailmap, see - linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- '%ge': reflog identity email -- '%gE': reflog identity email (respecting .mailmap, see - linkgit:git-shortlog[1] or linkgit:git-blame[1]) -- '%gs': reflog subject -- '%Cred': switch color to red -- '%Cgreen': switch color to green -- '%Cblue': switch color to blue -- '%Creset': reset color -- '%C(...)': color specification, as described under Values in the - "CONFIGURATION FILE" section of linkgit:git-config[1]. - By default, colors are shown only when enabled for log output (by - `color.diff`, `color.ui`, or `--color`, and respecting the `auto` - settings of the former if we are going to a terminal). `%C(auto,...)` - is accepted as a historical synonym for the default (e.g., - `%C(auto,red)`). Specifying `%C(always,...) will show the colors - even when color is not otherwise enabled (though consider - just using `--color=always` to enable color for the whole output, - including this format and anything else git might color). `auto` - alone (i.e. `%C(auto)`) will turn on auto coloring on the next - placeholders until the color is switched again. -- '%m': left (`<`), right (`>`) or boundary (`-`) mark -- '%n': newline -- '%%': a raw '%' -- '%x00': print a byte from a hex code -- '%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 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 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, but padding spaces on the left -- '%>>(<N>)', '%>>|(<N>)': similar to '%>(<N>)', '%>|(<N>)' - 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>)' - respectively, but padding both sides (i.e. the text is centered) -- %(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 the - `only` option is given, omit non-trailer lines from the trailer block. - If the `unfold` option is given, behave as if interpret-trailer's - `--unfold` option was given. E.g., `%(trailers:only,unfold)` to do - both. +'%GG':: raw verification message from GPG for a signed commit +'%G?':: 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 +'%GS':: show the name of the signer for a signed commit +'%GK':: show the key used to sign a signed commit +'%GF':: show the fingerprint of the key used to sign a signed commit +'%GP':: show the fingerprint of the primary key whose subkey was used + to sign a signed commit +'%GT':: show the trust level for the key used to sign a signed commit +'%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2 + minutes ago}`; the format follows the rules described for the + `-g` option. The portion before the `@` is the refname as + given on the command line (so `git log -g refs/heads/master` + would yield `refs/heads/master@{0}`). +'%gd':: shortened reflog selector; same as `%gD`, but the refname + portion is shortened for human readability (so + `refs/heads/master` becomes just `master`). +'%gn':: reflog identity name +'%gN':: reflog identity name (respecting .mailmap, see + linkgit:git-shortlog[1] or linkgit:git-blame[1]) +'%ge':: reflog identity email +'%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: +** 'key=<K>': 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 + non-trailer lines in the trailer block are hidden. If that is not + desired it can be disabled with `only=false`. E.g., + `%(trailers:key=Reviewed-by)` shows trailer lines with key + `Reviewed-by`. +** 'only[=val]': select whether non-trailer lines from the trailer + block should be included. The `only` keyword may optionally be + followed by an equal sign and one of `true`, `on`, `yes` to omit or + `false`, `off`, `no` to show the non-trailer lines. If option is + given without value it is enabled. If given multiple times the last + value is used. +** '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 + the literal formatting codes described above. To use comma as + separator one must use `%x2C` as it would otherwise be parsed as + next option. If separator option is given multiple times only the + last one is used. E.g., `%(trailers:key=Ticket,separator=%x2C )` + shows all trailer lines whose key is "Ticket" separated by a comma + and a space. +** 'unfold[=val]': make it behave as if interpret-trailer's `--unfold` + option was given. In same way as to for `only` it can be followed + by an equal sign and explicit value. E.g., + `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. +** 'valueonly[=val]': skip over the key part of the trailer line and only + show the value part. Also this optionally allows explicit value. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index e44fc8f738..7a6da6db78 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -3,7 +3,7 @@ Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', - 'full', 'fuller', 'email', 'raw', 'format:<string>' + 'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>' and 'tformat:<string>'. When '<format>' is none of the above, and has '%placeholder' in it, it acts as if '--pretty=tformat:<format>' were given. @@ -57,7 +57,7 @@ message by 4 spaces (i.e. 'medium', which is the default, 'full', and 'fuller'). ifndef::git-rev-list[] ---notes[=<treeish>]:: +--notes[=<ref>]:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default for `git log`, `git show` and `git whatchanged` commands when @@ -68,8 +68,8 @@ By default, the notes shown are from the notes refs listed in the `core.notesRef` and `notes.displayRef` variables (or corresponding environment overrides). See linkgit:git-config[1] for more details. + -With an optional '<treeish>' argument, use the treeish to find the notes -to display. The treeish can specify the full refname when it begins +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. + @@ -85,7 +85,7 @@ 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[=<treeish>]:: +--show-notes[=<ref>]:: --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes options instead. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index f1fb08dc68..95ea849902 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -19,7 +19,8 @@ ifndef::git-pull[] (see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below). endif::git-pull[] ifdef::git-pull[] - (see linkgit:git-fetch[1]). + (see the section "CONFIGURED REMOTE-TRACKING BRANCHES" + in linkgit:git-fetch[1]). endif::git-pull[] + The format of a <refspec> parameter is an optional plus @@ -33,11 +34,40 @@ name. it requests fetching everything up to the given tag. + The remote ref that matches <src> -is fetched, and if <dst> is not an empty string, the local -ref that matches it is fast-forwarded using <src>. -If the optional plus `+` is used, the local ref -is updated even if it does not result in a fast-forward -update. +is fetched, and if <dst> is not an empty string, an attempt +is made to update the local ref that matches it. ++ +Whether that update is allowed without `--force` depends on the ref +namespace it's being fetched to, the type of object being fetched, and +whether the update is considered to be a fast-forward. Generally, the +same rules apply for fetching as when pushing, see the `<refspec>...` +section of linkgit:git-push[1] for what those are. Exceptions to those +rules particular to 'git fetch' are noted below. ++ +Until Git version 2.20, and unlike when pushing with +linkgit:git-push[1], any updates to `refs/tags/*` would be accepted +without `+` in the refspec (or `--force`). When fetching, we promiscuously +considered all tag updates from a remote to be forced fetches. Since +Git version 2.20, fetching to update `refs/tags/*` works the same way +as when pushing. I.e. any updates will be rejected without `+` in the +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 +an ancestor etc. ++ +Unlike when pushing with linkgit:git-push[1], there is no +configuration which'll amend these rules, and nothing like a +`pre-fetch` hook analogous to the `pre-receive` hook. ++ +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` +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. + [NOTE] When the remote branch you want to fetch is known to diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 7b273635de..04ad7dd36e 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -13,8 +13,6 @@ has a line that matches `<pattern>`), unless otherwise noted. Note that these are applied before commit ordering and formatting options, such as `--reverse`. --- - -<number>:: -n <number>:: --max-count=<number>:: @@ -60,7 +58,7 @@ endif::git-rev-list[] `--all-match`). ifndef::git-rev-list[] + -When `--show-notes` is in effect, the message from the notes is +When `--notes` is in effect, the message from the notes is matched as if it were part of the log message. endif::git-rev-list[] @@ -184,6 +182,14 @@ explicitly. Pretend as if all objects mentioned by reflogs are listed on the command line as `<commit>`. +--alternate-refs:: + Pretend as if all objects mentioned as ref tips of alternate + repositories were listed on the command line. An alternate + repository is any repository whose object directory is specified + in `objects/info/alternates`. The set of included objects may + be modified by `core.alternateRefsCommand`, etc. See + linkgit:git-config[1]. + --single-worktree:: By default, all working trees will be examined by the following options when there are more than one (see @@ -263,7 +269,7 @@ list. exclude (that is, '{caret}commit', 'commit1..commit2', and 'commit1\...commit2' notations cannot be used). + -With `--pretty` format other than `oneline` (for obvious reasons), +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 @@ -272,13 +278,13 @@ depending on a few rules: + -- 1. If the starting point is specified as `ref@{Nth}`, show the index -format. + format. + 2. If the starting point was specified as `ref@{now}`, show the -timestamp format. + timestamp format. + 3. If neither was used, but `--date` was given on the command line, show -the timestamp in the format requested by `--date`. + the timestamp in the format requested by `--date`. + 4. Otherwise, show the index format. -- @@ -287,6 +293,8 @@ Under `--pretty=oneline`, the commit message is prefixed with this information on the same line. This option cannot be combined with `--reverse`. 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 @@ -308,8 +316,6 @@ ifdef::git-rev-list[] `<header>` text will be printed with each progress update. endif::git-rev-list[] --- - History Simplification ~~~~~~~~~~~~~~~~~~~~~~ @@ -336,6 +342,12 @@ Default mode:: branches if the end result is the same (i.e. merging branches with the same content) +--show-pulls:: + Include all commits from the default mode, but also any merge + commits that are not TREESAME to the first parent but are + TREESAME to a later parent. This mode is helpful for showing + the merge commits that "first introduced" a change to a branch. + --full-history:: Same as the default mode, but does not prune some history. @@ -528,7 +540,7 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`: parent and is TREESAME. -- -Finally, there is a fifth simplification mode available: +There is another simplification mode available: --ancestry-path:: Limit the displayed commits to those directly on the ancestry @@ -567,6 +579,132 @@ option does. Applied to the 'D..M' range, it results in: L--M ----------------------------------------------------------------------- +Before discussing another option, `--show-pulls`, we need to +create a new example history. ++ +A common problem users face when looking at simplified history is that a +commit they know changed a file somehow does not appear in the file's +simplified history. Let's demonstrate a new example and show how options +such as `--full-history` and `--simplify-merges` works in that case: ++ +----------------------------------------------------------------------- + .-A---M-----C--N---O---P + / / \ \ \/ / / + I B \ R-'`-Z' / + \ / \/ / + \ / /\ / + `---X--' `---Y--' +----------------------------------------------------------------------- ++ +For this example, suppose `I` created `file.txt` which was modified by +`A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`, +and `Y` do not change `file.txt`. The merge commit `M` was created by +resolving the merge conflict to include both changes from `A` and `B` +and hence is not TREESAME to either. The merge commit `R`, however, was +created by ignoring the contents of `file.txt` at `M` and taking only +the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not +`M`. Finally, the natural merge resolution to create `N` is to take the +contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`. +The merge commits `O` and `P` are TREESAME to their first parents, but +not to their second parents, `Z` and `Y` respectively. ++ +When using the default mode, `N` and `R` both have a TREESAME parent, so +those edges are walked and the others are ignored. The resulting history +graph is: ++ +----------------------------------------------------------------------- + I---X +----------------------------------------------------------------------- ++ +When using `--full-history`, Git walks every edge. This will discover +the commits `A` and `B` and the merge `M`, but also will reveal the +merge commits `O` and `P`. With parent rewriting, the resulting graph is: ++ +----------------------------------------------------------------------- + .-A---M--------N---O---P + / / \ \ \/ / / + I B \ R-'`--' / + \ / \/ / + \ / /\ / + `---X--' `------' +----------------------------------------------------------------------- ++ +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 +unrelated merges appear in the `--full-history` results. ++ +When using the `--simplify-merges` option, the commits `O` and `P` +disappear from the results. This is because the rewritten second parents +of `O` and `P` are reachable from their first parents. Those edges are +removed and then the commits look like single-parent commits that are +TREESAME to their parent. This also happens to the commit `N`, resulting +in a history view as follows: ++ +----------------------------------------------------------------------- + .-A---M--. + / / \ + I B R + \ / / + \ / / + `---X--' +----------------------------------------------------------------------- ++ +In this view, we see all of the important single-parent changes from +`A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the +not-so-carefully-resolved merge `R`. This is usually enough information +to determine why the commits `A` and `B` "disappeared" from history in +the default view. However, there are a few issues with this approach. ++ +The first issue is performance. Unlike any previous option, the +`--simplify-merges` option requires walking the entire commit history +before returning a single result. This can make the option difficult to +use for very large repositories. ++ +The second issue is one of auditing. When many contributors are working +on the same repository, it is important which merge commits introduced +a change into an important branch. The problematic merge `R` above is +not likely to be the merge commit that was used to merge into an +important branch. Instead, the merge `N` was used to merge `R` and `X` +into the important branch. This commit may have information about why +the change `X` came to override the changes from `A` and `B` in its +commit message. ++ +The `--show-pulls` option helps with both of these issues by adding more +merge commits to the history results. If a merge is not TREESAME to its +first parent but is TREESAME to a later parent, then that merge is +treated as if it "pulled" the change from another branch. When using +`--show-pulls` on this example (and no other options) the resulting +graph is: ++ +----------------------------------------------------------------------- + I---X---R---N +----------------------------------------------------------------------- ++ +Here, the merge commits `R` and `N` are included because they pulled +the commits `X` and `R` into the base branch, respectively. These +merges are the reason the commits `A` and `B` do not appear in the +default history. ++ +When `--show-pulls` is paired with `--simplify-merges`, the +graph includes all of the necessary information: ++ +----------------------------------------------------------------------- + .-A---M--. N + / / \ / + I B R + \ / / + \ / / + `---X--' +----------------------------------------------------------------------- ++ +Notice that since `M` is reachable from `R`, the edge from `N` to `M` +was simplified away. However, `N` still appears in the history as an +important commit because it "pulled" the change `R` into the main +branch. + The `--simplify-by-decoration` option allows you to view only the big picture of the topology of the history, by omitting commits that are not referenced by tags. Commits are marked as !TREESAME @@ -575,6 +713,7 @@ above) if (1) they are referenced by tags, or (2) they change the contents of the paths given on the command line. All other commits are marked as TREESAME (subject to be simplified away). +ifndef::git-shortlog[] ifdef::git-rev-list[] Bisection Helpers ~~~~~~~~~~~~~~~~~ @@ -630,8 +769,9 @@ This option can be used along with `--bisect-vars`, in this case, after all the sorted commit objects, there will be the same text as if `--bisect-vars` had been used alone. endif::git-rev-list[] +endif::git-shortlog[] - +ifndef::git-shortlog[] Commit Ordering ~~~~~~~~~~~~~~~ @@ -673,7 +813,9 @@ together. Output the commits chosen to be shown (see Commit Limiting section above) in reverse order. Cannot be combined with `--walk-reflogs`. +endif::git-shortlog[] +ifndef::git-shortlog[] Object Traversal ~~~~~~~~~~~~~~~~ @@ -712,6 +854,16 @@ ifdef::git-rev-list[] Only useful with `--objects`; print the object IDs that are not in packs. +--object-names:: + Only useful with `--objects`; print the names of the object IDs + that are found. This is the default behavior. + +--no-object-names:: + Only useful with `--objects`; does not print the names of the object + IDs that are found. This inverts `--object-names`. This flag allows + the output to be more easily parsed by commands such as + linkgit:git-cat-file[1]. + --filter=<filter-spec>:: Only useful with one of the `--objects*`; omits objects (usually blobs) from the list of printed objects. The '<filter-spec>' @@ -729,15 +881,42 @@ specification contained in the blob (or blob-expression) '<blob-ish>' to omit blobs that would not be not required for a sparse checkout on the requested refs. + -The form '--filter=sparse:path=<path>' similarly uses a sparse-checkout -specification contained in <path>. +The form '--filter=tree:<depth>' omits all blobs and trees whose depth +from the root tree is >= <depth> (minimum depth if an object is located +at multiple depths in the commits traversed). <depth>=0 will not include +any trees or blobs unless included explicitly in the command-line (or +standard input when --stdin is used). <depth>=1 will include only the +tree and blobs which are referenced directly by a commit reachable from +<commit> or an explicitly-given object. <depth>=2 is like <depth>=1 +while also including trees and blobs one more level removed from an +explicitly-given commit or tree. ++ +Note that the form '--filter=sparse:path=<path>' that wants to read +from an arbitrary path on the filesystem has been dropped for security +reasons. ++ +Multiple '--filter=' flags can be specified to combine filters. Only +objects which are accepted by every filter are included. ++ +The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be +used to combined several filters, but this is harder than just repeating +the '--filter' flag and is usually not necessary. Filters are joined by +'{plus}' and individual filters are %-encoded (i.e. URL-encoded). +Besides the '{plus}' and '%' characters, the following characters are +reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+ +as well as all characters with ASCII code <= `0x20`, which includes +space and newline. ++ +Other arbitrary characters can also be encoded. For instance, +'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are +equivalent. --no-filter:: Turn off any previous `--filter=` argument. --filter-print-omitted:: Only useful with `--filter=`; prints a list of the objects omitted - by the filter. Object IDs are prefixed with a ``~'' character. + by the filter. Object IDs are prefixed with a ``~'' character. --missing=<missing-action>:: A debug option to help with future "partial clone" development. @@ -756,7 +935,6 @@ 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. -endif::git-rev-list[] --exclude-promisor-objects:: (For internal use only.) Prefilter object traversal at @@ -764,6 +942,7 @@ endif::git-rev-list[] stronger than `--missing=allow-promisor` because it limits the traversal, rather than just silencing errors about missing objects. +endif::git-rev-list[] --no-walk[=(sorted|unsorted)]:: Only show the given commits, but do not traverse their ancestors. @@ -776,7 +955,9 @@ endif::git-rev-list[] --do-walk:: Overrides a previous `--no-walk`. +endif::git-shortlog[] +ifndef::git-shortlog[] Commit Formatting ~~~~~~~~~~~~~~~~~ @@ -799,12 +980,13 @@ include::pretty-options.txt[] author's). If `-local` is appended to the format (e.g., `iso-local`), the user's local time zone is used instead. + +-- `--date=relative` shows dates relative to the current time, e.g. ``2 hours ago''. The `-local` option has no effect for `--date=relative`. -+ + `--date=local` is an alias for `--date=default-local`. -+ + `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. The differences to the strict ISO 8601 format are: @@ -812,15 +994,14 @@ The differences to the strict ISO 8601 format are: - a space between time and time zone - no colon between hours and minutes of the time zone -+ `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict ISO 8601 format. -+ + `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 format, often found in email messages. -+ + `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. -+ + `--date=raw` shows the date as seconds since the epoch (1970-01-01 00:00:00 UTC), followed by a space, and then the timezone as an offset from UTC (a `+` or `-` with four digits; the first two are hours, and @@ -829,21 +1010,28 @@ with `strftime("%s %z")`). Note that the `-local` option does not affect the seconds-since-epoch value (which is always measured in UTC), but does switch the accompanying timezone value. -+ + +`--date=human` shows the timezone if the timezone does not match the +current time-zone, and doesn't print the whole date if that matches +(ie skip printing year for dates that are "this year", but also skip +the whole date itself if it's in the last few days and we can just say +what weekday it was). For older dates the hour and minute is also +omitted. + `--date=unix` shows the date as a Unix epoch timestamp (seconds since 1970). As with `--raw`, this is always in UTC and therefore `-local` has no effect. -+ + `--date=format:...` feeds the format `...` to your system `strftime`, except for %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: - +-- - there is no comma after the day-of-week - the time zone is omitted when the local time zone is used @@ -925,7 +1113,9 @@ ifdef::git-rev-list[] counts and print the count for equivalent commits separated by a tab. endif::git-rev-list[] +endif::git-shortlog[] +ifndef::git-shortlog[] ifndef::git-rev-list[] Diff Formatting ~~~~~~~~~~~~~~~ @@ -947,6 +1137,13 @@ options may be given. See linkgit:git-diff-files[1] for more options. the parents have only two variants and the merge result picks one of them without modification. +--combined-all-paths:: + This flag causes combined diffs (used for merge commits) to + list the name of the file from all parents. It thus only has + effect when -c or --cc are specified, and is likely only + useful if filename changes are detected (i.e. when either + rename or copy detection have been requested). + -m:: This flag makes the merge commits show the full diff like regular commits; for each merge parent, a separate log entry @@ -961,3 +1158,4 @@ options may be given. See linkgit:git-diff-files[1] for more options. -t:: Show the tree objects in the diff output. This implies `-r`. endif::git-rev-list[] +endif::git-shortlog[] diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 72daa20e76..1ad95065c1 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -58,14 +58,14 @@ when you run `git merge`. when you run `git cherry-pick`. + 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. +the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. '@':: '@' alone is a shortcut for `HEAD`. -'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: +'[<refname>]@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: A ref followed by the suffix '@' with a date specification enclosed in a brace pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8. The construct '@{-<n>}' means the <n>th branch/commit checked out before the current one. -'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: +'[<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 @@ -103,19 +103,19 @@ some output processing may assume ref names in UTF-8. current one. These suffixes are also accepted when spelled in uppercase, and they mean the same thing no matter the case. -'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: +'[<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/'). + that corresponds to that branch (i.e., something in `refs/remotes/`). + Here's an example to make it more clear: + ------------------------------ $ git config push.default current $ git config remote.pushdefault myfork -$ git checkout -b mybranch origin/master +$ git switch -c mybranch origin/master $ git rev-parse --symbolic-full-name @{upstream} refs/remotes/origin/master @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow, This suffix is also accepted when spelled in uppercase, and means the same thing no matter the case. -'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: +'<rev>{caret}[<n>]', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}<n>' means the <n>th parent (i.e. '<rev>{caret}' @@ -139,7 +139,9 @@ thing no matter the case. '<rev>{caret}0' means the commit itself and is used when '<rev>' is the object name of a tag object that refers to a commit object. -'<rev>{tilde}<n>', e.g. 'master{tilde}3':: +'<rev>{tilde}[<n>]', e.g. 'HEAD{tilde}, master{tilde}3':: + A suffix '{tilde}' to a revision parameter means the first parent of + that commit object. A suffix '{tilde}<n>' to a revision parameter means the commit object that is the <n>th generation ancestor of the named commit object, following only the first parents. I.e. '<rev>{tilde}3' is @@ -159,12 +161,12 @@ thing no matter the case. '<rev>{caret}0' is a short-hand for '<rev>{caret}\{commit\}'. + -'rev{caret}\{object\}' can be used to make sure 'rev' names an -object that exists, without requiring 'rev' to be a tag, and -without dereferencing 'rev'; because a tag is already an object, +'<rev>{caret}\{object\}' can be used to make sure '<rev>' names an +object that exists, without requiring '<rev>' to be a tag, and +without dereferencing '<rev>'; because a tag is already an object, it does not have to be dereferenced even once to get to an object. + -'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an +'<rev>{caret}\{tag\}' can be used to ensure that '<rev>' identifies an existing tag object. '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}':: @@ -194,19 +196,16 @@ existing tag object. Depending on the given text, the shell's word splitting rules might require additional quoting. -'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: +'<rev>:<path>', e.g. 'HEAD:README', 'master:./README':: A suffix ':' followed by a path names the blob or tree at the given path in the tree-ish object named by the part before the colon. - ':path' (with an empty part before the colon) - is a special case of the syntax described next: content - recorded in the index at the given path. A path starting with './' or '../' is relative to the current working directory. The given path will be converted to be relative to the working tree's root directory. This is most useful to address a blob or tree from a commit or tree that has the same tree structure as the working tree. -':<n>:<path>', e.g. ':0:README', ':README':: +':[<n>:]<path>', e.g. ':0:README', ':README':: A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path, names a blob object in the index at the given path. A missing stage number (and the colon @@ -234,7 +233,7 @@ G H I J A = = A^0 B = A^ = A^1 = A~1 - C = A^2 = A^2 + C = = A^2 D = A^^ = A^1^1 = A~2 E = B^2 = A^^2 F = B^3 = A^^3 @@ -302,7 +301,7 @@ The 'r1{caret}@' notation means all parents of 'r1'. The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. By itself, this notation denotes the single commit 'r1'. -The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th +The '<rev>{caret}-[<n>]' notation includes '<rev>' but excludes the <n>th parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if not given. This is typically useful for merge commits where you can just pass '<commit>{caret}-' to get all the commits in the branch diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.txt index 5747f442f2..3bceb56474 100644 --- a/Documentation/sequencer.txt +++ b/Documentation/sequencer.txt @@ -1,8 +1,12 @@ --continue:: Continue the operation in progress using the information in - '.git/sequencer'. Can be used to continue after resolving + `.git/sequencer`. Can be used to continue after resolving conflicts in a failed cherry-pick or revert. +--skip:: + Skip the current commit and continue with the rest of the + sequence. + --quit:: Forget about the current operation in progress. Can be used to clear the sequencer state after a failed cherry-pick or diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt deleted file mode 100644 index 5a59b54844..0000000000 --- a/Documentation/technical/api-allocation-growing.txt +++ /dev/null @@ -1,39 +0,0 @@ -allocation growing API -====================== - -Dynamically growing an array using realloc() is error prone and boring. - -Define your array with: - -* a pointer (`item`) that points at the array, initialized to `NULL` - (although please name the variable based on its contents, not on its - type); - -* an integer variable (`alloc`) that keeps track of how big the current - allocation is, initialized to `0`; - -* another integer variable (`nr`) to keep track of how many elements the - array currently has, initialized to `0`. - -Then before adding `n`th element to the item, call `ALLOC_GROW(item, n, -alloc)`. This ensures that the array can hold at least `n` elements by -calling `realloc(3)` and adjusting `alloc` variable. - ------------- -sometype *item; -size_t nr; -size_t alloc - -for (i = 0; i < nr; i++) - if (we like item[i] already) - return; - -/* we did not like any existing one, so add one */ -ALLOC_GROW(item, nr + 1, alloc); -item[nr++] = value you like; ------------- - -You are responsible for updating the `nr` variable. - -If you need to specify the number of elements to allocate explicitly -then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt deleted file mode 100644 index 870c8edbfb..0000000000 --- a/Documentation/technical/api-argv-array.txt +++ /dev/null @@ -1,65 +0,0 @@ -argv-array API -============== - -The argv-array API allows one to dynamically build and store -NULL-terminated lists. An argv-array maintains the invariant that the -`argv` member always points to a non-NULL array, and that the array is -always NULL-terminated at the element pointed to by `argv[argc]`. This -makes the result suitable for passing to functions expecting to receive -argv from main(), or the link:api-run-command.html[run-command API]. - -The string-list API (documented in string-list.h) is similar, but cannot be -used for these purposes; instead of storing a straight string pointer, -it contains an item structure with a `util` field that is not compatible -with the traditional argv interface. - -Each `argv_array` manages its own memory. Any strings pushed into the -array are duplicated, and all memory is freed by argv_array_clear(). - -Data Structures ---------------- - -`struct argv_array`:: - - A single array. This should be initialized by assignment from - `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv` - member contains the actual array; the `argc` member contains the - number of elements in the array, not including the terminating - NULL. - -Functions ---------- - -`argv_array_init`:: - Initialize an array. This is no different than assigning from - `ARGV_ARRAY_INIT`. - -`argv_array_push`:: - Push a copy of a string onto the end of the array. - -`argv_array_pushl`:: - Push a list of strings onto the end of the array. The arguments - should be a list of `const char *` strings, terminated by a NULL - argument. - -`argv_array_pushf`:: - Format a string and push it onto the end of the array. This is a - convenience wrapper combining `strbuf_addf` and `argv_array_push`. - -`argv_array_pushv`:: - Push a null-terminated array of strings onto the end of the array. - -`argv_array_pop`:: - Remove the final element from the array. If there are no - elements in the array, do nothing. - -`argv_array_clear`:: - Free all memory associated with the array and return it to the - initial, empty state. - -`argv_array_detach`:: - Disconnect the `argv` member from the `argv_array` struct and - return it. The caller is responsible for freeing the memory used - by the array, and by the strings it references. After detaching, - the `argv_array` is in a reinitialized state and can be pushed - into again. diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt deleted file mode 100644 index fa39ac9d71..0000000000 --- a/Documentation/technical/api-config.txt +++ /dev/null @@ -1,319 +0,0 @@ -config API -========== - -The config API gives callers a way to access Git configuration files -(and files which have the same syntax). See linkgit:git-config[1] for a -discussion of the config file syntax. - -General Usage -------------- - -Config files are parsed linearly, and each variable found is passed to a -caller-provided callback function. The callback function is responsible -for any actions to be taken on the config option, and is free to ignore -some options. It is not uncommon for the configuration to be parsed -several times during the run of a Git program, with different callbacks -picking out different variables useful to themselves. - -A config callback function takes three parameters: - -- the name of the parsed variable. This is in canonical "flat" form: the - section, subsection, and variable segments will be separated by dots, - and the section and variable segments will be all lowercase. E.g., - `core.ignorecase`, `diff.SomeType.textconv`. - -- the value of the found variable, as a string. If the variable had no - value specified, the value will be NULL (typically this means it - should be interpreted as boolean true). - -- a void pointer passed in by the caller of the config API; this can - contain callback-specific data - -A config callback should return 0 for success, or -1 if the variable -could not be parsed properly. - -Basic Config Querying ---------------------- - -Most programs will simply want to look up variables in all config files -that Git knows about, using the normal precedence rules. To do this, -call `git_config` with a callback function and void data pointer. - -`git_config` will read all config sources in order of increasing -priority. Thus a callback should typically overwrite previously-seen -entries with new ones (e.g., if both the user-wide `~/.gitconfig` and -repo-specific `.git/config` contain `color.ui`, the config machinery -will first feed the user-wide one to the callback, and then the -repo-specific one; by overwriting, the higher-priority repo-specific -value is left at the end). - -The `config_with_options` function lets the caller examine config -while adjusting some of the default behavior of `git_config`. It should -almost never be used by "regular" Git code that is looking up -configuration variables. It is intended for advanced callers like -`git-config`, which are intentionally tweaking the normal config-lookup -process. It takes two extra parameters: - -`config_source`:: -If this parameter is non-NULL, it specifies the source to parse for -configuration, rather than looking in the usual files. See `struct -git_config_source` in `config.h` for details. Regular `git_config` defaults -to `NULL`. - -`opts`:: -Specify options to adjust the behavior of parsing config files. See `struct -config_options` in `config.h` for details. As an example: regular `git_config` -sets `opts.respect_includes` to `1` by default. - -Reading Specific Files ----------------------- - -To read a specific file in git-config format, use -`git_config_from_file`. This takes the same callback and data parameters -as `git_config`. - -Querying For Specific Variables -------------------------------- - -For programs wanting to query for specific variables in a non-callback -manner, the config API provides two functions `git_config_get_value` -and `git_config_get_value_multi`. They both read values from an internal -cache generated previously from reading the config files. - -`int git_config_get_value(const char *key, const char **value)`:: - - Finds the highest-priority value for the configuration variable `key`, - stores the pointer to it in `value` and returns 0. When the - configuration variable `key` is not found, returns 1 without touching - `value`. The caller should not free or modify `value`, as it is owned - by the cache. - -`const struct string_list *git_config_get_value_multi(const char *key)`:: - - Finds and returns the value list, sorted in order of increasing priority - for the configuration variable `key`. When the configuration variable - `key` is not found, returns NULL. The caller should not free or modify - the returned pointer, as it is owned by the cache. - -`void git_config_clear(void)`:: - - Resets and invalidates the config cache. - -The config API also provides type specific API functions which do conversion -as well as retrieval for the queried variable, including: - -`int git_config_get_int(const char *key, int *dest)`:: - - Finds and parses the value to an integer for the configuration variable - `key`. Dies on error; otherwise, stores the value of the parsed integer in - `dest` and returns 0. When the configuration variable `key` is not found, - returns 1 without touching `dest`. - -`int git_config_get_ulong(const char *key, unsigned long *dest)`:: - - Similar to `git_config_get_int` but for unsigned longs. - -`int git_config_get_bool(const char *key, int *dest)`:: - - Finds and parses the value into a boolean value, for the configuration - variable `key` respecting keywords like "true" and "false". Integer - values are converted into true/false values (when they are non-zero or - zero, respectively). Other values cause a die(). If parsing is successful, - stores the value of the parsed result in `dest` and returns 0. When the - configuration variable `key` is not found, returns 1 without touching - `dest`. - -`int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest)`:: - - Similar to `git_config_get_bool`, except that integers are copied as-is, - and `is_bool` flag is unset. - -`int git_config_get_maybe_bool(const char *key, int *dest)`:: - - Similar to `git_config_get_bool`, except that it returns -1 on error - rather than dying. - -`int git_config_get_string_const(const char *key, const char **dest)`:: - - Allocates and copies the retrieved string into the `dest` parameter for - the configuration variable `key`; if NULL string is given, prints an - error message and returns -1. When the configuration variable `key` is - not found, returns 1 without touching `dest`. - -`int git_config_get_string(const char *key, char **dest)`:: - - Similar to `git_config_get_string_const`, except that retrieved value - copied into the `dest` parameter is a mutable string. - -`int git_config_get_pathname(const char *key, const char **dest)`:: - - Similar to `git_config_get_string`, but expands `~` or `~user` into - the user's home directory when found at the beginning of the path. - -`git_die_config(const char *key, const char *err, ...)`:: - - First prints the error message specified by the caller in `err` and then - dies printing the line number and the file name of the highest priority - value for the configuration variable `key`. - -`void git_die_config_linenr(const char *key, const char *filename, int linenr)`:: - - Helper function which formats the die error message according to the - parameters entered. Used by `git_die_config()`. It can be used by callers - handling `git_config_get_value_multi()` to print the correct error message - for the desired value. - -See test-config.c for usage examples. - -Value Parsing Helpers ---------------------- - -To aid in parsing string values, the config API provides callbacks with -a number of helper functions, including: - -`git_config_int`:: -Parse the string to an integer, including unit factors. Dies on error; -otherwise, returns the parsed result. - -`git_config_ulong`:: -Identical to `git_config_int`, but for unsigned longs. - -`git_config_bool`:: -Parse a string into a boolean value, respecting keywords like "true" and -"false". Integer values are converted into true/false values (when they -are non-zero or zero, respectively). Other values cause a die(). If -parsing is successful, the return value is the result. - -`git_config_bool_or_int`:: -Same as `git_config_bool`, except that integers are returned as-is, and -an `is_bool` flag is unset. - -`git_parse_maybe_bool`:: -Same as `git_config_bool`, except that it returns -1 on error rather -than dying. - -`git_config_string`:: -Allocates and copies the value string into the `dest` parameter; if no -string is given, prints an error message and returns -1. - -`git_config_pathname`:: -Similar to `git_config_string`, but expands `~` or `~user` into the -user's home directory when found at the beginning of the path. - -Include Directives ------------------- - -By default, the config parser does not respect include directives. -However, a caller can use the special `git_config_include` wrapper -callback to support them. To do so, you simply wrap your "real" callback -function and data pointer in a `struct config_include_data`, and pass -the wrapper to the regular config-reading functions. For example: - -------------------------------------------- -int read_file_with_include(const char *file, config_fn_t fn, void *data) -{ - struct config_include_data inc = CONFIG_INCLUDE_INIT; - inc.fn = fn; - inc.data = data; - return git_config_from_file(git_config_include, file, &inc); -} -------------------------------------------- - -`git_config` respects includes automatically. The lower-level -`git_config_from_file` does not. - -Custom Configsets ------------------ - -A `config_set` can be used to construct an in-memory cache for -config-like files that the caller specifies (i.e., files like `.gitmodules`, -`~/.gitconfig` etc.). For example, - ---------------------------------------- -struct config_set gm_config; -git_configset_init(&gm_config); -int b; -/* we add config files to the config_set */ -git_configset_add_file(&gm_config, ".gitmodules"); -git_configset_add_file(&gm_config, ".gitmodules_alt"); - -if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) { - /* hack hack hack */ -} - -/* when we are done with the configset */ -git_configset_clear(&gm_config); ----------------------------------------- - -Configset API provides functions for the above mentioned work flow, including: - -`void git_configset_init(struct config_set *cs)`:: - - Initializes the config_set `cs`. - -`int git_configset_add_file(struct config_set *cs, const char *filename)`:: - - Parses the file and adds the variable-value pairs to the `config_set`, - dies if there is an error in parsing the file. Returns 0 on success, or - -1 if the file does not exist or is inaccessible. The user has to decide - if he wants to free the incomplete configset or continue using it when - the function returns -1. - -`int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`:: - - Finds the highest-priority value for the configuration variable `key` - and config set `cs`, stores the pointer to it in `value` and returns 0. - When the configuration variable `key` is not found, returns 1 without - touching `value`. The caller should not free or modify `value`, as it - is owned by the cache. - -`const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`:: - - Finds and returns the value list, sorted in order of increasing priority - for the configuration variable `key` and config set `cs`. When the - configuration variable `key` is not found, returns NULL. The caller - should not free or modify the returned pointer, as it is owned by the cache. - -`void git_configset_clear(struct config_set *cs)`:: - - Clears `config_set` structure, removes all saved variable-value pairs. - -In addition to above functions, the `config_set` API provides type specific -functions in the vein of `git_config_get_int` and family but with an extra -parameter, pointer to struct `config_set`. -They all behave similarly to the `git_config_get*()` family described in -"Querying For Specific Variables" above. - -Writing Config Files --------------------- - -Git gives multiple entry points in the Config API to write config values to -files namely `git_config_set_in_file` and `git_config_set`, which write to -a specific config file or to `.git/config` respectively. They both take a -key/value pair as parameter. -In the end they both call `git_config_set_multivar_in_file` which takes four -parameters: - -- the name of the file, as a string, to which key/value pairs will be written. - -- the name of key, as a string. This is in canonical "flat" form: the section, - subsection, and variable segments will be separated by dots, and the section - and variable segments will be all lowercase. - E.g., `core.ignorecase`, `diff.SomeType.textconv`. - -- the value of the variable, as a string. If value is equal to NULL, it will - remove the matching key from the config file. - -- the value regex, as a string. It will disregard key/value pairs where value - does not match. - -- a multi_replace value, as an int. If value is equal to zero, nothing or only - one matching key/value is replaced, else all matching key/values (regardless - how many) are removed, before the new pair is written. - -It returns 0 on success. - -Also, there are functions `git_config_rename_section` and -`git_config_rename_section_in_file` with parameters `old_name` and `new_name` -for renaming or removing sections in the config files. If NULL is passed -through `new_name` parameter, the section will be removed from the config file. diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt deleted file mode 100644 index 75368f26ca..0000000000 --- a/Documentation/technical/api-credentials.txt +++ /dev/null @@ -1,271 +0,0 @@ -credentials API -=============== - -The credentials API provides an abstracted way of gathering username and -password credentials from the user (even though credentials in the wider -world can take many forms, in this document the word "credential" always -refers to a username and password pair). - -This document describes two interfaces: the C API that the credential -subsystem provides to the rest of Git, and the protocol that Git uses to -communicate with system-specific "credential helpers". If you are -writing Git code that wants to look up or prompt for credentials, see -the section "C API" below. If you want to write your own helper, see -the section on "Credential Helpers" below. - -Typical setup -------------- - ------------- -+-----------------------+ -| Git code (C) |--- to server requiring ---> -| | authentication -|.......................| -| C credential API |--- prompt ---> User -+-----------------------+ - ^ | - | pipe | - | v -+-----------------------+ -| Git credential helper | -+-----------------------+ ------------- - -The Git code (typically a remote-helper) will call the C API to obtain -credential data like a login/password pair (credential_fill). The -API will itself call a remote helper (e.g. "git credential-cache" or -"git credential-store") that may retrieve credential data from a -store. If the credential helper cannot find the information, the C API -will prompt the user. Then, the caller of the API takes care of -contacting the server, and does the actual authentication. - -C API ------ - -The credential C API is meant to be called by Git code which needs to -acquire or store a credential. It is centered around an object -representing a single credential and provides three basic operations: -fill (acquire credentials by calling helpers and/or prompting the user), -approve (mark a credential as successfully used so that it can be stored -for later use), and reject (mark a credential as unsuccessful so that it -can be erased from any persistent storage). - -Data Structures -~~~~~~~~~~~~~~~ - -`struct credential`:: - - This struct represents a single username/password combination - along with any associated context. All string fields should be - heap-allocated (or NULL if they are not known or not applicable). - The meaning of the individual context fields is the same as - their counterparts in the helper protocol; see the section below - for a description of each field. -+ -The `helpers` member of the struct is a `string_list` of helpers. Each -string specifies an external helper which will be run, in order, to -either acquire or store credentials. See the section on credential -helpers below. This list is filled-in by the API functions -according to the corresponding configuration variables before -consulting helpers, so there usually is no need for a caller to -modify the helpers field at all. -+ -This struct should always be initialized with `CREDENTIAL_INIT` or -`credential_init`. - - -Functions -~~~~~~~~~ - -`credential_init`:: - - Initialize a credential structure, setting all fields to empty. - -`credential_clear`:: - - Free any resources associated with the credential structure, - returning it to a pristine initialized state. - -`credential_fill`:: - - Instruct the credential subsystem to fill the username and - password fields of the passed credential struct by first - consulting helpers, then asking the user. After this function - returns, the username and password fields of the credential are - guaranteed to be non-NULL. If an error occurs, the function will - die(). - -`credential_reject`:: - - Inform the credential subsystem that the provided credentials - have been rejected. This will cause the credential subsystem to - notify any helpers of the rejection (which allows them, for - example, to purge the invalid credentials from storage). It - will also free() the username and password fields of the - credential and set them to NULL (readying the credential for - another call to `credential_fill`). Any errors from helpers are - ignored. - -`credential_approve`:: - - Inform the credential subsystem that the provided credentials - were successfully used for authentication. This will cause the - credential subsystem to notify any helpers of the approval, so - that they may store the result to be used again. Any errors - from helpers are ignored. - -`credential_from_url`:: - - Parse a URL into broken-down credential fields. - -Example -~~~~~~~ - -The example below shows how the functions of the credential API could be -used to login to a fictitious "foo" service on a remote host: - ------------------------------------------------------------------------ -int foo_login(struct foo_connection *f) -{ - int status; - /* - * Create a credential with some context; we don't yet know the - * username or password. - */ - - struct credential c = CREDENTIAL_INIT; - c.protocol = xstrdup("foo"); - c.host = xstrdup(f->hostname); - - /* - * Fill in the username and password fields by contacting - * helpers and/or asking the user. The function will die if it - * fails. - */ - credential_fill(&c); - - /* - * Otherwise, we have a username and password. Try to use it. - */ - status = send_foo_login(f, c.username, c.password); - switch (status) { - case FOO_OK: - /* It worked. Store the credential for later use. */ - credential_accept(&c); - break; - case FOO_BAD_LOGIN: - /* Erase the credential from storage so we don't try it - * again. */ - credential_reject(&c); - break; - default: - /* - * Some other error occurred. We don't know if the - * credential is good or bad, so report nothing to the - * credential subsystem. - */ - } - - /* Free any associated resources. */ - credential_clear(&c); - - return status; -} ------------------------------------------------------------------------ - - -Credential Helpers ------------------- - -Credential helpers are programs executed by Git to fetch or save -credentials from and to long-term storage (where "long-term" is simply -longer than a single Git process; e.g., credentials may be stored -in-memory for a few minutes, or indefinitely on disk). - -Each helper is specified by a single string in the configuration -variable `credential.helper` (and others, see linkgit:git-config[1]). -The string is transformed by Git into a command to be executed using -these rules: - - 1. If the helper string begins with "!", it is considered a shell - snippet, and everything after the "!" becomes the command. - - 2. Otherwise, if the helper string begins with an absolute path, the - verbatim helper string becomes the command. - - 3. Otherwise, the string "git credential-" is prepended to the helper - string, and the result becomes the command. - -The resulting command then has an "operation" argument appended to it -(see below for details), and the result is executed by the shell. - -Here are some example specifications: - ----------------------------------------------------- -# run "git credential-foo" -foo - -# same as above, but pass an argument to the helper -foo --bar=baz - -# the arguments are parsed by the shell, so use shell -# quoting if necessary -foo --bar="whitespace arg" - -# you can also use an absolute path, which will not use the git wrapper -/path/to/my/helper --with-arguments - -# or you can specify your own shell snippet -!f() { echo "password=`cat $HOME/.secret`"; }; f ----------------------------------------------------- - -Generally speaking, rule (3) above is the simplest for users to specify. -Authors of credential helpers should make an effort to assist their -users by naming their program "git-credential-$NAME", and putting it in -the $PATH or $GIT_EXEC_PATH during installation, which will allow a user -to enable it with `git config credential.helper $NAME`. - -When a helper is executed, it will have one "operation" argument -appended to its command line, which is one of: - -`get`:: - - Return a matching credential, if any exists. - -`store`:: - - Store the credential, if applicable to the helper. - -`erase`:: - - Remove a matching credential, 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 -`git credential` plumbing command (see the section `INPUT/OUTPUT -FORMAT` in linkgit:git-credential[1] for a detailed specification). - -For a `get` operation, the helper should produce a list of attributes -on stdout in the same format. 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. If a helper -outputs a `quit` attribute with a value of `true` or `1`, no further -helpers will be consulted, nor will the user be prompted (if no -credential has been provided, the operation will then fail). - -For a `store` or `erase` operation, the helper's output is ignored. -If it fails to perform the requested operation, it may complain to -stderr to inform the user. If it does not support the requested -operation (e.g., a read-only store), 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 -helpers will just ignore the new requests). - -See also --------- - -linkgit:gitcredentials[7] - -linkgit:git-config[1] (See configuration variables `credential.*`) diff --git a/Documentation/technical/api-diff.txt b/Documentation/technical/api-diff.txt deleted file mode 100644 index 8b001de0db..0000000000 --- a/Documentation/technical/api-diff.txt +++ /dev/null @@ -1,174 +0,0 @@ -diff API -======== - -The diff API is for programs that compare two sets of files (e.g. two -trees, one tree and the index) and present the found difference in -various ways. The calling program is responsible for feeding the API -pairs of files, one from the "old" set and the corresponding one from -"new" set, that are different. The library called through this API is -called diffcore, and is responsible for two things. - -* finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and - changes that touch a string (`-S`), as specified by the caller. - -* outputting the differences in various formats, as specified by the - caller. - -Calling sequence ----------------- - -* Prepare `struct diff_options` to record the set of diff options, and - then call `diff_setup()` to initialize this structure. This sets up - the vanilla default. - -* Fill in the options structure to specify desired output format, rename - detection, etc. `diff_opt_parse()` can be used to parse options given - from the command line in a way consistent with existing git-diff - family of programs. - -* Call `diff_setup_done()`; this inspects the options set up so far for - internal consistency and make necessary tweaking to it (e.g. if - textual patch output was asked, recursive behaviour is turned on); - the callback set_default in diff_options can be used to tweak this more. - -* As you find different pairs of files, call `diff_change()` to feed - modified files, `diff_addremove()` to feed created or deleted files, - or `diff_unmerge()` to feed a file whose state is 'unmerged' to the - API. These are thin wrappers to a lower-level `diff_queue()` function - that is flexible enough to record any of these kinds of changes. - -* Once you finish feeding the pairs of files, call `diffcore_std()`. - This will tell the diffcore library to go ahead and do its work. - -* Calling `diff_flush()` will produce the output. - - -Data structures ---------------- - -* `struct diff_filespec` - -This is the internal representation for a single file (blob). It -records the blob object name (if known -- for a work tree file it -typically is a NUL SHA-1), filemode and pathname. This is what the -`diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and -feed `diff_queue()` function with. - -* `struct diff_filepair` - -This records a pair of `struct diff_filespec`; the filespec for a file -in the "old" set (i.e. preimage) is called `one`, and the filespec for a -file in the "new" set (i.e. postimage) is called `two`. A change that -represents file creation has NULL in `one`, and file deletion has NULL -in `two`. - -A `filepair` starts pointing at `one` and `two` that are from the same -filename, but `diffcore_std()` can break pairs and match component -filespecs with other filespecs from a different filepair to form new -filepair. This is called 'rename detection'. - -* `struct diff_queue` - -This is a collection of filepairs. Notable members are: - -`queue`:: - - An array of pointers to `struct diff_filepair`. This - dynamically grows as you add filepairs; - -`alloc`:: - - The allocated size of the `queue` array; - -`nr`:: - - The number of elements in the `queue` array. - - -* `struct diff_options` - -This describes the set of options the calling program wants to affect -the operation of diffcore library with. - -Notable members are: - -`output_format`:: - The output format used when `diff_flush()` is run. - -`context`:: - Number of context lines to generate in patch output. - -`break_opt`, `detect_rename`, `rename-score`, `rename_limit`:: - Affects the way detection logic for complete rewrites, renames - and copies. - -`abbrev`:: - Number of hexdigits to abbreviate raw format output to. - -`pickaxe`:: - A constant string (can and typically does contain newlines to - look for a block of text, not just a single line) to filter out - the filepairs that do not change the number of strings contained - in its preimage and postimage of the diff_queue. - -`flags`:: - This is mostly a collection of boolean options that affects the - operation, but some do not have anything to do with the diffcore - library. - -`touched_flags`:: - Records whether a flag has been changed due to user request - (rather than just set/unset by default). - -`set_default`:: - Callback which allows tweaking the options in diff_setup_done(). - -BINARY, TEXT;; - Affects the way how a file that is seemingly binary is treated. - -FULL_INDEX;; - Tells the patch output format not to use abbreviated object - names on the "index" lines. - -FIND_COPIES_HARDER;; - Tells the diffcore library that the caller is feeding unchanged - filepairs to allow copies from unmodified files be detected. - -COLOR_DIFF;; - Output should be colored. - -COLOR_DIFF_WORDS;; - Output is a colored word-diff. - -NO_INDEX;; - Tells diff-files that the input is not tracked files but files - in random locations on the filesystem. - -ALLOW_EXTERNAL;; - Tells output routine that it is Ok to call user specified patch - output routine. Plumbing disables this to ensure stable output. - -QUIET;; - Do not show any output. - -REVERSE_DIFF;; - Tells the library that the calling program is feeding the - filepairs reversed; `one` is two, and `two` is one. - -EXIT_WITH_STATUS;; - For communication between the calling program and the options - parser; tell the calling program to signal the presence of - difference using program exit code. - -HAS_CHANGES;; - Internal; used for optimization to see if there is any change. - -SILENT_ON_REMOVE;; - Affects if diff-files shows removed files. - -RECURSIVE, TREE_IN_RECURSIVE;; - Tells if tree traversal done by tree-diff should recursively - descend into a tree object pair that are different in preimage - and postimage set. - -(JC) diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt deleted file mode 100644 index 5abb8e8b1f..0000000000 --- a/Documentation/technical/api-directory-listing.txt +++ /dev/null @@ -1,130 +0,0 @@ -directory listing API -===================== - -The directory listing API is used to enumerate paths in the work tree, -optionally taking `.git/info/exclude` and `.gitignore` files per -directory into account. - -Data structure --------------- - -`struct dir_struct` structure is used to pass directory traversal -options to the library and to record the paths discovered. A single -`struct dir_struct` is used regardless of whether or not the traversal -recursively descends into subdirectories. - -The notable options are: - -`exclude_per_dir`:: - - The name of the file to be read in each directory for excluded - files (typically `.gitignore`). - -`flags`:: - - A bit-field of options: - -`DIR_SHOW_IGNORED`::: - - Return just ignored files in `entries[]`, not untracked - files. This flag is mutually exclusive with - `DIR_SHOW_IGNORED_TOO`. - -`DIR_SHOW_IGNORED_TOO`::: - - Similar to `DIR_SHOW_IGNORED`, but return ignored files in - `ignored[]` in addition to untracked files in - `entries[]`. This flag is mutually exclusive with - `DIR_SHOW_IGNORED`. - -`DIR_KEEP_UNTRACKED_CONTENTS`::: - - Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is set, the - untracked contents of untracked directories are also returned in - `entries[]`. - -`DIR_SHOW_IGNORED_TOO_MODE_MATCHING`::: - - Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if - this is set, returns ignored files and directories that match - an exclude pattern. If a directory matches an exclude pattern, - then the directory is returned and the contained paths are - not. A directory that does not match an exclude pattern will - not be returned even if all of its contents are ignored. In - this case, the contents are returned as individual entries. -+ -If this is set, files and directories that explicitly match an ignore -pattern are reported. Implicitly ignored directories (directories that -do not match an ignore pattern, but whose contents are all ignored) -are not reported, instead all of the contents are reported. - -`DIR_COLLECT_IGNORED`::: - - Special mode for git-add. Return ignored files in `ignored[]` and - untracked files in `entries[]`. Only returns ignored files that match - pathspec exactly (no wildcards). Does not recurse into ignored - directories. - -`DIR_SHOW_OTHER_DIRECTORIES`::: - - Include a directory that is not tracked. - -`DIR_HIDE_EMPTY_DIRECTORIES`::: - - Do not include a directory that is not tracked and is empty. - -`DIR_NO_GITLINKS`::: - - If set, recurse into a directory that looks like a Git - directory. Otherwise it is shown as a directory. - -The result of the enumeration is left in these fields: - -`entries[]`:: - - An array of `struct dir_entry`, each element of which describes - a path. - -`nr`:: - - The number of members in `entries[]` array. - -`alloc`:: - - Internal use; keeps track of allocation of `entries[]` array. - -`ignored[]`:: - - An array of `struct dir_entry`, used for ignored paths with the - `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags. - -`ignored_nr`:: - - The number of members in `ignored[]` array. - -Calling sequence ----------------- - -Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE -marked. If you to exclude files, make sure you have loaded index first. - -* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, - sizeof(dir))`. - -* To add single exclude pattern, call `add_exclude_list()` and then - `add_exclude()`. - -* To add patterns from a file (e.g. `.git/info/exclude`), call - `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A - short-hand function `setup_standard_excludes()` can be used to set - up the standard set of exclude settings. - -* Set options described in the Data Structure section above. - -* Call `read_directory()`. - -* Use `dir.entries[]`. - -* Call `clear_directory()` when none of the contained elements are no longer in use. - -(JC) diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt deleted file mode 100644 index 45f0df600f..0000000000 --- a/Documentation/technical/api-gitattributes.txt +++ /dev/null @@ -1,154 +0,0 @@ -gitattributes API -================= - -gitattributes mechanism gives a uniform way to associate various -attributes to set of paths. - - -Data Structure --------------- - -`struct git_attr`:: - - An attribute is an opaque object that is identified by its name. - Pass the name to `git_attr()` function to obtain the object of - this type. The internal representation of this structure is - of no interest to the calling programs. The name of the - attribute can be retrieved by calling `git_attr_name()`. - -`struct attr_check_item`:: - - This structure represents one attribute and its value. - -`struct attr_check`:: - - This structure represents a collection of `attr_check_item`. - It is passed to `git_check_attr()` function, specifying the - attributes to check, and receives their values. - - -Attribute Values ----------------- - -An attribute for a path can be in one of four states: Set, Unset, -Unspecified or set to a string, and `.value` member of `struct -attr_check_item` records it. There are three macros to check these: - -`ATTR_TRUE()`:: - - Returns true if the attribute is Set for the path. - -`ATTR_FALSE()`:: - - Returns true if the attribute is Unset for the path. - -`ATTR_UNSET()`:: - - Returns true if the attribute is Unspecified for the path. - -If none of the above returns true, `.value` member points at a string -value of the attribute for the path. - - -Querying Specific Attributes ----------------------------- - -* Prepare `struct attr_check` using attr_check_initl() - function, enumerating the names of attributes whose values you are - interested in, terminated with a NULL pointer. Alternatively, an - empty `struct attr_check` can be prepared by calling - `attr_check_alloc()` function and then attributes you want to - ask about can be added to it with `attr_check_append()` - function. - -* Call `git_check_attr()` to check the attributes for the path. - -* Inspect `attr_check` structure to see how each of the - attribute in the array is defined for the path. - - -Example -------- - -To see how attributes "crlf" and "ident" are set for different paths. - -. Prepare a `struct attr_check` with two elements (because - we are checking two attributes): - ------------- -static struct attr_check *check; -static void setup_check(void) -{ - if (check) - return; /* already done */ - check = attr_check_initl("crlf", "ident", NULL); -} ------------- - -. Call `git_check_attr()` with the prepared `struct attr_check`: - ------------- - const char *path; - - setup_check(); - git_check_attr(path, check); ------------- - -. Act on `.value` member of the result, left in `check->items[]`: - ------------- - const char *value = check->items[0].value; - - if (ATTR_TRUE(value)) { - The attribute is Set, by listing only the name of the - attribute in the gitattributes file for the path. - } else if (ATTR_FALSE(value)) { - The attribute is Unset, by listing the name of the - attribute prefixed with a dash - for the path. - } else if (ATTR_UNSET(value)) { - The attribute is neither set nor unset for the path. - } else if (!strcmp(value, "input")) { - If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is - true, the value is a string set in the gitattributes - file for the path by saying "attr=value". - } else if (... other check using value as string ...) { - ... - } ------------- - -To see how attributes in argv[] are set for different paths, only -the first step in the above would be different. - ------------- -static struct attr_check *check; -static void setup_check(const char **argv) -{ - check = attr_check_alloc(); - while (*argv) { - struct git_attr *attr = git_attr(*argv); - attr_check_append(check, attr); - argv++; - } -} ------------- - - -Querying All Attributes ------------------------ - -To get the values of all attributes associated with a file: - -* Prepare an empty `attr_check` structure by calling - `attr_check_alloc()`. - -* Call `git_all_attrs()`, which populates the `attr_check` - with the attributes attached to the path. - -* Iterate over the `attr_check.items[]` array to examine - the attribute names and values. The name of the attribute - described by an `attr_check.items[]` object can be retrieved via - `git_attr_name(check->items[i].attr)`. (Please note that no items - will be returned for unset attributes, so `ATTR_UNSET()` will return - false for all returned `attr_check.items[]` objects.) - -* Free the `attr_check` struct by calling `attr_check_free()`. diff --git a/Documentation/technical/api-grep.txt b/Documentation/technical/api-grep.txt deleted file mode 100644 index a69cc8964d..0000000000 --- a/Documentation/technical/api-grep.txt +++ /dev/null @@ -1,8 +0,0 @@ -grep API -======== - -Talk about <grep.h>, things like: - -* grep_buffer() - -(JC) diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt deleted file mode 100644 index 18142b6d29..0000000000 --- a/Documentation/technical/api-history-graph.txt +++ /dev/null @@ -1,174 +0,0 @@ -history graph API -================= - -The graph API is used to draw a text-based representation of the commit -history. The API generates the graph in a line-by-line fashion. - -Functions ---------- - -Core functions: - -* `graph_init()` creates a new `struct git_graph` - -* `graph_update()` moves the graph to a new commit. - -* `graph_next_line()` outputs the next line of the graph into a strbuf. It - does not add a terminating newline. - -* `graph_padding_line()` outputs a line of vertical padding in the graph. It - is similar to `graph_next_line()`, but is guaranteed to never print the line - containing the current commit. Where `graph_next_line()` would print the - commit line next, `graph_padding_line()` prints a line that simply extends - all branch lines downwards one row, leaving their positions unchanged. - -* `graph_is_commit_finished()` determines if the graph has output all lines - necessary for the current commit. If `graph_update()` is called before all - lines for the current commit have been printed, the next call to - `graph_next_line()` will output an ellipsis, to indicate that a portion of - the graph was omitted. - -The following utility functions are wrappers around `graph_next_line()` and -`graph_is_commit_finished()`. They always print the output to stdout. -They can all be called with a NULL graph argument, in which case no graph -output will be printed. - -* `graph_show_commit()` calls `graph_next_line()` and - `graph_is_commit_finished()` until one of them return non-zero. This prints - all graph lines up to, and including, the line containing this commit. - Output is printed to stdout. The last line printed does not contain a - terminating newline. - -* `graph_show_oneline()` calls `graph_next_line()` and prints the result to - stdout. The line printed does not contain a terminating newline. - -* `graph_show_padding()` calls `graph_padding_line()` and prints the result to - stdout. The line printed does not contain a terminating newline. - -* `graph_show_remainder()` calls `graph_next_line()` until - `graph_is_commit_finished()` returns non-zero. Output is printed to stdout. - The last line printed does not contain a terminating newline. Returns 1 if - output was printed, and 0 if no output was necessary. - -* `graph_show_strbuf()` prints the specified strbuf to stdout, prefixing all - lines but the first with a graph line. The caller is responsible for - ensuring graph output for the first line has already been printed to stdout. - (This can be done with `graph_show_commit()` or `graph_show_oneline()`.) If - a NULL graph is supplied, the strbuf is printed as-is. - -* `graph_show_commit_msg()` is similar to `graph_show_strbuf()`, but it also - prints the remainder of the graph, if more lines are needed after the strbuf - ends. It is better than directly calling `graph_show_strbuf()` followed by - `graph_show_remainder()` since it properly handles buffers that do not end in - a terminating newline. The output printed by `graph_show_commit_msg()` will - end in a newline if and only if the strbuf ends in a newline. - -Data structure --------------- -`struct git_graph` is an opaque data type used to store the current graph -state. - -Calling sequence ----------------- - -* Create a `struct git_graph` by calling `graph_init()`. When using the - revision walking API, this is done automatically by `setup_revisions()` if - the '--graph' option is supplied. - -* Use the revision walking API to walk through a group of contiguous commits. - The `get_revision()` function automatically calls `graph_update()` each time - it is invoked. - -* For each commit, call `graph_next_line()` repeatedly, until - `graph_is_commit_finished()` returns non-zero. Each call go - `graph_next_line()` will output a single line of the graph. The resulting - lines will not contain any newlines. `graph_next_line()` returns 1 if the - resulting line contains the current commit, or 0 if this is merely a line - needed to adjust the graph before or after the current commit. This return - value can be used to determine where to print the commit summary information - alongside the graph output. - -Limitations ------------ - -* `graph_update()` must be called with commits in topological order. It should - not be called on a commit if it has already been invoked with an ancestor of - that commit, or the graph output will be incorrect. - -* `graph_update()` must be called on a contiguous group of commits. If - `graph_update()` is called on a particular commit, it should later be called - on all parents of that commit. Parents must not be skipped, or the graph - output will appear incorrect. -+ -`graph_update()` may be used on a pruned set of commits only if the parent list -has been rewritten so as to include only ancestors from the pruned set. - -* The graph API does not currently support reverse commit ordering. In - order to implement reverse ordering, the graphing API needs an - (efficient) mechanism to find the children of a commit. - -Sample usage ------------- - ------------- -struct commit *commit; -struct git_graph *graph = graph_init(opts); - -while ((commit = get_revision(opts)) != NULL) { - graph_update(graph, commit); - while (!graph_is_commit_finished(graph)) - { - struct strbuf sb; - int is_commit_line; - - strbuf_init(&sb, 0); - is_commit_line = graph_next_line(graph, &sb); - fputs(sb.buf, stdout); - - if (is_commit_line) - log_tree_commit(opts, commit); - else - putchar(opts->diffopt.line_termination); - } -} ------------- - -Sample output -------------- - -The following is an example of the output from the graph API. This output does -not include any commit summary information--callers are responsible for -outputting that information, if desired. - ------------- -* -* -* -|\ -* | -| | * -| \ \ -| \ \ -*-. \ \ -|\ \ \ \ -| | * | | -| | | | | * -| | | | | * -| | | | | * -| | | | | |\ -| | | | | | * -| * | | | | | -| | | | | * \ -| | | | | |\ | -| | | | * | | | -| | | | * | | | -* | | | | | | | -| |/ / / / / / -|/| / / / / / -* | | | | | | -|/ / / / / / -* | | | | | -| | | | | * -| | | | |/ -| | | | * ------------- diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 9dc1bed768..487d4d83ff 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -28,77 +28,9 @@ and `diff.c` for examples. * `struct ll_merge_options` -This describes the set of options the calling program wants to affect -the operation of a low-level (single file) merge. Some options: - -`virtual_ancestor`:: - Behave as though this were part of a merge between common - ancestors in a recursive merge. - If a helper program is specified by the - `[merge "<driver>"] recursive` configuration, it will - be used (see linkgit:gitattributes[5]). - -`variant`:: - Resolve local conflicts automatically in favor - of one side or the other (as in 'git merge-file' - `--ours`/`--theirs`/`--union`). Can be `0`, - `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or - `XDL_MERGE_FAVOR_UNION`. - -`renormalize`:: - Resmudge and clean the "base", "theirs" and "ours" files - before merging. Use this when the merge is likely to have - overlapped with a change in smudge/clean or end-of-line - normalization rules. +Check ll-merge.h for details. Low-level (single file) merge ----------------------------- -`ll_merge`:: - - Perform a three-way single-file merge in core. This is - a thin wrapper around `xdl_merge` that takes the path and - any merge backend specified in `.gitattributes` or - `.git/info/attributes` into account. Returns 0 for a - clean merge. - -Calling sequence: - -* Prepare a `struct ll_merge_options` to record options. - If you have no special requests, skip this and pass `NULL` - as the `opts` parameter to use the default options. - -* Allocate an mmbuffer_t variable for the result. - -* Allocate and fill variables with the file's original content - and two modified versions (using `read_mmfile`, for example). - -* Call `ll_merge()`. - -* Read the merged content from `result_buf.ptr` and `result_buf.size`. - -* Release buffers when finished. A simple - `free(ancestor.ptr); free(ours.ptr); free(theirs.ptr); - free(result_buf.ptr);` will do. - -If the modifications do not merge cleanly, `ll_merge` will return a -nonzero value and `result_buf` will generally include a description of -the conflict bracketed by markers such as the traditional `<<<<<<<` -and `>>>>>>>`. - -The `ancestor_label`, `our_label`, and `their_label` parameters are -used to label the different sides of a conflict if the merge driver -supports this. - -Everything else ---------------- - -Talk about <merge-recursive.h> and merge_file(): - - - merge_trees() to merge with rename detection - - merge_recursive() for ancestor consolidation - - try_merge_command() for other strategies - - conflict format - - merge options - -(Daniel, Miklos, Stephan, JC) +Check ll-merge.h for details. diff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt deleted file mode 100644 index 5b29622d00..0000000000 --- a/Documentation/technical/api-object-access.txt +++ /dev/null @@ -1,15 +0,0 @@ -object access API -================= - -Talk about <sha1-file.c> and <object.h> family, things like - -* read_sha1_file() -* read_object_with_reference() -* has_sha1_file() -* write_sha1_file() -* pretend_object_file() -* lookup_{object,commit,tag,blob,tree} -* parse_{object,commit,tag,blob,tree} -* Use of object flags - -(JC, Shawn, Daniel, Dscho, Linus) diff --git a/Documentation/technical/api-oid-array.txt b/Documentation/technical/api-oid-array.txt deleted file mode 100644 index 9febfb1d52..0000000000 --- a/Documentation/technical/api-oid-array.txt +++ /dev/null @@ -1,85 +0,0 @@ -oid-array API -============== - -The oid-array API provides storage and manipulation of sets of object -identifiers. The emphasis is on storage and processing efficiency, -making them suitable for large lists. Note that the ordering of items is -not preserved over some operations. - -Data Structures ---------------- - -`struct oid_array`:: - - A single array of object IDs. This should be initialized by - assignment from `OID_ARRAY_INIT`. The `oid` member contains - the actual data. The `nr` member contains the number of items in - the set. The `alloc` and `sorted` members are used internally, - and should not be needed by API callers. - -Functions ---------- - -`oid_array_append`:: - Add an item to the set. The object ID will be placed at the end of - the array (but note that some operations below may lose this - ordering). - -`oid_array_lookup`:: - Perform a binary search of the array for a specific object ID. - If found, returns the offset (in number of elements) of the - object ID. If not found, returns a negative integer. If the array - is not sorted, this function has the side effect of sorting it. - -`oid_array_clear`:: - Free all memory associated with the array and return it to the - initial, empty state. - -`oid_array_for_each`:: - Iterate over each element of the list, executing the callback - function for each one. Does not sort the list, so any custom - hash order is retained. If the callback returns a non-zero - value, the iteration ends immediately and the callback's - return is propagated; otherwise, 0 is returned. - -`oid_array_for_each_unique`:: - Iterate over each unique element of the list in sorted order, - but otherwise behave like `oid_array_for_each`. If the array - is not sorted, this function has the side effect of sorting - it. - -Examples --------- - ------------------------------------------ -int print_callback(const struct object_id *oid, - void *data) -{ - printf("%s\n", oid_to_hex(oid)); - return 0; /* always continue */ -} - -void some_func(void) -{ - struct sha1_array hashes = OID_ARRAY_INIT; - struct object_id oid; - - /* Read objects into our set */ - while (read_object_from_stdin(oid.hash)) - oid_array_append(&hashes, &oid); - - /* Check if some objects are in our set */ - while (read_object_from_stdin(oid.hash)) { - if (oid_array_lookup(&hashes, &oid) >= 0) - printf("it's in there!\n"); - - /* - * Print the unique set of objects. We could also have - * avoided adding duplicate objects in the first place, - * but we would end up re-sorting the array repeatedly. - * Instead, this will sort once and then skip duplicates - * in linear time. - */ - oid_array_for_each_unique(&hashes, print_callback, NULL); -} ------------------------------------------ diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 829b558110..2e2e7c10c6 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -183,10 +183,6 @@ There are some macros to easily define options: scale the provided value by 1024, 1024^2 or 1024^3 respectively. The scaled value is put into `unsigned_long_var`. -`OPT_DATE(short, long, ×tamp_t_var, description)`:: - Introduce an option with date argument, see `approxidate()`. - The timestamp is put into `timestamp_t_var`. - `OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`:: Introduce an option with expiry date argument, see `parse_expiry_date()`. The timestamp is put into `timestamp_t_var`. @@ -202,8 +198,10 @@ 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, description)`:: +`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 diff --git a/Documentation/technical/api-quote.txt b/Documentation/technical/api-quote.txt deleted file mode 100644 index e8a1bce94e..0000000000 --- a/Documentation/technical/api-quote.txt +++ /dev/null @@ -1,10 +0,0 @@ -quote API -========= - -Talk about <quote.h>, things like - -* sq_quote and unquote -* c_style quote and unquote -* quoting for foreign languages - -(JC) diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt deleted file mode 100644 index 46c3d5c355..0000000000 --- a/Documentation/technical/api-ref-iteration.txt +++ /dev/null @@ -1,78 +0,0 @@ -ref iteration API -================= - - -Iteration of refs is done by using an iterate function which will call a -callback function for every ref. The callback function has this -signature: - - int handle_one_ref(const char *refname, const struct object_id *oid, - int flags, void *cb_data); - -There are different kinds of iterate functions which all take a -callback of this type. The callback is then called for each found ref -until the callback returns nonzero. The returned value is then also -returned by the iterate function. - -Iteration functions -------------------- - -* `head_ref()` just iterates the head ref. - -* `for_each_ref()` iterates all refs. - -* `for_each_ref_in()` iterates all refs which have a defined prefix and - strips that prefix from the passed variable refname. - -* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`, - `for_each_replace_ref()` iterate refs from the respective area. - -* `for_each_glob_ref()` iterates all refs that match the specified glob - pattern. - -* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined. - -* Use `refs_` API for accessing submodules. The submodule ref store could - be obtained with `get_submodule_ref_store()`. - -* `for_each_rawref()` can be used to learn about broken ref and symref. - -* `for_each_reflog()` iterates each reflog file. - -Submodules ----------- - -If you want to iterate the refs of a submodule you first need to add the -submodules object database. You can do this by a code-snippet like -this: - - const char *path = "path/to/submodule" - if (add_submodule_odb(path)) - die("Error submodule '%s' not populated.", path); - -`add_submodule_odb()` will return zero on success. If you -do not do this you will get an error for each ref that it does not point -to a valid object. - -Note: As a side-effect of this you can not safely assume that all -objects you lookup are available in superproject. All submodule objects -will be available the same way as the superprojects objects. - -Example: --------- - ----- -static int handle_remote_ref(const char *refname, - const unsigned char *sha1, int flags, void *cb_data) -{ - struct strbuf *output = cb_data; - strbuf_addf(output, "%s\n", refname); - return 0; -} - -... - - struct strbuf output = STRBUF_INIT; - for_each_remote_ref(handle_remote_ref, &output); - printf("%s", output.buf); ----- diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt deleted file mode 100644 index f10941b2e8..0000000000 --- a/Documentation/technical/api-remote.txt +++ /dev/null @@ -1,127 +0,0 @@ -Remotes configuration API -========================= - -The API in remote.h gives access to the configuration related to -remotes. It handles all three configuration mechanisms historically -and currently used by Git, and presents the information in a uniform -fashion. Note that the code also handles plain URLs without any -configuration, giving them just the default information. - -struct remote -------------- - -`name`:: - - The user's nickname for the remote - -`url`:: - - An array of all of the url_nr URLs configured for the remote - -`pushurl`:: - - An array of all of the pushurl_nr push URLs configured for the remote - -`push`:: - - An array of refspecs configured for pushing, with - push_refspec being the literal strings, and push_refspec_nr - being the quantity. - -`fetch`:: - - An array of refspecs configured for fetching, with - fetch_refspec being the literal strings, and fetch_refspec_nr - being the quantity. - -`fetch_tags`:: - - The setting for whether to fetch tags (as a separate rule from - the configured refspecs); -1 means never to fetch tags, 0 - means to auto-follow tags based on the default heuristic, 1 - means to always auto-follow tags, and 2 means to fetch all - tags. - -`receivepack`, `uploadpack`:: - - The configured helper programs to run on the remote side, for - Git-native protocols. - -`http_proxy`:: - - The proxy to use for curl (http, https, ftp, etc.) URLs. - -`http_proxy_authmethod`:: - - The method used for authenticating against `http_proxy`. - -struct remotes can be found by name with remote_get(), and iterated -through with for_each_remote(). remote_get(NULL) will return the -default remote, given the current branch and configuration. - -struct refspec --------------- - -A struct refspec holds the parsed interpretation of a refspec. If it -will force updates (starts with a '+'), force is true. If it is a -pattern (sides end with '*') pattern is true. src and dest are the -two sides (including '*' characters if present); if there is only one -side, it is src, and dst is NULL; if sides exist but are empty (i.e., -the refspec either starts or ends with ':'), the corresponding side is -"". - -An array of strings can be parsed into an array of struct refspecs -using parse_fetch_refspec() or parse_push_refspec(). - -remote_find_tracking(), given a remote and a struct refspec with -either src or dst filled out, will fill out the other such that the -result is in the "fetch" specification for the remote (note that this -evaluates patterns and returns a single result). - -struct branch -------------- - -Note that this may end up moving to branch.h - -struct branch holds the configuration for a branch. It can be looked -up with branch_get(name) for "refs/heads/{name}", or with -branch_get(NULL) for HEAD. - -It contains: - -`name`:: - - The short name of the branch. - -`refname`:: - - The full path for the branch ref. - -`remote_name`:: - - The name of the remote listed in the configuration. - -`merge_name`:: - - An array of the "merge" lines in the configuration. - -`merge`:: - - An array of the struct refspecs used for the merge lines. That - is, merge[i]->dst is a local tracking ref which should be - merged into this branch by default. - -`merge_nr`:: - - The number of merge configurations - -branch_has_merge_config() returns true if the given branch has merge -configuration given. - -Other stuff ------------ - -There is other stuff in remote.h that is related, in general, to the -process of interacting with remotes. - -(Daniel Barkalow) diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt deleted file mode 100644 index 55b878ade8..0000000000 --- a/Documentation/technical/api-revision-walking.txt +++ /dev/null @@ -1,72 +0,0 @@ -revision walking API -==================== - -The revision walking API offers functions to build a list of revisions -and then iterate over that list. - -Calling sequence ----------------- - -The walking API has a given calling sequence: first you need to -initialize a rev_info structure, then add revisions to control what kind -of revision list do you want to get, finally you can iterate over the -revision list. - -Functions ---------- - -`init_revisions`:: - - Initialize a rev_info structure with default values. The second - parameter may be NULL or can be prefix path, and then the `.prefix` - variable will be set to it. This is typically the first function you - want to call when you want to deal with a revision list. After calling - this function, you are free to customize options, like set - `.ignore_merges` to 0 if you don't want to ignore merges, and so on. See - `revision.h` for a complete list of available options. - -`add_pending_object`:: - - This function can be used if you want to add commit objects as revision - information. You can use the `UNINTERESTING` object flag to indicate if - you want to include or exclude the given commit (and commits reachable - from the given commit) from the revision list. -+ -NOTE: If you have the commits as a string list then you probably want to -use setup_revisions(), instead of parsing each string and using this -function. - -`setup_revisions`:: - - Parse revision information, filling in the `rev_info` structure, and - removing the used arguments from the argument list. Returns the number - of arguments left that weren't recognized, which are also moved to the - head of the argument list. The last parameter is used in case no - parameter given by the first two arguments. - -`prepare_revision_walk`:: - - Prepares the rev_info structure for a walk. You should check if it - returns any error (non-zero return code) and if it does not, you can - start using get_revision() to do the iteration. - -`get_revision`:: - - Takes a pointer to a `rev_info` structure and iterates over it, - returning a `struct commit *` each time you call it. The end of the - revision list is indicated by returning a NULL pointer. - -`reset_revision_walk`:: - - Reset the flags used by the revision walking api. You can use - this to do multiple sequential revision walks. - -Data structures ---------------- - -Talk about <revision.h>, things like: - -* two diff_options, one for path limiting, another for output; -* remaining functions; - -(Linus, JC, Dscho) diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt deleted file mode 100644 index 8bf3e37f53..0000000000 --- a/Documentation/technical/api-run-command.txt +++ /dev/null @@ -1,264 +0,0 @@ -run-command API -=============== - -The run-command API offers a versatile tool to run sub-processes with -redirected input and output as well as with a modified environment -and an alternate current directory. - -A similar API offers the capability to run a function asynchronously, -which is primarily used to capture the output that the function -produces in the caller in order to process it. - - -Functions ---------- - -`child_process_init`:: - - Initialize a struct child_process variable. - -`start_command`:: - - Start a sub-process. Takes a pointer to a `struct child_process` - that specifies the details and returns pipe FDs (if requested). - See below for details. - -`finish_command`:: - - Wait for the completion of a sub-process that was started with - start_command(). - -`run_command`:: - - A convenience function that encapsulates a sequence of - start_command() followed by finish_command(). Takes a pointer - to a `struct child_process` that specifies the details. - -`run_command_v_opt`, `run_command_v_opt_cd_env`:: - - Convenience functions that encapsulate a sequence of - start_command() followed by finish_command(). The argument argv - specifies the program and its arguments. The argument opt is zero - or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, - `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE` - that correspond to the members .no_stdin, .git_cmd, - .stdout_to_stderr, .silent_exec_failure of `struct child_process`. - The argument dir corresponds the member .dir. The argument env - corresponds to the member .env. - -`child_process_clear`:: - - Release the memory associated with the struct child_process. - Most users of the run-command API don't need to call this - function explicitly because `start_command` invokes it on - failure and `finish_command` calls it automatically already. - -The functions above do the following: - -. If a system call failed, errno is set and -1 is returned. A diagnostic - is printed. - -. If the program was not found, then -1 is returned and errno is set to - ENOENT; a diagnostic is printed only if .silent_exec_failure is 0. - -. Otherwise, the program is run. If it terminates regularly, its exit - code is returned. No diagnostic is printed, even if the exit code is - non-zero. - -. If the program terminated due to a signal, then the return value is the - signal number + 128, ie. the same value that a POSIX shell's $? would - report. A diagnostic is printed. - - -`start_async`:: - - Run a function asynchronously. Takes a pointer to a `struct - async` that specifies the details and returns a set of pipe FDs - for communication with the function. See below for details. - -`finish_async`:: - - Wait for the completion of an asynchronous function that was - started with start_async(). - -`run_hook`:: - - Run a hook. - The first argument is a pathname to an index file, or NULL - if the hook uses the default index file or no index is needed. - The second argument is the name of the hook. - The further arguments correspond to the hook arguments. - The last argument has to be NULL to terminate the arguments list. - If the hook does not exist or is not executable, the return - value will be zero. - If it is executable, the hook will be executed and the exit - status of the hook is returned. - On execution, .stdout_to_stderr and .no_stdin will be set. - (See below.) - - -Data structures ---------------- - -* `struct child_process` - -This describes the arguments, redirections, and environment of a -command to run in a sub-process. - -The caller: - -1. allocates and clears (using child_process_init() or - CHILD_PROCESS_INIT) a struct child_process variable; -2. initializes the members; -3. calls start_command(); -4. processes the data; -5. closes file descriptors (if necessary; see below); -6. calls finish_command(). - -The .argv member is set up as an array of string pointers (NULL -terminated), of which .argv[0] is the program name to run (usually -without a path). If the command to run is a git command, set argv[0] to -the command name without the 'git-' prefix and set .git_cmd = 1. - -Note that the ownership of the memory pointed to by .argv stays with the -caller, but it should survive until `finish_command` completes. If the -.argv member is NULL, `start_command` will point it at the .args -`argv_array` (so you may use one or the other, but you must use exactly -one). The memory in .args will be cleaned up automatically during -`finish_command` (or during `start_command` when it is unsuccessful). - -The members .in, .out, .err are used to redirect stdin, stdout, -stderr as follows: - -. Specify 0 to request no special redirection. No new file descriptor - is allocated. The child process simply inherits the channel from the - parent. - -. Specify -1 to have a pipe allocated; start_command() replaces -1 - by the pipe FD in the following way: - - .in: Returns the writable pipe end into which the caller writes; - the readable end of the pipe becomes the child's stdin. - - .out, .err: Returns the readable pipe end from which the caller - reads; the writable end of the pipe end becomes child's - stdout/stderr. - - The caller of start_command() must close the so returned FDs - after it has completed reading from/writing to it! - -. Specify a file descriptor > 0 to be used by the child: - - .in: The FD must be readable; it becomes child's stdin. - .out: The FD must be writable; it becomes child's stdout. - .err: The FD must be writable; it becomes child's stderr. - - The specified FD is closed by start_command(), even if it fails to - run the sub-process! - -. Special forms of redirection are available by setting these members - to 1: - - .no_stdin, .no_stdout, .no_stderr: The respective channel is - redirected to /dev/null. - - .stdout_to_stderr: stdout of the child is redirected to its - stderr. This happens after stderr is itself redirected. - So stdout will follow stderr to wherever it is - redirected. - -To modify the environment of the sub-process, specify an array of -string pointers (NULL terminated) in .env: - -. If the string is of the form "VAR=value", i.e. it contains '=' - the variable is added to the child process's environment. - -. If the string does not contain '=', it names an environment - variable that will be removed from the child process's environment. - -If the .env member is NULL, `start_command` will point it at the -.env_array `argv_array` (so you may use one or the other, but not both). -The memory in .env_array will be cleaned up automatically during -`finish_command` (or during `start_command` when it is unsuccessful). - -To specify a new initial working directory for the sub-process, -specify it in the .dir member. - -If the program cannot be found, the functions return -1 and set -errno to ENOENT. Normally, an error message is printed, but if -.silent_exec_failure is set to 1, no message is printed for this -special error condition. - - -* `struct async` - -This describes a function to run asynchronously, whose purpose is -to produce output that the caller reads. - -The caller: - -1. allocates and clears (memset(&asy, 0, sizeof(asy));) a - struct async variable; -2. initializes .proc and .data; -3. calls start_async(); -4. processes communicates with proc through .in and .out; -5. closes .in and .out; -6. calls finish_async(). - -The members .in, .out are used to provide a set of fd's for -communication between the caller and the callee as follows: - -. Specify 0 to have no file descriptor passed. The callee will - receive -1 in the corresponding argument. - -. Specify < 0 to have a pipe allocated; start_async() replaces - with the pipe FD in the following way: - - .in: Returns the writable pipe end into which the caller - writes; the readable end of the pipe becomes the function's - in argument. - - .out: Returns the readable pipe end from which the caller - reads; the writable end of the pipe becomes the function's - out argument. - - The caller of start_async() must close the returned FDs after it - has completed reading from/writing from them. - -. Specify a file descriptor > 0 to be used by the function: - - .in: The FD must be readable; it becomes the function's in. - .out: The FD must be writable; it becomes the function's out. - - The specified FD is closed by start_async(), even if it fails to - run the function. - -The function pointer in .proc has the following signature: - - int proc(int in, int out, void *data); - -. in, out specifies a set of file descriptors to which the function - must read/write the data that it needs/produces. The function - *must* close these descriptors before it returns. A descriptor - may be -1 if the caller did not configure a descriptor for that - direction. - -. data is the value that the caller has specified in the .data member - of struct async. - -. The return value of the function is 0 on success and non-zero - on failure. If the function indicates failure, finish_async() will - report failure as well. - - -There are serious restrictions on what the asynchronous function can do -because this facility is implemented by a thread in the same address -space on most platforms (when pthreads is available), but by a pipe to -a forked process otherwise: - -. It cannot change the program's state (global variables, environment, - etc.) in a way that the caller notices; in other words, .in and .out - are the only communication channels to the caller. - -. It must not change the program's state that the caller of the - facility also uses. diff --git a/Documentation/technical/api-setup.txt b/Documentation/technical/api-setup.txt deleted file mode 100644 index eb1fa9853e..0000000000 --- a/Documentation/technical/api-setup.txt +++ /dev/null @@ -1,47 +0,0 @@ -setup API -========= - -Talk about - -* setup_git_directory() -* setup_git_directory_gently() -* is_inside_git_dir() -* is_inside_work_tree() -* setup_work_tree() - -(Dscho) - -Pathspec --------- - -See glossary-context.txt for the syntax of pathspec. In memory, a -pathspec set is represented by "struct pathspec" and is prepared by -parse_pathspec(). This function takes several arguments: - -- magic_mask specifies what features that are NOT supported by the - following code. If a user attempts to use such a feature, - parse_pathspec() can reject it early. - -- flags specifies other things that the caller wants parse_pathspec to - perform. - -- prefix and args come from cmd_* functions - -parse_pathspec() helps catch unsupported features and reject them -politely. At a lower level, different pathspec-related functions may -not support the same set of features. Such pathspec-sensitive -functions are guarded with GUARD_PATHSPEC(), which will die in an -unfriendly way when an unsupported feature is requested. - -The command designers are supposed to make sure that GUARD_PATHSPEC() -never dies. They have to make sure all unsupported features are caught -by parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC() -should give the designers all pathspec-sensitive codepaths and what -features they support. - -A similar process is applied when a new pathspec magic is added. The -designer lifts the GUARD_PATHSPEC restriction in the functions that -support the new magic. At the same time (s)he has to make sure this -new feature will be caught at parse_pathspec() in commands that cannot -handle the new magic in some cases. grepping parse_pathspec() should -help. diff --git a/Documentation/technical/api-sigchain.txt b/Documentation/technical/api-sigchain.txt deleted file mode 100644 index 9e1189ef01..0000000000 --- a/Documentation/technical/api-sigchain.txt +++ /dev/null @@ -1,41 +0,0 @@ -sigchain API -============ - -Code often wants to set a signal handler to clean up temporary files or -other work-in-progress when we die unexpectedly. For multiple pieces of -code to do this without conflicting, each piece of code must remember -the old value of the handler and restore it either when: - - 1. The work-in-progress is finished, and the handler is no longer - necessary. The handler should revert to the original behavior - (either another handler, SIG_DFL, or SIG_IGN). - - 2. The signal is received. We should then do our cleanup, then chain - to the next handler (or die if it is SIG_DFL). - -Sigchain is a tiny library for keeping a stack of handlers. Your handler -and installation code should look something like: - ------------------------------------------- - void clean_foo_on_signal(int sig) - { - clean_foo(); - sigchain_pop(sig); - raise(sig); - } - - void other_func() - { - sigchain_push_common(clean_foo_on_signal); - mess_up_foo(); - clean_foo(); - } ------------------------------------------- - -Handlers are given the typedef of sigchain_fun. This is the same type -that is given to signal() or sigaction(). It is perfectly reasonable to -push SIG_DFL or SIG_IGN onto the stack. - -You can sigchain_push and sigchain_pop individual signals. For -convenience, sigchain_push_common will push the handler onto the stack -for many common signals. diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt deleted file mode 100644 index fb06089393..0000000000 --- a/Documentation/technical/api-submodule-config.txt +++ /dev/null @@ -1,66 +0,0 @@ -submodule config cache API -========================== - -The submodule config cache API allows to read submodule -configurations/information from specified revisions. Internally -information is lazily read into a cache that is used to avoid -unnecessary parsing of the same .gitmodules files. Lookups can be done by -submodule path or name. - -Usage ------ - -To initialize the cache with configurations from the worktree the caller -typically first calls `gitmodules_config()` to read values from the -worktree .gitmodules and then to overlay the local git config values -`parse_submodule_config_option()` from the config parsing -infrastructure. - -The caller can look up information about submodules by using the -`submodule_from_path()` or `submodule_from_name()` functions. They return -a `struct submodule` which contains the values. The API automatically -initializes and allocates the needed infrastructure on-demand. If the -caller does only want to lookup values from revisions the initialization -can be skipped. - -If the internal cache might grow too big or when the caller is done with -the API, all internally cached values can be freed with submodule_free(). - -Data Structures ---------------- - -`struct submodule`:: - - This structure is used to return the information about one - submodule for a certain revision. It is returned by the lookup - functions. - -Functions ---------- - -`void submodule_free(struct repository *r)`:: - - Use these to free the internally cached values. - -`int parse_submodule_config_option(const char *var, const char *value)`:: - - Can be passed to the config parsing infrastructure to parse - local (worktree) submodule configurations. - -`const struct submodule *submodule_from_path(const unsigned char *treeish_name, const char *path)`:: - - Given a tree-ish in the superproject and a path, return the - submodule that is bound at the path in the named tree. - -`const struct submodule *submodule_from_name(const unsigned char *treeish_name, const char *name)`:: - - The same as above but lookup by name. - -Whenever a submodule configuration is parsed in `parse_submodule_config_option` -via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry. -So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed -with the repository configuration, the null_sha1 entry contains the local -configuration of a submodule (e.g. consolidated values from local git -configuration and the .gitmodules file in the worktree). - -For an example usage see test-submodule-config.c. diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt deleted file mode 100644 index fadb5979c4..0000000000 --- a/Documentation/technical/api-trace.txt +++ /dev/null @@ -1,140 +0,0 @@ -trace API -========= - -The trace API can be used to print debug messages to stderr or a file. Trace -code is inactive unless explicitly enabled by setting `GIT_TRACE*` environment -variables. - -The trace implementation automatically adds `timestamp file:line ... \n` to -all trace messages. E.g.: - ------------- -23:59:59.123456 git.c:312 trace: built-in: git 'foo' -00:00:00.000001 builtin/foo.c:99 foo: some message ------------- - -Data Structures ---------------- - -`struct trace_key`:: - - Defines a trace key (or category). The default (for API functions that - don't take a key) is `GIT_TRACE`. -+ -E.g. to define a trace key controlled by environment variable `GIT_TRACE_FOO`: -+ ------------- -static struct trace_key trace_foo = TRACE_KEY_INIT(FOO); - -static void trace_print_foo(const char *message) -{ - trace_printf_key(&trace_foo, "%s", message); -} ------------- -+ -Note: don't use `const` as the trace implementation stores internal state in -the `trace_key` structure. - -Functions ---------- - -`int trace_want(struct trace_key *key)`:: - - Checks whether the trace key is enabled. Used to prevent expensive - string formatting before calling one of the printing APIs. - -`void trace_disable(struct trace_key *key)`:: - - Disables tracing for the specified key, even if the environment - variable was set. - -`void trace_printf(const char *format, ...)`:: -`void trace_printf_key(struct trace_key *key, const char *format, ...)`:: - - Prints a formatted message, similar to printf. - -`void trace_argv_printf(const char **argv, const char *format, ...)``:: - - Prints a formatted message, followed by a quoted list of arguments. - -`void trace_strbuf(struct trace_key *key, const struct strbuf *data)`:: - - Prints the strbuf, without additional formatting (i.e. doesn't - choke on `%` or even `\0`). - -`uint64_t getnanotime(void)`:: - - Returns nanoseconds since the epoch (01/01/1970), typically used - for performance measurements. -+ -Currently there are high precision timer implementations for Linux (using -`clock_gettime(CLOCK_MONOTONIC)`) and Windows (`QueryPerformanceCounter`). -Other platforms use `gettimeofday` as time source. - -`void trace_performance(uint64_t nanos, const char *format, ...)`:: -`void trace_performance_since(uint64_t start, const char *format, ...)`:: - - Prints the elapsed time (in nanoseconds), or elapsed time since - `start`, followed by a formatted message. Enabled via environment - variable `GIT_TRACE_PERFORMANCE`. Used for manual profiling, e.g.: -+ ------------- -uint64_t start = getnanotime(); -/* code section to measure */ -trace_performance_since(start, "foobar"); ------------- -+ ------------- -uint64_t t = 0; -for (;;) { - /* ignore */ - t -= getnanotime(); - /* code section to measure */ - t += getnanotime(); - /* ignore */ -} -trace_performance(t, "frotz"); ------------- - -Bugs & Caveats --------------- - -GIT_TRACE_* environment variables can be used to tell Git to show -trace output to its standard error stream. Git can often spawn a pager -internally to run its subcommand and send its standard output and -standard error to it. - -Because GIT_TRACE_PERFORMANCE trace is generated only at the very end -of the program with atexit(), which happens after the pager exits, it -would not work well if you send its log to the standard error output -and let Git spawn the pager at the same time. - -As a work around, you can for example use '--no-pager', or set -GIT_TRACE_PERFORMANCE to another file descriptor which is redirected -to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its -absolute path. - -For example instead of the following command which by default may not -print any performance information: - ------------- -GIT_TRACE_PERFORMANCE=2 git log -1 ------------- - -you may want to use: - ------------- -GIT_TRACE_PERFORMANCE=2 git --no-pager log -1 ------------- - -or: - ------------- -GIT_TRACE_PERFORMANCE=3 3>&2 git log -1 ------------- - -or: - ------------- -GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1 ------------- diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt new file mode 100644 index 0000000000..6b6085585d --- /dev/null +++ b/Documentation/technical/api-trace2.txt @@ -0,0 +1,1171 @@ += Trace2 API + +The Trace2 API can be used to print debug, performance, and telemetry +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 +`GIT_TRACE_PERFORMANCE` facilities. During initial implementation, +Trace2 and Trace1 may operate in parallel. + +The Trace2 API defines a set of high-level messages with known fields, +such as (`start`: `argv`) and (`exit`: {`exit-code`, `elapsed-time`}). + +Trace2 instrumentation throughout the Git code base sends Trace2 +messages to the enabled Trace2 Targets. Targets transform these +messages content into purpose-specific formats and write events to +their data streams. In this manner, the Trace2 API can drive +many different types of analysis. + +Targets are defined using a VTable allowing easy extension to other +formats in the future. This might be used to define a binary format, +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. + +== Trace2 Targets + +Trace2 defines the following set of Trace2 Targets. +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` +environment variable or the `trace2.normalTarget` system or global +config setting. + +For example + +------------ +$ export GIT_TRACE2=~/log.normal +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +or + +------------ +$ git config --global trace2.normalTarget ~/log.normal +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +yields + +------------ +$ cat ~/log.normal +12:28:42.620009 common-main.c:38 version 2.20.1.155.g426c96fcdb +12:28:42.620989 common-main.c:39 start git version +12:28:42.621101 git.c:432 cmd_name version (version) +12:28:42.621215 git.c:662 exit elapsed:0.001227 code:0 +12:28:42.621250 trace2/tr2_tgt_normal.c:124 atexit elapsed:0.001265 code:0 +------------ + +=== 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 +enabled with the `GIT_TRACE2_PERF` environment variable or the +`trace2.perfTarget` system or global config setting. + +For example + +------------ +$ export GIT_TRACE2_PERF=~/log.perf +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +or + +------------ +$ git config --global trace2.perfTarget ~/log.perf +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +yields + +------------ +$ cat ~/log.perf +12:28:42.620675 common-main.c:38 | d0 | main | version | | | | | 2.20.1.155.g426c96fcdb +12:28:42.621001 common-main.c:39 | d0 | main | start | | 0.001173 | | | git version +12:28:42.621111 git.c:432 | d0 | main | cmd_name | | | | | version (version) +12:28:42.621225 git.c:662 | d0 | main | exit | | 0.001227 | | | code:0 +12:28:42.621259 trace2/tr2_tgt_perf.c:211 | d0 | main | atexit | | 0.001265 | | | code:0 +------------ + +=== The Event Format Target + +The event format target is a JSON-based format of event data suitable +for telemetry analysis. This format is enabled with the `GIT_TRACE2_EVENT` +environment variable or the `trace2.eventTarget` system or global config +setting. + +For example + +------------ +$ export GIT_TRACE2_EVENT=~/log.event +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +or + +------------ +$ git config --global trace2.eventTarget ~/log.event +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +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":"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} +{"event":"atexit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621268Z","file":"trace2/tr2_tgt_event.c","line":163,"t_abs":0.001265,"code":0} +------------ + +=== Enabling a Target + +To enable a target, set the corresponding environment variable or +system or global config value to one of the following: + +include::../trace2-target-values.txt[] + +When trace files are written to a target directory, they will be named according +to the last component of the SID (optionally followed by a counter to avoid +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_`. + +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`. + +== 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. + +Some functions have a `_fl()` suffix to indicate that they take `file` +and `line-number` arguments. + +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)`. + +=== 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. + +== Trace2 Target Formats + +=== NORMAL Format + +Events are written as lines of the form: + +------------ +[<time> SP <filename>:<line> SP+] <event-name> [[SP] <event-message>] LF +------------ + +`<event-name>`:: + + is the event name. + +`<event-message>`:: + 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. + +If `GIT_TRACE2_BRIEF` or `trace2.normalBrief` is true, the `time`, `filename`, +and `line` fields are omitted. + +This target is intended to be more of a summary (like GIT_TRACE) and +less detailed than the other targets. It ignores thread, region, and +data messages, for example. + +=== PERF Format + +Events are written as lines of the form: + +------------ +[<time> SP <filename>:<line> SP+ + BAR SP] d<depth> SP + BAR SP <thread-name> SP+ + BAR SP <event-name> SP+ + BAR SP [r<repo-id>] SP+ + BAR SP [<t_abs>] SP+ + BAR SP [<t_rel>] SP+ + BAR SP [<category>] SP+ + BAR SP DOTS* <perf-event-message> + LF +------------ + +`<depth>`:: + is the git process depth. This is the number of parent + git processes. A top-level git command has depth value "d0". + A child of it has depth value "d1". A second level child + has depth value "d2" and so on. + +`<thread-name>`:: + is a unique name for the thread. The primary thread + is called "main". Other thread names are of the form "th%d:%s" + and include a unique number and the name of the thread-proc. + +`<event-name>`:: + is the event name. + +`<repo-id>`:: + when present, is a number indicating the repository + in use. A `def_repo` event is emitted when a repository is + opened. This defines the repo-id and associated worktree. + Subsequent repo-specific events will reference this repo-id. ++ +Currently, this is always "r1" for the main repository. +This field is in anticipation of in-proc submodules in the future. + +`<t_abs>`:: + when present, is the absolute time in seconds since the + program started. + +`<t_rel>`:: + when present, is time in seconds relative to the start of + the current region. For a thread-exit event, it is the elapsed + time of the thread. + +`<category>`:: + is present on region and data events and is used to + indicate a broad category, such as "index" or "status". + +`<perf-event-message>`:: + 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 +15:33:33.532712 wt-status.c:2331 | d0 | main | region_leave | r1 | 0.127568 | 0.001504 | status | label:print +------------ + +If `GIT_TRACE2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`, +and `line` fields are omitted. + +------------ +d0 | main | region_leave | r1 | 0.011717 | 0.009122 | index | label:preload +------------ + +The PERF target is intended for interactive performance analysis +during development and is quite noisy. + +=== EVENT Format + +Each event is a JSON-object containing multiple key/value pairs +written as a single line and followed by a LF. + +------------ +'{' <key> ':' <value> [',' <key> ':' <value>]* '}' LF +------------ + +Some key/value pairs are common to all events and some are +event-specific. + +==== Common Key/Value Pairs + +The following key/value pairs are common to all events: + +------------ +{ + "event":"version", + "sid":"20190408T191827.272759Z-H9b68c35f-P00003510", + "thread":"main", + "time":"2019-04-08T19:18:27.282761Z", + "file":"common-main.c", + "line":42, + ... +} +------------ + +`"event":<event>`:: + is the event name. + +`"sid":<sid>`:: + is the session-id. This is a unique string to identify the + process instance to allow all events emitted by a process to + be identified. A session-id is used instead of a PID because + PIDs are recycled by the OS. For child git processes, the + session-id is prepended with the session-id of the parent git + process to allow parent-child relationships to be identified + during post-processing. + +`"thread":<thread>`:: + is the thread name. + +`"time":<time>`:: + is the UTC time of the event. + +`"file":<filename>`:: + is source file generating the event. + +`"line":<line-number>`:: + is the integer source line number generating the event. + +`"repo":<repo-id>`:: + when present, is the integer repo-id as described previously. + +If `GIT_TRACE2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file` +and `line` fields are omitted from all events and the `time` field is +only present on the "start" and "atexit" events. + +==== Event-Specific Key/Value Pairs + +`"version"`:: + This event gives the version of the executable and the EVENT format. It + should always be the first event in a trace session. The EVENT format + version will be incremented if new event types are added, if existing + fields are removed, or if there are significant changes in + interpretation of existing events or fields. Smaller changes, such as + adding a new field to an existing event, will not require an increment + to the EVENT format version. ++ +------------ +{ + "event":"version", + ... + "evt":"2", # EVENT format version + "exe":"2.20.1.155.g426c96fcdb" # git version +} +------------ + +`"discard"`:: + This event is written to the git-trace2-discard sentinel file if there + are too many files in the target trace directory (see the + trace2.maxFiles config option). ++ +------------ +{ + "event":"discard", + ... +} +------------ + +`"start"`:: + This event contains the complete argv received by main(). ++ +------------ +{ + "event":"start", + ... + "t_abs":0.001227, # elapsed time in seconds + "argv":["git","version"] +} +------------ + +`"exit"`:: + This event is emitted when git calls `exit()`. ++ +------------ +{ + "event":"exit", + ... + "t_abs":0.001227, # elapsed time in seconds + "code":0 # exit code +} +------------ + +`"atexit"`:: + This event is emitted by the Trace2 `atexit` routine during + final shutdown. It should be the last event emitted by the + process. ++ +(The elapsed time reported here is greater than the time reported in +the "exit" event because it runs after all other atexit tasks have +completed.) ++ +------------ +{ + "event":"atexit", + ... + "t_abs":0.001227, # elapsed time in seconds + "code":0 # exit code +} +------------ + +`"signal"`:: + This event is emitted when the program is terminated by a user + signal. Depending on the platform, the signal event may + prevent the "atexit" event from being generated. ++ +------------ +{ + "event":"signal", + ... + "t_abs":0.001227, # elapsed time in seconds + "signo":13 # SIGTERM, SIGINT, etc. +} +------------ + +`"error"`:: + This event is emitted when one of the `error()`, `die()`, + or `usage()` functions are called. ++ +------------ +{ + "event":"error", + ... + "msg":"invalid option: --cahced", # formatted error message + "fmt":"invalid option: %s" # error format string +} +------------ ++ +The error event may be emitted more than once. The format string +allows post-processors to group errors by type without worrying +about specific error arguments. + +`"cmd_path"`:: + This event contains the discovered full path of the git + executable (on platforms that are configured to resolve it). ++ +------------ +{ + "event":"cmd_path", + ... + "path":"C:/work/gfw/git.exe" +} +------------ + +`"cmd_name"`:: + This event contains the command name for this git process + and the hierarchy of commands from parent git processes. ++ +------------ +{ + "event":"cmd_name", + ... + "name":"pack-objects", + "hierarchy":"push/pack-objects" +} +------------ ++ +Normally, the "name" field contains the canonical name of the +command. When a canonical name is not available, one of +these special values are used: ++ +------------ +"_query_" # "git --html-path" +"_run_dashed_" # when "git foo" tries to run "git-foo" +"_run_shell_alias_" # alias expansion to a shell command +"_run_git_alias_" # alias expansion to a git command +"_usage_" # usage error +------------ + +`"cmd_mode"`:: + This event, when present, describes the command variant This + event may be emitted more than once. ++ +------------ +{ + "event":"cmd_mode", + ... + "name":"branch" +} +------------ ++ +The "name" field is an arbitrary string to describe the command mode. +For example, checkout can checkout a branch or an individual file. +And these variations typically have different performance +characteristics that are not comparable. + +`"alias"`:: + This event is present when an alias is expanded. ++ +------------ +{ + "event":"alias", + ... + "alias":"l", # registered alias + "argv":["log","--graph"] # alias expansion +} +------------ + +`"child_start"`:: + This event describes a child process that is about to be + spawned. ++ +------------ +{ + "event":"child_start", + ... + "child_id":2, + "child_class":"?", + "use_shell":false, + "argv":["git","rev-list","--objects","--stdin","--not","--all","--quiet"] + + "hook_name":"<hook_name>" # present when child_class is "hook" + "cd":"<path>" # present when cd is required +} +------------ ++ +The "child_id" field can be used to match this child_start with the +corresponding child_exit event. ++ +The "child_class" field is a rough classification, such as "editor", +"pager", "transport/*", and "hook". Unclassified children are classified +with "?". + +`"child_exit"`:: + This event is generated after the current process has returned + from the waitpid() and collected the exit information from the + child. ++ +------------ +{ + "event":"child_exit", + ... + "child_id":2, + "pid":14708, # child PID + "code":0, # child exit-code + "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.) ++ +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). +So this time will be slightly larger than the atexit time reported by +the child process itself. + +`"exec"`:: + This event is generated before git attempts to `exec()` + another command rather than starting a child process. ++ +------------ +{ + "event":"exec", + ... + "exec_id":0, + "exe":"git", + "argv":["foo", "bar"] +} +------------ ++ +The "exec_id" field is a command-unique id and is only useful if the +`exec()` fails and a corresponding exec_result event is generated. + +`"exec_result"`:: + This event is generated if the `exec()` fails and control + returns to the current git command. ++ +------------ +{ + "event":"exec_result", + ... + "exec_id":0, + "code":1 # error code (errno) from exec() +} +------------ + +`"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). ++ +------------ +{ + "event":"thread_start", + ... + "thread":"th02:preload_thread" # thread name +} +------------ + +`"thread_exit"`:: + This event is generated when a thread exits. It is generated + from *within* the thread's thread-proc (for TLS reasons). ++ +------------ +{ + "event":"thread_exit", + ... + "thread":"th02:preload_thread", # thread name + "t_rel":0.007328 # thread elapsed time +} +------------ + +`"def_param"`:: + This event is generated to log a global parameter, such as a config + setting, command-line flag, or environment variable. ++ +------------ +{ + "event":"def_param", + ... + "param":"core.abbrev", + "value":"7" +} +------------ + +`"def_repo"`:: + This event defines a repo-id and associates it with the root + of the worktree. ++ +------------ +{ + "event":"def_repo", + ... + "repo":1, + "worktree":"/Users/jeffhost/work/gfw" +} +------------ ++ +As stated earlier, the repo-id is currently always 1, so there will +only be one def_repo event. Later, if in-proc submodules are +supported, a def_repo event should be emitted for each submodule +visited. + +`"region_enter"`:: + This event is generated when entering a region. ++ +------------ +{ + "event":"region_enter", + ... + "repo":1, # optional + "nesting":1, # current region stack depth + "category":"index", # optional + "label":"do_read_index", # optional + "msg":".git/index" # optional +} +------------ ++ +The `category` field may be used in a future enhancement to +do category-based filtering. ++ +`GIT_TRACE2_EVENT_NESTING` or `trace2.eventNesting` can be used to +filter deeply nested regions and data events. It defaults to "2". + +`"region_leave"`:: + This event is generated when leaving a region. ++ +------------ +{ + "event":"region_leave", + ... + "repo":1, # optional + "t_rel":0.002876, # time spent in region in seconds + "nesting":1, # region stack depth + "category":"index", # optional + "label":"do_read_index", # optional + "msg":".git/index" # optional +} +------------ + +`"data"`:: + This event is generated to log a thread- and region-local + key/value pair. ++ +------------ +{ + "event":"data", + ... + "repo":1, # optional + "t_abs":0.024107, # absolute elapsed time + "t_rel":0.001031, # elapsed time in region/thread + "nesting":2, # region stack depth + "category":"index", + "key":"read/cache_nr", + "value":"3552" +} +------------ ++ +The "value" field may be an integer or a string. + +`"data-json"`:: + This event is generated to log a pre-formatted JSON string + containing structured data. ++ +------------ +{ + "event":"data_json", + ... + "repo":1, # optional + "t_abs":0.015905, + "t_rel":0.015905, + "nesting":1, + "category":"process", + "key":"windows/ancestry", + "value":["bash.exe","bash.exe"] +} +------------ + +== Example Trace2 API Usage + +Here is a hypothetical usage of the Trace2 API showing the intended +usage (without worrying about the actual Git details). + +Initialization:: + + Initialization happens in `main()`. Behind the scenes, an + `atexit` and `signal` handler are registered. ++ +---------------- +int main(int argc, const char **argv) +{ + int exit_code; + + trace2_initialize(); + trace2_cmd_start(argv); + + exit_code = cmd_main(argc, argv); + + trace2_cmd_exit(exit_code); + + return exit_code; +} +---------------- + +Command Details:: + + After the basics are established, additional command + information can be sent to Trace2 as it is discovered. ++ +---------------- +int cmd_checkout(int argc, const char **argv) +{ + trace2_cmd_name("checkout"); + trace2_cmd_mode("branch"); + trace2_def_repo(the_repository); + + // emit "def_param" messages for "interesting" config settings. + trace2_cmd_list_config(); + + if (do_something()) + trace2_cmd_error("Path '%s': cannot do something", path); + + return 0; +} +---------------- + +Child Processes:: + + Wrap code spawning child processes. ++ +---------------- +void run_child(...) +{ + int child_exit_code; + struct child_process cmd = CHILD_PROCESS_INIT; + ... + cmd.trace2_child_class = "editor"; + + trace2_child_start(&cmd); + child_exit_code = spawn_child_and_wait_for_it(); + trace2_child_exit(&cmd, child_exit_code); +} +---------------- ++ +For example, the following fetch command spawned ssh, index-pack, +rev-list, and gc. This example also shows that fetch took +5.199 seconds and of that 4.932 was in ssh. ++ +---------------- +$ export GIT_TRACE2_BRIEF=1 +$ export GIT_TRACE2=~/log.normal +$ git fetch origin +... +---------------- ++ +---------------- +$ cat ~/log.normal +version 2.20.1.vfs.1.1.47.g534dbe1ad1 +start git fetch origin +worktree /Users/jeffhost/work/gfw +cmd_name fetch (fetch) +child_start[0] ssh git@github.com ... +child_start[1] git index-pack ... +... (Trace2 events from child processes omitted) +child_exit[1] pid:14707 code:0 elapsed:0.076353 +child_exit[0] pid:14706 code:0 elapsed:4.931869 +child_start[2] git rev-list ... +... (Trace2 events from child process omitted) +child_exit[2] pid:14708 code:0 elapsed:0.110605 +child_start[3] git gc --auto +... (Trace2 events from child process omitted) +child_exit[3] pid:14709 code:0 elapsed:0.006240 +exit elapsed:5.198503 code:0 +atexit elapsed:5.198541 code:0 +---------------- ++ +When a git process is a (direct or indirect) child of another +git process, it inherits Trace2 context information. This +allows the child to print the command hierarchy. This example +shows gc as child[3] of fetch. When the gc process reports +its name as "gc", it also reports the hierarchy as "fetch/gc". +(In this example, trace2 messages from the child process is +indented for clarity.) ++ +---------------- +$ export GIT_TRACE2_BRIEF=1 +$ export GIT_TRACE2=~/log.normal +$ git fetch origin +... +---------------- ++ +---------------- +$ cat ~/log.normal +version 2.20.1.160.g5676107ecd.dirty +start git fetch official +worktree /Users/jeffhost/work/gfw +cmd_name fetch (fetch) +... +child_start[3] git gc --auto + version 2.20.1.160.g5676107ecd.dirty + start /Users/jeffhost/work/gfw/git gc --auto + worktree /Users/jeffhost/work/gfw + cmd_name gc (fetch/gc) + exit elapsed:0.001959 code:0 + atexit elapsed:0.001997 code:0 +child_exit[3] pid:20303 code:0 elapsed:0.007564 +exit elapsed:3.868938 code:0 +atexit elapsed:3.868970 code:0 +---------------- + +Regions:: + + Regions can be use to time an interesting section of code. ++ +---------------- +void wt_status_collect(struct wt_status *s) +{ + trace2_region_enter("status", "worktrees", s->repo); + wt_status_collect_changes_worktree(s); + trace2_region_leave("status", "worktrees", s->repo); + + trace2_region_enter("status", "index", s->repo); + wt_status_collect_changes_index(s); + trace2_region_leave("status", "index", s->repo); + + trace2_region_enter("status", "untracked", s->repo); + wt_status_collect_untracked(s); + trace2_region_leave("status", "untracked", s->repo); +} + +void wt_status_print(struct wt_status *s) +{ + trace2_region_enter("status", "print", s->repo); + switch (s->status_format) { + ... + } + trace2_region_leave("status", "print", s->repo); +} +---------------- ++ +In this example, scanning for untracked files ran from +0.012568 to ++0.027149 (since the process started) and took 0.014581 seconds. ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ git status +... + +$ cat ~/log.perf +d0 | main | version | | | | | 2.20.1.160.g5676107ecd.dirty +d0 | main | start | | 0.001173 | | | git status +d0 | main | def_repo | r1 | | | | worktree:/Users/jeffhost/work/gfw +d0 | main | cmd_name | | | | | status (status) +... +d0 | main | region_enter | r1 | 0.010988 | | status | label:worktrees +d0 | main | region_leave | r1 | 0.011236 | 0.000248 | status | label:worktrees +d0 | main | region_enter | r1 | 0.011260 | | status | label:index +d0 | main | region_leave | r1 | 0.012542 | 0.001282 | status | label:index +d0 | main | region_enter | r1 | 0.012568 | | status | label:untracked +d0 | main | region_leave | r1 | 0.027149 | 0.014581 | status | label:untracked +d0 | main | region_enter | r1 | 0.027411 | | status | label:print +d0 | main | region_leave | r1 | 0.028741 | 0.001330 | status | label:print +d0 | main | exit | | 0.028778 | | | code:0 +d0 | main | atexit | | 0.028809 | | | code:0 +---------------- ++ +Regions may be nested. This causes messages to be indented in the +PERF target, for example. +Elapsed times are relative to the start of the corresponding nesting +level as expected. For example, if we add region message to: ++ +---------------- +static enum path_treatment read_directory_recursive(struct dir_struct *dir, + struct index_state *istate, const char *base, int baselen, + struct untracked_cache_dir *untracked, int check_only, + int stop_at_first_file, const struct pathspec *pathspec) +{ + enum path_treatment state, subdir_state, dir_state = path_none; + + trace2_region_enter_printf("dir", "read_recursive", NULL, "%.*s", baselen, base); + ... + trace2_region_leave_printf("dir", "read_recursive", NULL, "%.*s", baselen, base); + return dir_state; +} +---------------- ++ +We can further investigate the time spent scanning for untracked files. ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ git status +... +$ cat ~/log.perf +d0 | main | version | | | | | 2.20.1.162.gb4ccea44db.dirty +d0 | main | start | | 0.001173 | | | git status +d0 | main | def_repo | r1 | | | | worktree:/Users/jeffhost/work/gfw +d0 | main | cmd_name | | | | | status (status) +... +d0 | main | region_enter | r1 | 0.015047 | | status | label:untracked +d0 | main | region_enter | | 0.015132 | | dir | ..label:read_recursive +d0 | main | region_enter | | 0.016341 | | dir | ....label:read_recursive vcs-svn/ +d0 | main | region_leave | | 0.016422 | 0.000081 | dir | ....label:read_recursive vcs-svn/ +d0 | main | region_enter | | 0.016446 | | dir | ....label:read_recursive xdiff/ +d0 | main | region_leave | | 0.016522 | 0.000076 | dir | ....label:read_recursive xdiff/ +d0 | main | region_enter | | 0.016612 | | dir | ....label:read_recursive git-gui/ +d0 | main | region_enter | | 0.016698 | | dir | ......label:read_recursive git-gui/po/ +d0 | main | region_enter | | 0.016810 | | dir | ........label:read_recursive git-gui/po/glossary/ +d0 | main | region_leave | | 0.016863 | 0.000053 | dir | ........label:read_recursive git-gui/po/glossary/ +... +d0 | main | region_enter | | 0.031876 | | dir | ....label:read_recursive builtin/ +d0 | main | region_leave | | 0.032270 | 0.000394 | dir | ....label:read_recursive builtin/ +d0 | main | region_leave | | 0.032414 | 0.017282 | dir | ..label:read_recursive +d0 | main | region_leave | r1 | 0.032454 | 0.017407 | status | label:untracked +... +d0 | main | exit | | 0.034279 | | | code:0 +d0 | main | atexit | | 0.034322 | | | code:0 +---------------- ++ +Trace2 regions are similar to the existing trace_performance_enter() +and trace_performance_leave() routines, but are thread safe and +maintain per-thread stacks of timers. + +Data Messages:: + + Data messages added to a region. ++ +---------------- +int read_index_from(struct index_state *istate, const char *path, + const char *gitdir) +{ + trace2_region_enter_printf("index", "do_read_index", the_repository, "%s", path); + + ... + + trace2_data_intmax("index", the_repository, "read/version", istate->version); + trace2_data_intmax("index", the_repository, "read/cache_nr", istate->cache_nr); + + trace2_region_leave_printf("index", "do_read_index", the_repository, "%s", path); +} +---------------- ++ +This example shows that the index contained 3552 entries. ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ git status +... +$ cat ~/log.perf +d0 | main | version | | | | | 2.20.1.156.gf9916ae094.dirty +d0 | main | start | | 0.001173 | | | git status +d0 | main | def_repo | r1 | | | | worktree:/Users/jeffhost/work/gfw +d0 | main | cmd_name | | | | | status (status) +d0 | main | region_enter | r1 | 0.001791 | | index | label:do_read_index .git/index +d0 | main | data | r1 | 0.002494 | 0.000703 | index | ..read/version:2 +d0 | main | data | r1 | 0.002520 | 0.000729 | index | ..read/cache_nr:3552 +d0 | main | region_leave | r1 | 0.002539 | 0.000748 | index | label:do_read_index .git/index +... +---------------- + +Thread Events:: + + Thread messages added to a thread-proc. ++ +For example, the multithreaded preload-index code can be +instrumented with a region around the thread pool and then +per-thread start and exit events within the threadproc. ++ +---------------- +static void *preload_thread(void *_data) +{ + // start the per-thread clock and emit a message. + trace2_thread_start("preload_thread"); + + // report which chunk of the array this thread was assigned. + trace2_data_intmax("index", the_repository, "offset", p->offset); + trace2_data_intmax("index", the_repository, "count", nr); + + do { + ... + } while (--nr > 0); + ... + + // report elapsed time taken by this thread. + trace2_thread_exit(); + return NULL; +} + +void preload_index(struct index_state *index, + const struct pathspec *pathspec, + unsigned int refresh_flags) +{ + trace2_region_enter("index", "preload", the_repository); + + for (i = 0; i < threads; i++) { + ... /* create thread */ + } + + for (i = 0; i < threads; i++) { + ... /* join thread */ + } + + trace2_region_leave("index", "preload", the_repository); +} +---------------- ++ +In this example preload_index() was executed by the `main` thread +and started the `preload` region. Seven threads, named +`th01:preload_thread` through `th07:preload_thread`, were started. +Events from each thread are atomically appended to the shared target +stream as they occur so they may appear in random order with respect +other threads. Finally, the main thread waits for the threads to +finish and leaves the region. ++ +Data events are tagged with the active thread name. They are used +to report the per-thread parameters. ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ git status +... +$ cat ~/log.perf +... +d0 | main | region_enter | r1 | 0.002595 | | index | label:preload +d0 | th01:preload_thread | thread_start | | 0.002699 | | | +d0 | th02:preload_thread | thread_start | | 0.002721 | | | +d0 | th01:preload_thread | data | r1 | 0.002736 | 0.000037 | index | offset:0 +d0 | th02:preload_thread | data | r1 | 0.002751 | 0.000030 | index | offset:2032 +d0 | th03:preload_thread | thread_start | | 0.002711 | | | +d0 | th06:preload_thread | thread_start | | 0.002739 | | | +d0 | th01:preload_thread | data | r1 | 0.002766 | 0.000067 | index | count:508 +d0 | th06:preload_thread | data | r1 | 0.002856 | 0.000117 | index | offset:2540 +d0 | th03:preload_thread | data | r1 | 0.002824 | 0.000113 | index | offset:1016 +d0 | th04:preload_thread | thread_start | | 0.002710 | | | +d0 | th02:preload_thread | data | r1 | 0.002779 | 0.000058 | index | count:508 +d0 | th06:preload_thread | data | r1 | 0.002966 | 0.000227 | index | count:508 +d0 | th07:preload_thread | thread_start | | 0.002741 | | | +d0 | th07:preload_thread | data | r1 | 0.003017 | 0.000276 | index | offset:3048 +d0 | th05:preload_thread | thread_start | | 0.002712 | | | +d0 | th05:preload_thread | data | r1 | 0.003067 | 0.000355 | index | offset:1524 +d0 | th05:preload_thread | data | r1 | 0.003090 | 0.000378 | index | count:508 +d0 | th07:preload_thread | data | r1 | 0.003037 | 0.000296 | index | count:504 +d0 | th03:preload_thread | data | r1 | 0.002971 | 0.000260 | index | count:508 +d0 | th04:preload_thread | data | r1 | 0.002983 | 0.000273 | index | offset:508 +d0 | th04:preload_thread | data | r1 | 0.007311 | 0.004601 | index | count:508 +d0 | th05:preload_thread | thread_exit | | 0.008781 | 0.006069 | | +d0 | th01:preload_thread | thread_exit | | 0.009561 | 0.006862 | | +d0 | th03:preload_thread | thread_exit | | 0.009742 | 0.007031 | | +d0 | th06:preload_thread | thread_exit | | 0.009820 | 0.007081 | | +d0 | th02:preload_thread | thread_exit | | 0.010274 | 0.007553 | | +d0 | th07:preload_thread | thread_exit | | 0.010477 | 0.007736 | | +d0 | th04:preload_thread | thread_exit | | 0.011657 | 0.008947 | | +d0 | main | region_leave | r1 | 0.011717 | 0.009122 | index | label:preload +... +d0 | main | exit | | 0.029996 | | | code:0 +d0 | main | atexit | | 0.030027 | | | code:0 +---------------- ++ +In this example, the preload region took 0.009122 seconds. The 7 threads +took between 0.006069 and 0.008947 seconds to work on their portion of +the index. Thread "th01" worked on 508 items at offset 0. Thread "th02" +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. + +== Future Work + +=== Relationship to the Existing Trace Api (api-trace.txt) + +There are a few issues to resolve before we can completely +switch to Trace2. + +* Updating existing tests that assume GIT_TRACE format messages. + +* How to best handle custom GIT_TRACE_<key> messages? + +** 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 +Trace2 targets (and convert <key> to a "category"). diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt deleted file mode 100644 index bde18622a8..0000000000 --- a/Documentation/technical/api-tree-walking.txt +++ /dev/null @@ -1,147 +0,0 @@ -tree walking API -================ - -The tree walking API is used to traverse and inspect trees. - -Data Structures ---------------- - -`struct name_entry`:: - - An entry in a tree. Each entry has a sha1 identifier, pathname, and - mode. - -`struct tree_desc`:: - - A semi-opaque data structure used to maintain the current state of the - walk. -+ -* `buffer` is a pointer into the memory representation of the tree. It always -points at the current entry being visited. - -* `size` counts the number of bytes left in the `buffer`. - -* `entry` points to the current entry being visited. - -`struct traverse_info`:: - - A structure used to maintain the state of a traversal. -+ -* `prev` points to the traverse_info which was used to descend into the -current tree. If this is the top-level tree `prev` will point to -a dummy traverse_info. - -* `name` is the entry for the current tree (if the tree is a subtree). - -* `pathlen` is the length of the full path for the current tree. - -* `conflicts` can be used by callbacks to maintain directory-file conflicts. - -* `fn` is a callback called for each entry in the tree. See Traversing for more -information. - -* `data` can be anything the `fn` callback would want to use. - -* `show_all_errors` tells whether to stop at the first error or not. - -Initializing ------------- - -`init_tree_desc`:: - - Initialize a `tree_desc` and decode its first entry. The buffer and - size parameters are assumed to be the same as the buffer and size - members of `struct tree`. - -`fill_tree_descriptor`:: - - Initialize a `tree_desc` and decode its first entry given the - object ID of a tree. Returns the `buffer` member if the latter - is a valid tree identifier and NULL otherwise. - -`setup_traverse_info`:: - - Initialize a `traverse_info` given the pathname of the tree to start - traversing from. The `base` argument is assumed to be the `path` - member of the `name_entry` being recursed into unless the tree is a - top-level tree in which case the empty string ("") is used. - -Walking -------- - -`tree_entry`:: - - Visit the next entry in a tree. Returns 1 when there are more entries - left to visit and 0 when all entries have been visited. This is - commonly used in the test of a while loop. - -`tree_entry_len`:: - - Calculate the length of a tree entry's pathname. This utilizes the - memory structure of a tree entry to avoid the overhead of using a - generic strlen(). - -`update_tree_entry`:: - - Walk to the next entry in a tree. This is commonly used in conjunction - with `tree_entry_extract` to inspect the current entry. - -`tree_entry_extract`:: - - Decode the entry currently being visited (the one pointed to by - `tree_desc's` `entry` member) and return the sha1 of the entry. The - `pathp` and `modep` arguments are set to the entry's pathname and mode - respectively. - -`get_tree_entry`:: - - Find an entry in a tree given a pathname and the sha1 of a tree to - search. Returns 0 if the entry is found and -1 otherwise. The third - and fourth parameters are set to the entry's sha1 and mode - respectively. - -Traversing ----------- - -`traverse_trees`:: - - Traverse `n` number of trees in parallel. The `fn` callback member of - `traverse_info` is called once for each tree entry. - -`traverse_callback_t`:: - The arguments passed to the traverse callback are as follows: -+ -* `n` counts the number of trees being traversed. - -* `mask` has its nth bit set if something exists in the nth entry. - -* `dirmask` has its nth bit set if the nth tree's entry is a directory. - -* `entry` is an array of size `n` where the nth entry is from the nth tree. - -* `info` maintains the state of the traversal. - -+ -Returning a negative value will terminate the traversal. Otherwise the -return value is treated as an update mask. If the nth bit is set the nth tree -will be updated and if the bit is not set the nth tree entry will be the -same in the next callback invocation. - -`make_traverse_path`:: - - Generate the full pathname of a tree entry based from the root of the - traversal. For example, if the traversal has recursed into another - tree named "bar" the pathname of an entry "baz" in the "bar" - tree would be "bar/baz". - -`traverse_path_len`:: - - Calculate the length of a pathname returned by `make_traverse_path`. - This utilizes the memory structure of a tree entry to avoid the - overhead of using a generic strlen(). - -Authors -------- - -Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds -<torvalds@linux-foundation.org> diff --git a/Documentation/technical/api-xdiff-interface.txt b/Documentation/technical/api-xdiff-interface.txt deleted file mode 100644 index 6296ecad1d..0000000000 --- a/Documentation/technical/api-xdiff-interface.txt +++ /dev/null @@ -1,7 +0,0 @@ -xdiff interface API -=================== - -Talk about our calling convention to xdiff library, including -xdiff_emit_consume_fn. - -(Dscho, JC) diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt new file mode 100644 index 0000000000..0e828151a5 --- /dev/null +++ b/Documentation/technical/bundle-format.txt @@ -0,0 +1,48 @@ += Git bundle v2 format + +The Git bundle format is a format that represents both refs and Git objects. + +== Format + +We will use ABNF notation to define the Git bundle format. See +protocol-common.txt for the details. + +---- +bundle = signature *prerequisite *reference LF pack +signature = "# v2 git bundle" LF + +prerequisite = "-" obj-id SP comment LF +comment = *CHAR +reference = obj-id SP refname LF + +pack = ... ; packfile +---- + +== Semantics + +A Git bundle consists of three parts. + +* "Prerequisites" lists 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 + a blob that is reachable from a prerequisite) and/or expressed as a delta + against prerequisite objects. + +* "References" record the tips of the history graph, iow, what the reader of the + bundle CAN "git fetch" from it. + +* "Pack" is the pack data stream "git fetch" would send, if you fetch from a + repository that has the references recorded in the "References" above into a + repository that has references pointing at the objects listed in + "Prerequisites" above. + +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 that the prerequisites does 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. diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index cc0474ba3e..1beef17182 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -17,6 +17,9 @@ metadata, including: - The parents of the commit, stored using positional references within the graph file. +- The Bloom filter of the commit carrying the paths that were changed between + the commit and its first parent, if requested. + These positional references are stored as unsigned 32-bit integers 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 @@ -44,8 +47,9 @@ HEADER: 1-byte number (C) of "chunks" - 1-byte (reserved for later use) - Current clients should ignore this value. + 1-byte number (B) of base commit-graphs + We infer the length (H*B) of the Base Graphs chunk + from this value. CHUNK LOOKUP: @@ -76,7 +80,7 @@ CHUNK DATA: of the ith commit. Stores value 0x7000000 if no parent in that position. If there are more than two parents, the second value has its most-significant bit on and the other bits store an array - position into the Large Edge List chunk. + position into the Extra Edge List chunk. * The next 8 bytes store the generation number of the commit and the commit time in seconds since EPOCH. The generation number uses the higher 30 bits of the first 4 bytes, while the commit @@ -84,7 +88,7 @@ CHUNK DATA: 2 bits of the lowest byte, storing the 33rd and 34th bit of the commit time. - Large 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 @@ -92,6 +96,39 @@ 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] + * 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] + * 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 + implemented exactly as described in + https://en.wikipedia.org/wiki/MurmurHash#Algorithm and the double + hashing technique using seed values 0x293ae76f and 0x7e646e2 as + described in https://doi.org/10.1007/978-3-540-30494-4_26 "Bloom Filters + in Probabilistic Verification" + - The number of times a path is hashed and hence the number of bit positions + that cumulatively determine whether a file is present in the commit. + - The minimum number of bits 'b' per entry in the Bloom filter. If the filter + contains 'n' entries, then the filter size is the minimum number of 64-bit + words that contain n*b bits. + * The rest of the chunk is the concatenation of all the computed Bloom + filters for the commits in lexicographic order. + * Note: Commits with no changes or more than 512 changes have Bloom filters + of length zero. + * The BDAT chunk is present if and only if BIDX is present. + + 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: H-byte HASH-checksum of all of the above. diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index c664acbd76..808fa30b99 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -15,18 +15,18 @@ There are two main costs here: 1. Decompressing and parsing commits. 2. Walking the entire graph to satisfy topological order constraints. -The commit graph file is a supplemental data structure that accelerates +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 as "commit-graph" either in the .git/objects/info directory or in the info directory of an alternate. -The commit graph file stores the commit graph structure along with some -extra metadata to speed up graph walks. By listing commit OIDs in lexi- -cographic order, we can identify an integer position for each commit and -refer to the parents of a commit using those integer positions. We use -binary search to find initial commits and then use the integer positions -for fast lookups during the walk. +The commit-graph file stores the commit graph structure along with some +extra metadata to speed up graph walks. By listing commit OIDs in +lexicographic order, we can identify an integer position for each commit +and refer to the parents of a commit using those integer positions. We +use binary search to find initial commits and then use the integer +positions for fast lookups during the walk. A consumer may load the following info for a commit from the graph: @@ -85,7 +85,7 @@ have generation number represented by the macro GENERATION_NUMBER_ZERO = 0. Since the commit-graph file is closed under reachability, we can guarantee the following weaker condition on all commits: - If A and B are commits with generation numbers N amd M, respectively, + If A and B are commits with generation numbers N and M, respectively, and N < M, then A cannot reach B. Note how the strict inequality differs from the inequality when we have @@ -103,7 +103,7 @@ that of a parent. Design Details -------------- -- The commit graph file is stored in a file named 'commit-graph' in the +- The commit-graph file is stored in a file named 'commit-graph' in the .git/objects/info directory. This could be stored in the info directory of an alternate. @@ -112,39 +112,225 @@ Design Details - The file format includes parameters for the object ID hash function, so a future change of hash algorithm does not require a change in format. -Future Work ------------ - -- The commit graph feature currently does not honor commit grafts. This can - be remedied by duplicating or refactoring the current graft logic. - -- After computing and storing generation numbers, we must make graph - walks aware of generation numbers to gain the performance benefits they - enable. This will mostly be accomplished by swapping a commit-date-ordered - priority queue with one ordered by generation number. The following - operations are important candidates: - - - 'log --topo-order' - - 'tag --merged' - -- A server could provide a commit graph file as part of the network protocol - to avoid extra calculations by clients. This feature is only of benefit if - the user is willing to trust the file, because verifying the file is correct - is as hard as computing it from scratch. +- 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 + 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. + +- Shallow clones create grafts of commits by dropping their parents. This + leads the commit-graph to think those commits have generation number 1. + If and when those commits are made unshallow, those generation numbers + become invalid. Since shallow clones are intended to restrict the commit + history to a very small set of commits, the commit-graph feature is less + helpful for these clones, anyway. The commit-graph will not be read or + written when shallow commits are present. + +Commit Graphs Chains +-------------------- + +Typically, repos grow with near-constant velocity (commits per day). Over time, +the number of commits added by a fetch operation is much smaller than the +number of commits in the full history. By creating a "chain" of commit-graphs, +we enable fast writes of new commit data without rewriting the entire commit +history -- at least, most of the time. + +## File Layout + +A commit-graph chain uses multiple files, and we use a fixed naming convention +to organize these files. Each commit-graph file has a name +`$OBJDIR/info/commit-graphs/graph-{hash}.graph` where `{hash}` is the hex- +valued hash stored in the footer of that file (which is a hash of the file's +contents before that hash). For a chain of commit-graph files, a plain-text +file at `$OBJDIR/info/commit-graphs/commit-graph-chain` contains the +hashes for the files in order from "lowest" to "highest". + +For example, if the `commit-graph-chain` file contains the lines + +``` + {hash0} + {hash1} + {hash2} +``` + +then the commit-graph chain looks like the following diagram: + + +-----------------------+ + | graph-{hash2}.graph | + +-----------------------+ + | + +-----------------------+ + | | + | graph-{hash1}.graph | + | | + +-----------------------+ + | + +-----------------------+ + | | + | | + | | + | graph-{hash0}.graph | + | | + | | + | | + +-----------------------+ + +Let X0 be the number of commits in `graph-{hash0}.graph`, X1 be the number of +commits in `graph-{hash1}.graph`, and X2 be the number of commits in +`graph-{hash2}.graph`. If a commit appears in position i in `graph-{hash2}.graph`, +then we interpret this as being the commit in position (X0 + X1 + i), and that +will be used as its "graph position". The commits in `graph-{hash2}.graph` use these +positions to refer to their parents, which may be in `graph-{hash1}.graph` or +`graph-{hash0}.graph`. We can navigate to an arbitrary commit in position j by checking +its containment in the intervals [0, X0), [X0, X0 + X1), [X0 + X1, X0 + X1 + +X2). + +Each commit-graph file (except the base, `graph-{hash0}.graph`) contains data +specifying the hashes of all files in the lower layers. In the above example, +`graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains +`{hash0}` and `{hash1}`. + +## Merging commit-graph files + +If we only added a new commit-graph file on every write, we would run into a +linear search problem through many commit-graph files. Instead, we use a merge +strategy to decide when the stack should collapse some number of levels. + +The diagram below shows such a collapse. As a set of new commits are added, it +is determined by the merge strategy that the files should collapse to +`graph-{hash1}`. Thus, the new commits, the commits in `graph-{hash2}` and +the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}` +file. + + +---------------------+ + | | + | (new commits) | + | | + +---------------------+ + | | + +-----------------------+ +---------------------+ + | graph-{hash2} |->| | + +-----------------------+ +---------------------+ + | | | + +-----------------------+ +---------------------+ + | | | | + | graph-{hash1} |->| | + | | | | + +-----------------------+ +---------------------+ + | tmp_graphXXX + +-----------------------+ + | | + | | + | | + | graph-{hash0} | + | | + | | + | | + +-----------------------+ + +During this process, the commits to write are combined, sorted and we write the +contents to a temporary file, all while holding a `commit-graph-chain.lock` +lock-file. When the file is flushed, we rename it to `graph-{hash3}` +according to the computed `{hash3}`. Finally, we write the new chain data to +`commit-graph-chain.lock`: + +``` + {hash3} + {hash0} +``` + +We then close the lock-file. + +## Merge Strategy + +When writing a set of commits that do not exist in the commit-graph stack of +height N, we default to creating a new file at level N + 1. We then decide to +merge with the Nth level if one of two conditions hold: + + 1. `--size-multiple=<X>` is specified or X = 2, and the number of commits in + level N is less than X times the number of commits in level N + 1. + + 2. `--max-commits=<C>` is specified with non-zero C and the number of commits + in level N + 1 is more than C commits. + +This decision cascades down the levels: when we merge a level we create a new +set of commits that then compares to the next level. + +The first condition bounds the number of levels to be logarithmic in the total +number of commits. The second condition bounds the total number of commits in +a `graph-{hashN}` file and not in the `commit-graph` file, preventing +significant performance issues when the stack merges and another process only +partially reads the previous stack. + +The merge strategy values (2 for the size multiple, 64,000 for the maximum +number of commits) could be extracted into config settings for full +flexibility. + +## Deleting graph-{hash} files + +After a new tip file is written, some `graph-{hash}` files may no longer +be part of a chain. It is important to remove these files from disk, eventually. +The main reason to delay removal is that another process could read the +`commit-graph-chain` file before it is rewritten, but then look for the +`graph-{hash}` files after they are deleted. + +To allow holding old split commit-graphs for a while after they are unreferenced, +we update the modified times of the files when they become unreferenced. Then, +we scan the `$OBJDIR/info/commit-graphs/` directory for `graph-{hash}` +files whose modified times are older than a given expiry window. This window +defaults to zero, but can be changed using command-line arguments or a config +setting. + +## Chains across multiple object directories + +In a repo with alternates, we look for the `commit-graph-chain` file starting +in the local object directory and then in each alternate. The first file that +exists defines our chain. As we look for the `graph-{hash}` files for +each `{hash}` in the chain file, we follow the same pattern for the host +directories. + +This allows commit-graphs to be split across multiple forks in a fork network. +The typical case is a large "base" repo with many smaller forks. + +As the base repo advances, it will likely update and merge its commit-graph +chain more frequently than the forks. If a fork updates their commit-graph after +the base repo, then it should "reparent" the commit-graph chain onto the new +chain in the base repo. When reading each `graph-{hash}` file, we track +the object directory containing it. During a write of a new commit-graph file, +we check for any changes in the source object directory and read the +`commit-graph-chain` file for that source and create a new file based on those +files. During this "reparent" operation, we necessarily need to collapse all +levels in the fork, as all of the files are invalid against the new base file. + +It is crucial to be careful when cleaning up "unreferenced" `graph-{hash}.graph` +files in this scenario. It falls to the user to define the proper settings for +their custom environment: + + 1. When merging levels in the base repo, the unreferenced files may still be + referenced by chains from fork repos. + + 2. The expiry time should be set to a length of time such that every fork has + time to recompute their commit-graph chain to "reparent" onto the new base + file(s). + + 3. If the commit-graph chain is updated in the base, the fork will not have + access to the new chain until its chain is updated to reference those files. + (This may change in the future [5].) Related Links ------------- [0] https://bugs.chromium.org/p/git/issues/detail?id=8 Chromium work item for: Serialized Commit Graph -[1] https://public-inbox.org/git/20110713070517.GC18566@sigill.intra.peff.net/ +[1] https://lore.kernel.org/git/20110713070517.GC18566@sigill.intra.peff.net/ An abandoned patch that introduced generation numbers. -[2] https://public-inbox.org/git/20170908033403.q7e6dj7benasrjes@sigill.intra.peff.net/ +[2] https://lore.kernel.org/git/20170908033403.q7e6dj7benasrjes@sigill.intra.peff.net/ Discussion about generation numbers on commits and how they interact with fsck. -[3] https://public-inbox.org/git/20170908034739.4op3w4f2ma5s65ku@sigill.intra.peff.net/ +[3] https://lore.kernel.org/git/20170908034739.4op3w4f2ma5s65ku@sigill.intra.peff.net/ More discussion about generation numbers and not storing them inside commit objects. A valuable quote: @@ -156,5 +342,9 @@ Related Links commit objects (i.e., packv4 or something like the "metapacks" I proposed a few years ago)." -[4] https://public-inbox.org/git/20180108154822.54829-1-git@jeffhostetler.com/T/#u +[4] https://lore.kernel.org/git/20180108154822.54829-1-git@jeffhostetler.com/T/#u A patch to remove the ahead-behind calculation from 'status'. + +[5] https://lore.kernel.org/git/f27db281-abad-5043-6d71-cbb083b1c877@gmail.com/ + A discussion of a "two-dimensional graph position" that can allow reading + multiple commit-graph chains at the same time. diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt index 1c0086e287..844629c8c4 100644 --- a/Documentation/technical/directory-rename-detection.txt +++ b/Documentation/technical/directory-rename-detection.txt @@ -20,8 +20,8 @@ More interesting possibilities exist, though, such as: * one side of history renames x -> z, and the other renames some file to x/e, causing the need for the merge to do a transitive rename. - * one side of history renames x -> z, but also renames all files within - x. For example, x/a -> z/alpha, x/b -> z/bravo, etc. + * one side of history renames x -> z, but also renames all files within x. + For example, x/a -> z/alpha, x/b -> z/bravo, etc. * both 'x' and 'y' being merged into a single directory 'z', with a directory rename being detected for both x->z and y->z. diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index bc2ace2a6e..5b2db3be1e 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -456,7 +456,7 @@ packfile marked as UNREACHABLE_GARBAGE (using the PSRC field; see below). To avoid the race when writing new objects referring to an about-to-be-deleted object, code paths that write new objects will need to copy any objects from UNREACHABLE_GARBAGE packs that they -refer to to new, non-UNREACHABLE_GARBAGE packs (or loose objects). +refer to new, non-UNREACHABLE_GARBAGE packs (or loose objects). UNREACHABLE_GARBAGE are then safe to delete if their creation time (as indicated by the file's mtime) is long enough ago. @@ -531,7 +531,7 @@ Until Git protocol gains SHA-256 support, using SHA-256 based storage on public-facing Git servers is strongly discouraged. Once Git protocol gains SHA-256 support, SHA-256 based servers are likely not to support SHA-1 compatibility, to avoid what may be a very expensive -hash reencode during clone and to encourage peers to modernize. +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 @@ -602,7 +602,7 @@ git --output-format=sha1 log abac87a^{sha1}..f787cac^{sha256} Choice of Hash -------------- -In early 2005, around the time that Git was written, Xiaoyun Wang, +In early 2005, around the time that Git was written, Xiaoyun Wang, Yiqun Lisa Yin, and Hongbo Yu announced an attack finding SHA-1 collisions in 2^69 operations. In August they published details. Luckily, no practical demonstrations of a collision in full SHA-1 were @@ -730,7 +730,7 @@ adoption. Using hash functions in parallel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -(e.g. https://public-inbox.org/git/22708.8913.864049.452252@chiark.greenend.org.uk/ ) +(e.g. https://lore.kernel.org/git/22708.8913.864049.452252@chiark.greenend.org.uk/ ) Objects newly created would be addressed by the new hash, but inside such an object (e.g. commit) it is still possible to address objects using the old hash function. @@ -783,7 +783,7 @@ bmwill@google.com, jonathantanmy@google.com, jrnieder@gmail.com, sbeller@google.com Initial version sent to -http://public-inbox.org/git/20170304011251.GA26789@aiede.mtv.corp.google.com +http://lore.kernel.org/git/20170304011251.GA26789@aiede.mtv.corp.google.com 2017-03-03 jrnieder@gmail.com Incorporated suggestions from jonathantanmy and sbeller: @@ -820,8 +820,8 @@ Later history: edits. This document history is no longer being maintained as it would now be superfluous to the commit log -[1] http://public-inbox.org/git/CA+55aFzJtejiCjV0e43+9oR3QuJK2PiFiLQemytoLpyJWe6P9w@mail.gmail.com/ -[2] http://public-inbox.org/git/CA+55aFz+gkAsDZ24zmePQuEs1XPS9BP_s8O7Q4wQ7LV7X5-oDA@mail.gmail.com/ -[3] http://public-inbox.org/git/20170306084353.nrns455dvkdsfgo5@sigill.intra.peff.net/ -[4] http://public-inbox.org/git/20170304224936.rqqtkdvfjgyezsht@genre.crustytoothpaste.net -[5] https://public-inbox.org/git/CAJo=hJtoX9=AyLHHpUJS7fueV9ciZ_MNpnEPHUz8Whui6g9F0A@mail.gmail.com/ +[1] http://lore.kernel.org/git/CA+55aFzJtejiCjV0e43+9oR3QuJK2PiFiLQemytoLpyJWe6P9w@mail.gmail.com/ +[2] http://lore.kernel.org/git/CA+55aFz+gkAsDZ24zmePQuEs1XPS9BP_s8O7Q4wQ7LV7X5-oDA@mail.gmail.com/ +[3] http://lore.kernel.org/git/20170306084353.nrns455dvkdsfgo5@sigill.intra.peff.net/ +[4] http://lore.kernel.org/git/20170304224936.rqqtkdvfjgyezsht@genre.crustytoothpaste.net +[5] https://lore.kernel.org/git/CAJo=hJtoX9=AyLHHpUJS7fueV9ciZ_MNpnEPHUz8Whui6g9F0A@mail.gmail.com/ diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index db3572626b..faa25c5c52 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -314,3 +314,44 @@ The remaining data of each directory block is grouped by type: - An ewah bitmap, the n-th bit indicates whether the n-th index entry is not CE_FSMONITOR_VALID. + +== End of Index Entry + + The End of Index Entry (EOIE) is used to locate the end of the variable + length index entries and the beginning of the extensions. Code can take + advantage of this to quickly locate the index extensions without having + to parse through all of the index entries. + + Because it must be able to be loaded before the variable length cache + entries and other index extensions, this extension must be written last. + The signature for this extension is { 'E', 'O', 'I', 'E' }. + + The extension consists of: + + - 32-bit offset to the end of the index entries + + - 160-bit SHA-1 over the extension types and their sizes (but not + their contents). E.g. if we have "TREE" extension that is N-bytes + long, "REUC" extension that is M-bytes long, followed by "EOIE", + then the hash would be: + + SHA-1("TREE" + <binary representation of N> + + "REUC" + <binary representation of M>) + +== Index Entry Offset Table + + The Index Entry Offset Table (IEOT) is used to help address the CPU + cost of loading the index by enabling multi-threading the process of + converting cache entries from the on-disk format to the in-memory format. + The signature for this extension is { 'I', 'E', 'O', 'T' }. + + The extension consists of: + + - 32-bit version (currently 1) + + - A number of index offset entries each consisting of: + + - 32-bit offset from the beginning of the file to the first cache entry + in this block of entries. + + - 32-bit count of cache entries in this block diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index d7e57639f7..4e7631437a 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -36,7 +36,7 @@ Design Details directory of an alternate. It refers only to packfiles in that same directory. -- The pack.multiIndex config setting must be on to consume MIDX files. +- The core.multiPackIndex config setting must be on to consume MIDX files. - The file format includes parameters for the object ID hash function, so a future change of hash algorithm does not require @@ -102,8 +102,8 @@ Related Links [0] https://bugs.chromium.org/p/git/issues/detail?id=6 Chromium work item for: Multi-Pack Index (MIDX) -[1] https://public-inbox.org/git/20180107181459.222909-1-dstolee@microsoft.com/ +[1] https://lore.kernel.org/git/20180107181459.222909-1-dstolee@microsoft.com/ An earlier RFC for the multi-pack-index feature -[2] https://public-inbox.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/ +[2] https://lore.kernel.org/git/alpine.DEB.2.20.1803091557510.23109@alexmv-linux/ Git Merge 2018 Contributor's summit notes (includes discussion of MIDX) diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index cab5bdd2ff..d3a142c652 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -315,10 +315,11 @@ CHUNK DATA: Stores two 4-byte values for every object. 1: The pack-int-id for the pack storing this object. 2: The offset within the pack. - If all offsets are less than 2^31, then the large offset chunk + If all offsets are less than 2^32, then the large offset chunk will not exist and offsets are stored as in IDX v1. If there is at least one offset value larger than 2^32-1, then - the large offset chunk must exist. If the large offset chunk + the large offset chunk must exist, and offsets larger than + 2^31-1 must be stored in it instead. If the large offset chunk exists and the 31st bit is on, then removing that bit reveals the row in the large offsets containing the 8-byte offset of this object. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 6ac774d5f6..d5ce4eea8a 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -22,6 +22,16 @@ protocol-common.txt. When the grammar indicate `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. +An error packet is a special pkt-line that contains an error string. + +---- + error-line = PKT-LINE("ERR" SP explanation-text) +---- + +Throughout the protocol, where `PKT-LINE(...)` is expected, an error packet MAY +be sent. Once this packet is sent by a client or a server, the data transfer +process defined in this protocol is terminated. + Transports ---------- There are three transports over which the packfile protocol is @@ -89,13 +99,6 @@ process on the server side over the Git protocol is this: "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418 -If the server refuses the request for some reasons, it could abort -gracefully with an error message. - ----- - error-line = PKT-LINE("ERR" SP explanation-text) ----- - SSH Transport ------------- @@ -398,12 +401,11 @@ from the client). Then the server will start sending its packfile data. ---- - server-response = *ack_multi ack / nak / error-line + server-response = *ack_multi ack / nak ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" ack = PKT-LINE("ACK" SP obj-id) nak = PKT-LINE("NAK") - error-line = PKT-LINE("ERR" SP explanation-text) ---- A simple clone may look like this (with no 'have' lines): @@ -642,7 +644,7 @@ update was successful, or 'ng [refname] [error]' if the update was not. command-ok = PKT-LINE("ok" SP refname) command-fail = PKT-LINE("ng" SP refname SP error-msg) - error-msg = 1*(OCTECT) ; where not "ok" + error-msg = 1*(OCTET) ; where not "ok" ---- Updates can be unsuccessful for a number of reasons. The reference can have @@ -655,14 +657,14 @@ can be rejected. An example client/server communication might look like this: ---- - S: 007c74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n + S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n - S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n + S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n S: 0000 - C: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n - C: 003e74730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n + C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n + C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n C: 0000 C: [PACKDATA] diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 1ef66bd788..b9e17e7a28 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -30,12 +30,20 @@ advance* during clone and fetch operations and thereby reduce download times and disk usage. Missing objects can later be "demand fetched" if/when needed. +A remote that can later provide the missing objects is called a +promisor remote, as it promises to send the objects when +requested. Initially Git supported only one promisor remote, the origin +remote from which the user cloned and that was configured in the +"extensions.partialClone" config option. Later support for more than +one promisor remote has been implemented. + Use of partial clone requires that the user be online and the origin -remote be available for on-demand fetching of missing objects. This may -or may not be problematic for the user. For example, if the user can -stay within the pre-selected subset of the source tree, they may not -encounter any missing objects. Alternatively, the user could try to -pre-fetch various objects if they know that they are going offline. +remote or other promisor remotes be available for on-demand fetching +of missing objects. This may or may not be problematic for the user. +For example, if the user can stay within the pre-selected subset of +the source tree, they may not encounter any missing objects. +Alternatively, the user could try to pre-fetch various objects if they +know that they are going offline. Non-Goals @@ -100,21 +108,21 @@ or commits that reference missing trees. Handling Missing Objects ------------------------ -- An object may be missing due to a partial clone or fetch, or missing due - to repository corruption. To differentiate these cases, the local - repository specially indicates such filtered packfiles obtained from the - promisor remote as "promisor packfiles". +- An object may be missing due to a partial clone or fetch, or missing + due to repository corruption. To differentiate these cases, the + local repository specially indicates such filtered packfiles + obtained from promisor remotes as "promisor packfiles". + These promisor packfiles consist of a "<name>.promisor" file with arbitrary contents (like the "<name>.keep" files), in addition to their "<name>.pack" and "<name>.idx" files. - The local repository considers a "promisor object" to be an object that - it knows (to the best of its ability) that the promisor remote has promised - that it has, either because the local repository has that object in one of + it knows (to the best of its ability) that promisor remotes have promised + that they have, either because the local repository has that object in one of its promisor packfiles, or because another promisor object refers to it. + -When Git encounters a missing object, Git can see if it a promisor object +When Git encounters a missing object, Git can see if it is a promisor object and handle it appropriately. If not, Git can report a corruption. + This means that there is no need for the client to explicitly maintain an @@ -123,12 +131,12 @@ expensive-to-modify list of missing objects.[a] - Since almost all Git code currently expects any referenced object to be present locally and because we do not want to force every command to do a dry-run first, a fallback mechanism is added to allow Git to attempt - to dynamically fetch missing objects from the promisor remote. + to dynamically fetch missing objects from promisor remotes. + When the normal object lookup fails to find an object, Git invokes -fetch-object to try to get the object from the server and then retry -the object lookup. This allows objects to be "faulted in" without -complicated prediction algorithms. +promisor_remote_get_direct() to try to get the object from a promisor +remote and then retry the object lookup. This allows objects to be +"faulted in" without complicated prediction algorithms. + For efficiency reasons, no check as to whether the missing object is actually a promisor object is performed. @@ -157,8 +165,7 @@ and prefetch those objects in bulk. + We are not happy with this global variable and would like to remove it, but that requires significant refactoring of the object code to pass an -additional flag. We hope that concurrent efforts to add an ODB API can -encompass this. +additional flag. Fetching Missing Objects @@ -182,21 +189,63 @@ has been updated to not use any object flags when the corresponding argument though they are not necessary. +Using many promisor remotes +--------------------------- + +Many promisor remotes can be configured and used. + +This allows for example a user to have multiple geographically-close +cache servers for fetching missing blobs while continuing to do +filtered `git-fetch` commands from the central server. + +When fetching objects, promisor remotes are tried one after the other +until all the objects have been fetched. + +Remotes that are considered "promisor" remotes are those specified by +the following configuration variables: + +- `extensions.partialClone = <name>` + +- `remote.<name>.promisor = true` + +- `remote.<name>.partialCloneFilter = ...` + +Only one promisor remote can be configured using the +`extensions.partialClone` config variable. This promisor remote will +be the last one tried when fetching objects. + +We decided to make it the last one we try, because it is likely that +someone using many promisor remotes is doing so because the other +promisor remotes are better for some reason (maybe they are closer or +faster for some kind of objects) than the origin, and the origin is +likely to be the remote specified by extensions.partialClone. + +This justification is not very strong, but one choice had to be made, +and anyway the long term plan should be to make the order somehow +fully configurable. + +For now though the other promisor remotes will be tried in the order +they appear in the config file. + Current Limitations ------------------- -- The remote used for a partial clone (or the first partial fetch - following a regular clone) is marked as the "promisor remote". +- It is not possible to specify the order in which the promisor + remotes are tried in other ways than the order in which they appear + in the config file. + -We are currently limited to a single promisor remote and only that -remote may be used for subsequent partial fetches. +It is also not possible to specify an order to be used when fetching +from one remote and a different order when fetching from another +remote. + +- It is not possible to push only specific objects to a promisor + remote. + -We accept this limitation because we believe initial users of this -feature will be using it on repositories with a strong single central -server. +It is not possible to push at the same time to multiple promisor +remote in a specific order. -- Dynamic object fetching will only ask the promisor remote for missing - objects. We assume that the promisor remote has a complete view of the +- Dynamic object fetching will only ask promisor remotes for missing + objects. We assume that promisor remotes have a complete view of the repository and can satisfy all such requests. - Repack essentially treats promisor and non-promisor packfiles as 2 @@ -218,15 +267,17 @@ server. Future Work ----------- -- Allow more than one promisor remote and define a strategy for fetching - missing objects from specific promisor remotes or of iterating over the - set of promisor remotes until a missing object is found. +- Improve the way to specify the order in which promisor remotes are + tried. + -A user might want to have multiple geographically-close cache servers -for fetching missing blobs while continuing to do filtered `git-fetch` -commands from the central server, for example. +For example this could allow to specify 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." + +- Allow pushing to promisor remotes. + -Or the user might want to work in a triangular work flow with multiple +The user might want to work in a triangular work flow with multiple promisor remotes that each have an incomplete view of the repository. - Allow repack to work on promisor packfiles (while keeping them distinct @@ -299,26 +350,26 @@ Related Links [0] https://crbug.com/git/2 Bug#2: Partial Clone -[1] https://public-inbox.org/git/20170113155253.1644-1-benpeart@microsoft.com/ + +[1] https://lore.kernel.org/git/20170113155253.1644-1-benpeart@microsoft.com/ + Subject: [RFC] Add support for downloading blobs on demand + Date: Fri, 13 Jan 2017 10:52:53 -0500 -[2] https://public-inbox.org/git/cover.1506714999.git.jonathantanmy@google.com/ + +[2] https://lore.kernel.org/git/cover.1506714999.git.jonathantanmy@google.com/ + Subject: [PATCH 00/18] Partial clone (from clone to lazy fetch in 18 patches) + Date: Fri, 29 Sep 2017 13:11:36 -0700 -[3] https://public-inbox.org/git/20170426221346.25337-1-jonathantanmy@google.com/ + +[3] https://lore.kernel.org/git/20170426221346.25337-1-jonathantanmy@google.com/ + Subject: Proposal for missing blob support in Git repos + Date: Wed, 26 Apr 2017 15:13:46 -0700 -[4] https://public-inbox.org/git/1488999039-37631-1-git-send-email-git@jeffhostetler.com/ + +[4] https://lore.kernel.org/git/1488999039-37631-1-git-send-email-git@jeffhostetler.com/ + Subject: [PATCH 00/10] RFC Partial Clone and Fetch + Date: Wed, 8 Mar 2017 18:50:29 +0000 -[5] https://public-inbox.org/git/20170505152802.6724-1-benpeart@microsoft.com/ + +[5] https://lore.kernel.org/git/20170505152802.6724-1-benpeart@microsoft.com/ + Subject: [PATCH v7 00/10] refactor the filter process code into a reusable module + Date: Fri, 5 May 2017 11:27:52 -0400 -[6] https://public-inbox.org/git/20170714132651.170708-1-benpeart@microsoft.com/ + +[6] https://lore.kernel.org/git/20170714132651.170708-1-benpeart@microsoft.com/ + Subject: [RFC/PATCH v2 0/1] Add support for downloading blobs on demand + Date: Fri, 14 Jul 2017 09:26:50 -0400 diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 332d209b58..2b267c0da6 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -1,6 +1,10 @@ Git Protocol Capabilities ========================= +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] +doc. + Servers SHOULD support all capabilities defined in this document. On the very first line of the initial server response of either @@ -172,6 +176,20 @@ agent strings are purely informative for statistics and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features. +symref +------ + +This parameterized capability is used to inform the receiver which symbolic ref +points to which ref; for example, "symref=HEAD:refs/heads/master" tells the +receiver that HEAD points to master. This capability can be repeated to +represent multiple symrefs. + +Servers SHOULD include this capability for the HEAD symref if it is one of the +refs being sent. + +Clients MAY use the parameters from this capability to select the proper initial +branch when cloning a repository. + shallow ------- diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index 09e4e0273f..7e3766cafb 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -1,5 +1,5 @@ - Git Wire Protocol, Version 2 -============================== +Git Wire Protocol, Version 2 +============================ This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways: @@ -22,8 +22,8 @@ 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. - Packet-Line Framing ---------------------- +Packet-Line Framing +------------------- All communication is done using packet-line framing, just as in v1. See `Documentation/technical/pack-protocol.txt` and @@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics: * '0000' Flush Packet (flush-pkt) - indicates the end of a message * '0001' Delimiter Packet (delim-pkt) - separates sections of a message - Initial Client Request ------------------------- +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 @@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`. More information can be found in `pack-protocol.txt` and `http-protocol.txt`. In all cases the response from the server is the capability advertisement. - Git Transport -~~~~~~~~~~~~~~~ +Git Transport +~~~~~~~~~~~~~ When using the git:// transport, you can request to use protocol v2 by sending "version=2" as an extra parameter: 003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0 - SSH and File Transport -~~~~~~~~~~~~~~~~~~~~~~~~ +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". - HTTP Transport -~~~~~~~~~~~~~~~~ +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 @@ -79,8 +79,8 @@ 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). - Capability Advertisement --------------------------- +Capability Advertisement +------------------------ A server which decides to communicate (based on a request from a client) using protocol version 2, notifies the client by sending a version string @@ -101,8 +101,8 @@ to be executed by the client. key = 1*(ALPHA | DIGIT | "-_") value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;") - Command Request ------------------ +Command Request +--------------- After receiving the capability advertisement, a client can then issue a request to select the command it wants with any particular capabilities @@ -137,11 +137,11 @@ command be executed or can terminate the connection. A client may optionally send an empty request consisting of just a flush-pkt to indicate that no more requests will be made. - Capabilities --------------- +Capabilities +------------ There are two different types of capabilities: normal capabilities, -which can be used to to convey information or alter the behavior of a +which can be used to convey information or alter the behavior of a request, and commands, which are the core actions that a client wants to perform (fetch, push, etc). @@ -153,8 +153,8 @@ management on the server side in order to function correctly. This permits simple round-robin load-balancing on the server side, without needing to worry about state management. - agent -~~~~~~~ +agent +~~~~~ The server can advertise the `agent` capability with a value `X` (in the form `agent=X`) to notify the client that the server is running version @@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x < and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features. - ls-refs -~~~~~~~~~ +ls-refs +~~~~~~~ `ls-refs` is the command used to request a reference advertisement in v2. Unlike the current reference advertisement, ls-refs takes in arguments @@ -199,8 +199,8 @@ The output of ls-refs is as follows: symref = "symref-target:" symref-target peeled = "peeled:" obj-id - fetch -~~~~~~~ +fetch +~~~~~ `fetch` is the command used to fetch a packfile in v2. It can be looked at as a modified version of the v1 fetch where the ref-advertisement is @@ -252,7 +252,7 @@ A `fetch` request can take the following arguments: ofs-delta Indicate that the client understands PACKv2 with delta referring to its base by position in pack rather than by an oid. That is, - they can read OBJ_OFS_DELTA (ake type 6) in a packfile. + they can read OBJ_OFS_DELTA (aka type 6) in a packfile. If the 'shallow' feature is advertised the following arguments can be included in the clients request as well as the potential addition of the @@ -296,7 +296,13 @@ included in the client's request: Request that various objects from the packfile be omitted using one of several filtering techniques. These are intended for use with partial clone and partial fetch operations. See - `rev-list` for possible "filter-spec" values. + `rev-list` for possible "filter-spec" values. When communicating + with other processes, senders SHOULD translate scaled integers + (e.g. "1k") into a fully-expanded form (e.g. "1024") to aid + interoperability with older receivers that may not understand + newly-invented scaling suffixes. However, receivers SHOULD + accept the following suffixes: 'k', 'm', and 'g' for 1024, + 1048576, and 1073741824, respectively. If the 'ref-in-want' feature is advertised, the following argument can be included in the client's request as well as the potential addition of @@ -307,6 +313,16 @@ the 'wanted-refs' section in the server's response as explained below. particular ref, where <ref> is the full name of a ref on the server. +If the 'sideband-all' feature is advertised, the following argument can be +included in the client's request: + + sideband-all + Instruct the server to send the whole response multiplexed, not just + the packfile section. All non-flush and non-delim PKT-LINE in the + response (not only in the packfile section) will then start with a byte + indicating its sideband (1, 2, or 3), and the server may send "0005\2" + (a PKT-LINE of sideband 2 with no payload) as a keepalive packet. + The response of `fetch` is broken into a number of sections separated by delimiter packets (0001), with each section beginning with its section header. @@ -428,8 +444,8 @@ header. 2 - progress messages 3 - fatal error message just before stream aborts - server-option -~~~~~~~~~~~~~~~ +server-option +~~~~~~~~~~~~~ If advertised, indicates that any number of server specific options can be included in a request. This is done by sending each option as a diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 4a8be4d144..ceda4bbfda 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -51,7 +51,7 @@ of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git only fixes the issue for file systems with exactly 1 ns or 1 s resolution. Other file systems are still broken in current Linux kernels (e.g. CEPH, CIFS, NTFS, UDF), see -https://lkml.org/lkml/2015/6/9/714 +https://lore.kernel.org/lkml/5577240D.7020309@gmail.com/ Racy Git -------- diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt index e03eaccebc..7844ef30ff 100644 --- a/Documentation/technical/repository-version.txt +++ b/Documentation/technical/repository-version.txt @@ -1,5 +1,4 @@ -Git Repository Format Versions -============================== +== Git Repository Format Versions Every git repository is marked with a numeric version in the `core.repositoryformatversion` key of its `config` file. This version @@ -40,16 +39,14 @@ format by default. The currently defined format versions are: -Version `0` ------------ +=== Version `0` This is the format defined by the initial version of git, including but not limited to the format of the repository directory, the repository configuration file, and the object and ref storage. Specifying the complete behavior of git is beyond the scope of this document. -Version `1` ------------ +=== Version `1` This format is identical to version `0`, with the following exceptions: @@ -74,21 +71,18 @@ it here, in order to claim the name. The defined extensions are: -`noop` -~~~~~~ +==== `noop` This extension does not change git's behavior at all. It is useful only for testing format-1 compatibility. -`preciousObjects` -~~~~~~~~~~~~~~~~~ +==== `preciousObjects` 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 that the repo was created with a partial clone (or later performed @@ -98,3 +92,11 @@ and it promises that all such omitted objects can be fetched from it in the future. 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 +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) diff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.txt new file mode 100644 index 0000000000..af5f9fc24f --- /dev/null +++ b/Documentation/technical/rerere.txt @@ -0,0 +1,186 @@ +Rerere +====== + +This document describes the rerere logic. + +Conflict normalization +---------------------- + +To ensure recorded conflict resolutions can be looked up in the rerere +database, even when branches are merged in a different order, +different branches are merged that result in the same conflict, or +when different conflict style settings are used, rerere normalizes the +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. + +Once these two normalization operations are applied, a conflict ID is +calculated based on the normalized conflict, which is later used by +rerere to look up the conflict in the rerere database. + +Removing the common ancestor version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Say we have three branches AB, AC and AC2. The common ancestor of +these branches has a file with a line containing the string "A" (for +brevity this is called "line A" in the rest of the document). In +branch AB this line is changed to "B", in AC, this line is changed to +"C", and branch AC2 is forked off of AC, after the line was changed to +"C". + +Forking a branch ABAC off of branch AB and then merging AC into it, we +get a conflict like the following: + + <<<<<<< HEAD + B + ======= + C + >>>>>>> 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: + + <<<<<<< HEAD + B + ||||||| merged common ancestors + A + ======= + C + >>>>>>> AC2 + +By resolving this conflict, to leave line D, the user declares: + + After examining what branches AB and AC did, I believe that making + line A into line D is the best thing to do that is compatible with + 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. + +By extension, this means that rerere should recognize that the above +conflicts are the same. To do this, the labels on the conflict +markers are stripped, and the common ancestor version is removed. The above +examples would both result in the following normalized conflict: + + <<<<<<< + B + ======= + C + >>>>>>> + +Sorting hunks +~~~~~~~~~~~~~ + +As before, lets 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: + + - AB: changes A to B + - AC: changes A to C + - XY: changes X to Y + - XZ: changes X to Z + +Now, forking a branch ABAC off of branch AB and then merging AC into +it, and forking a branch ACAB off of branch AC and then merging AB +into it, would yield the conflict in a different order. The former +would say "A became B or C, what now?" while the latter would say "A +became C or B, what now?" + +As a reminder, the act of merging AC into ABAC and resolving the +conflict to leave line D means that the user declares: + + After examining what branches AB and AC did, I believe that + making line A into line D is the best thing to do that is + 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 +declaration. + +Imagine that similarly previously a branch XYXZ was forked from XY, +and XZ was merged into it, and resolved "X became Y or Z" into "X +became W". + +Now, if a branch ABXY was forked from AB and then merged XY, then ABXY +would have line B in its early part and line Y in its later part. +Such a merge would be quite clean. We can construct 4 combinations +using these four branches ((AB, AC) x (XY, XZ)). + +Merging ABXY and ACXZ would make "an early A became B or C, a late X +became Y or Z" conflict, while merging ACXY and ABXZ would make "an +early A became C or B, a late X became Y or Z". We can see there are +4 combinations of ("B or C", "C or B") x ("X or Y", "Y or X"). + +By sorting, the conflict is given its canonical name, namely, "an +early part became B or C, a late part became X or Y", and whenever +any of these four patterns appear, and we can get to the same conflict +and resolution that we saw earlier. + +Without the sorting, we'd have to somehow find a previous resolution +from combinatorial explosion. + +Conflict ID calculation +~~~~~~~~~~~~~~~~~~~~~~~ + +Once the conflict normalization is done, the conflict ID is calculated +as the sha1 hash of the conflict hunks appended to each other, +separated by <NUL> characters. The conflict markers are stripped out +before the sha1 is calculated. So in the example above, where we +merge branch AC which changes line A to line C, into branch AB, which +changes line A to line C, the conflict ID would be +SHA1('B<NUL>C<NUL>'). + +If there are multiple conflicts in one file, the sha1 is calculated +the same way with all hunks appended to each other, in the order in +which they appear in the file, separated by a <NUL> character. + +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 +inner conflict. This is done recursively, so any number of nested +conflicts can be handled. + +Note that this only works for conflict markers that "cleanly nest". If +there are any unmatched conflict markers, rerere will fail to handle +the conflict and record a conflict resolution. + +The only difference is in how the conflict ID is calculated. For the +inner conflict, the conflict markers themselves are not stripped out +before calculating the sha1. + +Say we have the following conflict for example: + + <<<<<<< HEAD + 1 + ======= + <<<<<<< HEAD + 3 + ======= + 2 + >>>>>>> branch-2 + >>>>>>> branch-3~ + +After stripping out the labels of the conflict markers, and sorting +the hunks, the conflict would look as follows: + + <<<<<<< + 1 + ======= + <<<<<<< + 2 + ======= + 3 + >>>>>>> + >>>>>>> + +and finally the conflict ID would be calculated as: +`sha1('1<NUL><<<<<<<\n3\n=======\n2\n>>>>>>><NUL>')` diff --git a/Documentation/trace2-target-values.txt b/Documentation/trace2-target-values.txt new file mode 100644 index 0000000000..3985b6d3c2 --- /dev/null +++ b/Documentation/trace2-target-values.txt @@ -0,0 +1,12 @@ +-- +* `0` or `false` - Disables the target. +* `1` or `true` - Writes to `STDERR`. +* `[2-9]` - Writes to the already opened file descriptor. +* `<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 +Unix DomainSocket (on platforms that support them). Socket +type can be either `stream` or `dgram`; if omitted Git will +try both. +-- diff --git a/Documentation/urls.txt b/Documentation/urls.txt index b05da95788..1c229d7581 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -53,6 +53,9 @@ These two syntaxes are mostly equivalent, except the former implies --local option. endif::git-clone[] +'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 exists. To explicitly request a remote helper, the following syntax @@ -62,7 +65,7 @@ may be used: 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[1] for details. +invoked. See linkgit:gitremote-helpers[7] for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index d87294de2f..0148f126dc 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -9,13 +9,3 @@ tilde=~ [linkgit-inlinemacro] <ulink url="{target}.html">{target}{0?({0})}</ulink> - -ifdef::backend-docbook[] -# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. -[listingblock] -<example><title>{title}</title> -<literallayout class="monospaced"> -| -</literallayout> -{title#}</example> -endif::backend-docbook[] diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index eff7890274..833652983f 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,5 +1,4 @@ -Git User Manual -=============== += Git User Manual Git is a fast distributed revision control system. @@ -41,12 +40,10 @@ complete. [[repositories-and-branches]] -Repositories and Branches -========================= +== Repositories and Branches [[how-to-get-a-git-repository]] -How to get a Git repository ---------------------------- +=== How to get a Git repository It will be useful to have a Git repository to experiment with as you read this manual. @@ -73,8 +70,7 @@ top-level directory named `.git`, which contains all the information about the history of the project. [[how-to-check-out]] -How to check out a different version of a project -------------------------------------------------- +=== How to check out a different version of a project Git is best thought of as a tool for storing the history of a collection of files. It stores the history as a compressed collection of @@ -122,10 +118,10 @@ Tags are expected to always point at the same version of a project, while heads are expected to advance as development progresses. Create a new branch head pointing to one of these versions and check it -out using linkgit:git-checkout[1]: +out using linkgit:git-switch[1]: ------------------------------------------------ -$ git checkout -b new v2.6.13 +$ git switch -c new v2.6.13 ------------------------------------------------ The working directory then reflects the contents that the project had @@ -151,8 +147,7 @@ with no way to find the history it used to point to; so use this command carefully. [[understanding-commits]] -Understanding History: Commits ------------------------------- +=== Understanding History: Commits Every change in the history of a project is represented by a commit. The linkgit:git-show[1] command shows the most recent commit on the @@ -202,8 +197,7 @@ history, including file data and directory contents, is stored in an object with a name that is a hash of its contents. [[understanding-reachability]] -Understanding history: commits, parents, and reachability -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Understanding history: commits, parents, and reachability Every commit (except the very first commit in a project) also has a parent commit which shows what happened before this commit. @@ -227,8 +221,7 @@ that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X. [[history-diagrams]] -Understanding history: History diagrams -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Understanding history: History diagrams We will sometimes represent Git history using diagrams like the one below. Commits are shown as "o", and the links between them with @@ -247,8 +240,7 @@ If we need to talk about a particular commit, the character "o" may be replaced with another letter or number. [[what-is-a-branch]] -Understanding history: What is a branch? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Understanding history: What is a branch? When we need to be precise, we will use the word "branch" to mean a line of development, and "branch head" (or just "head") to mean a reference @@ -261,8 +253,7 @@ However, when no confusion will result, we often just use the term "branch" both for branches and for branch heads. [[manipulating-branches]] -Manipulating branches ---------------------- +=== Manipulating branches Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands: @@ -282,10 +273,10 @@ a summary of the commands: this command will fail with a warning. `git branch -D <branch>`:: delete the branch `<branch>` irrespective of its merged status. -`git checkout <branch>`:: +`git switch <branch>`:: make the current branch `<branch>`, updating the working directory to reflect the version referenced by `<branch>`. -`git checkout -b <new> <start-point>`:: +`git switch -c <new> <start-point>`:: create a new branch `<new>` referencing `<start-point>`, and check it out. @@ -299,25 +290,24 @@ ref: refs/heads/master ------------------------------------------------ [[detached-head]] -Examining an old version without creating a new branch ------------------------------------------------------- +=== Examining an old version without creating a new branch -The `git checkout` command normally expects a branch head, but will also -accept an arbitrary commit; for example, you can check out the commit -referenced by a tag: +The `git switch` command normally expects a branch head, but will also +accept an arbitrary commit when invoked with --detach; for example, +you can check out the commit referenced by a tag: ------------------------------------------------ -$ git checkout v2.6.17 +$ git switch --detach v2.6.17 Note: checking out 'v2.6.17'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this -state without impacting any branches by performing another checkout. +state without impacting any branches by performing another switch. If you want to create a new branch to retain commits you create, you may -do so (now or later) by using -b with the checkout command again. Example: +do so (now or later) by using -c with the switch command again. Example: - git checkout -b new_branch_name + git switch -c new_branch_name HEAD is now at 427abfa Linux v2.6.17 ------------------------------------------------ @@ -340,8 +330,7 @@ make up a name for the new branch. You can still create a new branch (or tag) for this version later if you decide to. [[examining-remote-branches]] -Examining branches from a remote repository -------------------------------------------- +=== Examining branches from a remote repository The "master" branch that was created at the time you cloned is a copy of the HEAD in the repository that you cloned from. That repository @@ -373,7 +362,7 @@ You might want to build on one of these remote-tracking branches on a branch of your own, just as you would for a tag: ------------------------------------------------ -$ git checkout -b my-todo-copy origin/todo +$ git switch -c my-todo-copy origin/todo ------------------------------------------------ You can also check out `origin/todo` directly to examine it or @@ -383,8 +372,7 @@ Note that the name "origin" is just the name that Git uses by default to refer to the repository that you cloned from. [[how-git-stores-references]] -Naming branches, tags, and other references -------------------------------------------- +=== Naming branches, tags, and other references Branches, remote-tracking branches, and tags are all references to commits. All references are named with a slash-separated path name @@ -413,8 +401,7 @@ references with the same shorthand name, see the "SPECIFYING REVISIONS" section of linkgit:gitrevisions[7]. [[Updating-a-repository-With-git-fetch]] -Updating a repository with git fetch ------------------------------------- +=== Updating a repository with git fetch After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates. @@ -425,8 +412,7 @@ repository. It will not touch any of your own branches--not even the "master" branch that was created for you on clone. [[fetching-branches]] -Fetching branches from other repositories ------------------------------------------ +=== Fetching branches from other repositories You can also track branches from repositories other than the one you cloned from, using linkgit:git-remote[1]: @@ -474,8 +460,7 @@ text editor. (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for details.) [[exploring-git-history]] -Exploring Git history -===================== +== Exploring Git history Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of @@ -489,8 +474,7 @@ We start with one specialized tool that is useful for finding the commit that introduced a bug into a project. [[using-bisect]] -How to use bisect to find a regression --------------------------------------- +=== How to use bisect to find a regression Suppose version 2.6.18 of your project worked, but the version at "master" crashes. Sometimes the best way to find the cause of such a @@ -572,8 +556,7 @@ linkgit:git-bisect[1] for more information about this and other `git bisect` features. [[naming-commits]] -Naming commits --------------- +=== Naming commits We have seen several ways of naming commits already: @@ -637,8 +620,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b ------------------------------------------------- [[creating-tags]] -Creating tags -------------- +=== Creating tags We can also create a tag to refer to a particular commit; after running @@ -655,8 +637,7 @@ should create a tag object instead; see the linkgit:git-tag[1] man page for details. [[browsing-revisions]] -Browsing revisions ------------------- +=== Browsing revisions The linkgit:git-log[1] command can show lists of commits. On its own, it shows all commits reachable from the parent commit; but you @@ -697,8 +678,7 @@ multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary. [[generating-diffs]] -Generating diffs ----------------- +=== Generating diffs You can generate diffs between any two versions using linkgit:git-diff[1]: @@ -726,8 +706,7 @@ will generate a file with a patch for each commit reachable from test but not from master. [[viewing-old-file-versions]] -Viewing old file versions -------------------------- +=== Viewing old file versions You can always view an old version of a file by just checking out the correct revision first. But sometimes it is more convenient to be @@ -742,12 +721,10 @@ Before the colon may be anything that names a commit, and after it may be any path to a file tracked by Git. [[history-examples]] -Examples --------- +=== Examples [[counting-commits-on-a-branch]] -Counting the number of commits on a branch -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Counting the number of commits on a branch Suppose you want to know how many commits you've made on `mybranch` since it diverged from `origin`: @@ -765,8 +742,7 @@ $ git rev-list origin..mybranch | wc -l ------------------------------------------------- [[checking-for-equal-branches]] -Check whether two branches point at the same history -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Check whether two branches point at the same history Suppose you want to check whether two branches point at the same point in history. @@ -798,8 +774,7 @@ $ git log origin...master will return no commits when the two branches are equal. [[finding-tagged-descendants]] -Find first tagged version including a given fix -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Find first tagged version including a given fix Suppose you know that the commit e05db0fd fixed a certain problem. You'd like to find the earliest tagged release that contains that @@ -883,8 +858,7 @@ shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and from v1.5.0-rc2, and not from v1.5.0-rc0. [[showing-commits-unique-to-a-branch]] -Showing commits unique to a given branch -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Showing commits unique to a given branch Suppose you would like to see all the commits reachable from the branch head named `master` but not from any other head in your repository. @@ -931,8 +905,7 @@ $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) syntax such as `--not`.) [[making-a-release]] -Creating a changelog and tarball for a software release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Creating a changelog and tarball for a software release The linkgit:git-archive[1] command can create a tar or zip archive from any version of a project; for example: @@ -983,8 +956,7 @@ and then he just cut-and-pastes the output commands after verifying that they look OK. [[Finding-commits-With-given-Content]] -Finding commits referencing a file with given content -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Finding commits referencing a file with given content Somebody hands you a copy of a file, and asks which commits modified a file such that it contained the given content either before or after the @@ -1000,12 +972,10 @@ student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and linkgit:git-hash-object[1] man pages may prove helpful. [[Developing-With-git]] -Developing with Git -=================== +== Developing with Git [[telling-git-your-name]] -Telling Git your name ---------------------- +=== Telling Git your name Before creating any commits, you should introduce yourself to Git. The easiest way to do so is to use linkgit:git-config[1]: @@ -1030,8 +1000,7 @@ also edit it with your favorite editor. [[creating-a-new-repository]] -Creating a new repository -------------------------- +=== Creating a new repository Creating a new repository from scratch is very easy: @@ -1052,8 +1021,7 @@ $ git commit ------------------------------------------------- [[how-to-make-a-commit]] -How to make a commit --------------------- +=== How to make a commit Creating a new commit takes three steps: @@ -1148,8 +1116,7 @@ for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk For Commit"). [[creating-good-commit-messages]] -Creating good commit messages ------------------------------ +=== 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 @@ -1162,8 +1129,7 @@ rest of the commit in the body. [[ignoring-files]] -Ignoring files --------------- +=== Ignoring files A project will often generate files that you do 'not' want to track with Git. This typically includes files generated by a build process or temporary @@ -1205,8 +1171,7 @@ Some Git commands can also take exclude patterns directly on the command line. See linkgit:gitignore[5] for the details. [[how-to-merge]] -How to merge ------------- +=== How to merge You can rejoin two diverging branches of development using linkgit:git-merge[1]: @@ -1254,8 +1219,7 @@ has two parents, one pointing to the top of the current branch, and one to the top of the other branch. [[resolving-a-merge]] -Resolving a merge ------------------ +=== Resolving a merge When a merge isn't resolved automatically, Git leaves the index and the working tree in a special state that gives you all the @@ -1297,8 +1261,7 @@ The above is all you need to know to resolve a simple merge. But Git also provides more information to help resolve conflicts: [[conflict-resolution]] -Getting conflict-resolution help during a merge -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Getting conflict-resolution help during a merge All of the changes that Git was able to merge automatically are already added to the index file, so linkgit:git-diff[1] shows only @@ -1401,14 +1364,13 @@ the different stages of that file will be "collapsed", after which `git diff` will (by default) no longer show diffs for that file. [[undoing-a-merge]] -Undoing a merge ---------------- +=== Undoing a merge If you get stuck and decide to just give up and throw the whole mess away, you can always return to the pre-merge state with ------------------------------------------------- -$ git reset --hard HEAD +$ git merge --abort ------------------------------------------------- Or, if you've already committed the merge that you want to throw away, @@ -1423,8 +1385,7 @@ itself have been merged into another branch, as doing so may confuse further merges. [[fast-forwards]] -Fast-forward merges -------------------- +=== Fast-forward merges There is one special case not mentioned above, which is treated differently. Normally, a merge results in a merge commit, with two @@ -1438,15 +1399,14 @@ to point at the head of the merged-in branch, without any new commits being created. [[fixing-mistakes]] -Fixing mistakes ---------------- +=== Fixing mistakes If you've messed up the working tree, but haven't yet committed your mistake, you can return the entire working tree to the last committed state with ------------------------------------------------- -$ git reset --hard HEAD +$ git restore --staged --worktree :/ ------------------------------------------------- If you make a commit that you later wish you hadn't, there are two @@ -1463,8 +1423,7 @@ fundamentally different ways to fix the problem: a branch that has had its history changed. [[reverting-a-commit]] -Fixing a mistake with a new commit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Fixing a mistake with a new commit Creating a new commit that reverts an earlier change is very easy; just pass the linkgit:git-revert[1] command a reference to the bad @@ -1490,8 +1449,7 @@ conflicts manually, just as in the case of <<resolving-a-merge, resolving a merge>>. [[fixing-a-mistake-by-rewriting-history]] -Fixing a mistake by rewriting history -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Fixing a mistake by rewriting history If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just @@ -1518,17 +1476,14 @@ this is an advanced topic to be left for <<cleaning-up-history,another chapter>>. [[checkout-of-path]] -Checking out an old version of a file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Checking out an old version of a file In the process of undoing a previous bad change, you may find it useful to check out an older version of a particular file using -linkgit:git-checkout[1]. We've used `git checkout` before to switch -branches, but it has quite different behavior if it is given a path -name: the command +linkgit:git-restore[1]. The command ------------------------------------------------- -$ git checkout HEAD^ path/to/file +$ git restore --source=HEAD^ path/to/file ------------------------------------------------- replaces path/to/file by the contents it had in the commit HEAD^, and @@ -1545,8 +1500,7 @@ $ git show HEAD^:path/to/file which will display the given version of the file. [[interrupted-work]] -Temporarily setting aside work in progress -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Temporarily setting aside work in progress While you are in the middle of working on something complicated, you find an unrelated but obvious and trivial bug. You would like to fix it @@ -1577,8 +1531,7 @@ $ git stash pop [[ensuring-good-performance]] -Ensuring good performance -------------------------- +=== Ensuring good performance On large repositories, Git depends on compression to keep the history information from taking up too much space on disk or in memory. Some @@ -1589,12 +1542,10 @@ to avoid automatic compression kicking in when it is not convenient. [[ensuring-reliability]] -Ensuring reliability --------------------- +=== Ensuring reliability [[checking-for-corruption]] -Checking the repository for corruption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Checking the repository for corruption The linkgit:git-fsck[1] command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some @@ -1620,12 +1571,10 @@ You can run `git fsck --no-dangling` to suppress these messages, and still view real errors. [[recovering-lost-changes]] -Recovering lost changes -~~~~~~~~~~~~~~~~~~~~~~~ +==== Recovering lost changes [[reflogs]] -Reflogs -^^^^^^^ +===== Reflogs Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>, and then realize that the branch was the only reference you had to @@ -1672,8 +1621,7 @@ same project, the reflog history is not shared: it tells you only about how the branches in your local repository have changed over time. [[dangling-object-recovery]] -Examining dangling objects -^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== Examining dangling objects In some situations the reflog may not be able to save you. For example, suppose you delete a branch, then realize you need the history it @@ -1717,12 +1665,10 @@ dangling objects can arise in other situations. [[sharing-development]] -Sharing development with others -=============================== +== Sharing development with others [[getting-updates-With-git-pull]] -Getting updates with git pull ------------------------------ +=== Getting updates with git pull After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates and merge them @@ -1785,8 +1731,7 @@ $ git merge branch are roughly equivalent. [[submitting-patches]] -Submitting patches to a project -------------------------------- +=== Submitting patches to a project If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: @@ -1814,8 +1759,7 @@ Consult the mailing list for your project first to determine their requirements for submitting patches. [[importing-patches]] -Importing patches to a project ------------------------------- +=== Importing patches to a project Git also provides a tool called linkgit:git-am[1] (am stands for "apply mailbox"), for importing such an emailed series of patches. @@ -1847,8 +1791,7 @@ the original mailbox, with authorship and commit log message each taken from the message containing each patch. [[public-repositories]] -Public Git repositories ------------------------ +=== Public Git repositories Another way to submit changes to a project is to tell the maintainer of that project to pull the changes from your repository using @@ -1888,21 +1831,22 @@ pull from that repository. So the flow of changes, in a situation where there is one other developer with a public repository, looks like this: - you push - your personal repo ------------------> your public repo - ^ | - | | - | you pull | they pull - | | - | | - | they push V - their public repo <------------------- their repo +.... + you push +your personal repo ------------------> your public repo + ^ | + | | + | you pull | they pull + | | + | | + | they push V +their public repo <------------------- their repo +.... We explain how to do this in the following sections. [[setting-up-a-public-repository]] -Setting up a public repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Setting up a public repository Assume your personal repository is in the directory `~/proj`. We first create a new clone of the repository and tell `git daemon` that it @@ -1922,8 +1866,7 @@ public repository. You can use scp, rsync, or whatever is most convenient. [[exporting-via-git]] -Exporting a Git repository via the Git protocol -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Exporting a Git repository via the Git protocol This is the preferred method. @@ -1944,8 +1887,7 @@ linkgit:git-daemon[1] man page for details. (See especially the examples section.) [[exporting-via-http]] -Exporting a git repository via HTTP -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Exporting a git repository via HTTP The Git protocol gives better performance and reliability, but on a host with a web server set up, HTTP exports may be simpler to set up. @@ -1977,8 +1919,7 @@ for a slightly more sophisticated setup using WebDAV which also allows pushing over HTTP.) [[pushing-changes-to-a-public-repository]] -Pushing changes to a public repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Pushing changes to a public repository Note that the two techniques outlined above (exporting via <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other @@ -2037,8 +1978,7 @@ See the explanations of the `remote.<name>.url`, linkgit:git-config[1] for details. [[forcing-push]] -What to do when a push fails -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== What to do when a push fails If a push would not result in a <<fast-forwards,fast-forward>> of the remote branch, then it will fail with an error like: @@ -2092,8 +2032,7 @@ pull, or by a fetch followed by a rebase; see the linkgit:gitcvs-migration[7] for more. [[setting-up-a-shared-repository]] -Setting up a shared repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Setting up a shared repository Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights @@ -2123,8 +2062,7 @@ advantages over the central shared repository: "out". [[setting-up-gitweb]] -Allowing web browsing of a repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Allowing web browsing of a repository The gitweb cgi script provides users an easy way to browse your project's revisions, file contents and logs without having to install @@ -2140,8 +2078,7 @@ linkgit:gitweb[1] for instructions on details setting up a permanent installation with a CGI or Perl capable server. [[how-to-get-a-git-repository-with-minimal-history]] -How to get a Git repository with minimal history ------------------------------------------------- +=== How to get a Git repository with minimal history A <<def_shallow_clone,shallow clone>>, with its truncated history, is useful when one is interested only in recent history @@ -2160,12 +2097,10 @@ have to result in huge conflicts. This limitation may make such a repository unsuitable to be used in merge based workflows. [[sharing-development-examples]] -Examples --------- +=== Examples [[maintaining-topic-branches]] -Maintaining topic branches for a Linux subsystem maintainer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Maintaining topic branches for a Linux subsystem maintainer This describes how Tony Luck uses Git in his role as maintainer of the IA64 architecture for the Linux kernel. @@ -2211,8 +2146,8 @@ $ git branch --track release origin/master These can be easily kept up to date using linkgit:git-pull[1]. ------------------------------------------------- -$ git checkout test && git pull -$ git checkout release && git pull +$ git switch test && git pull +$ git switch release && git pull ------------------------------------------------- Important note! If you have any local changes in these branches, then @@ -2264,7 +2199,7 @@ tested changes 2) help future bug hunters that use `git bisect` to find problems ------------------------------------------------- -$ git checkout -b speed-up-spinlocks v2.6.35 +$ git switch -c speed-up-spinlocks v2.6.35 ------------------------------------------------- Now you apply the patch(es), run some tests, and commit the change(s). If @@ -2279,7 +2214,7 @@ When you are happy with the state of this change, you can merge it into the "test" branch in preparation to make it public: ------------------------------------------------- -$ git checkout test && git merge speed-up-spinlocks +$ git switch test && git merge speed-up-spinlocks ------------------------------------------------- It is unlikely that you would have any conflicts here ... but you might if you @@ -2291,7 +2226,7 @@ see the value of keeping each patch (or patch series) in its own branch. It means that the patches can be moved into the `release` tree in any order. ------------------------------------------------- -$ git checkout release && git merge speed-up-spinlocks +$ git switch release && git merge speed-up-spinlocks ------------------------------------------------- After a while, you will have a number of branches, and despite the @@ -2461,8 +2396,7 @@ done [[cleaning-up-history]] -Rewriting history and maintaining patch series -============================================== +== Rewriting history and maintaining patch series Normally commits are only added to a project, never taken away or replaced. Git is designed with this assumption, and violating it will @@ -2472,8 +2406,7 @@ However, there is a situation in which it can be useful to violate this assumption. [[patch-series]] -Creating the perfect patch series ---------------------------------- +=== Creating the perfect patch series Suppose you are a contributor to a large project, and you want to add a complicated feature, and to present it to the other developers in a way @@ -2505,14 +2438,13 @@ use them, and then explain some of the problems that can arise because you are rewriting history. [[using-git-rebase]] -Keeping a patch series up to date using git rebase --------------------------------------------------- +=== Keeping a patch series up to date using git rebase Suppose that you create a branch `mywork` on a remote-tracking branch `origin`, and create some commits on top of it: ------------------------------------------------- -$ git checkout -b mywork origin +$ git switch -c mywork origin $ vi file.txt $ git commit $ vi otherfile.txt @@ -2552,7 +2484,7 @@ commits without any merges, you may instead choose to use linkgit:git-rebase[1]: ------------------------------------------------- -$ git checkout mywork +$ git switch mywork $ git rebase origin ------------------------------------------------- @@ -2593,8 +2525,7 @@ the rebase. See <<interactive-rebase>> for details, and <<reordering-patch-series>> for alternatives. [[rewriting-one-commit]] -Rewriting a single commit -------------------------- +=== Rewriting a single commit We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the most recent commit using @@ -2612,8 +2543,7 @@ If you need to amend commits from deeper in your history, you can use <<interactive-rebase,interactive rebase's `edit` instruction>>. [[reordering-patch-series]] -Reordering or selecting from a patch series -------------------------------------------- +=== Reordering or selecting from a patch series Sometimes you want to edit a commit deeper in your history. One approach is to use `git format-patch` to create a series of patches @@ -2632,8 +2562,7 @@ $ git am *.patch ------------------------------------------------- [[interactive-rebase]] -Using interactive rebases -------------------------- +=== Using interactive rebases You can also edit a patch series with an interactive rebase. This is the same as <<reordering-patch-series,reordering a patch series using @@ -2690,16 +2619,14 @@ For a more detailed discussion of the procedure and additional tips, see the "INTERACTIVE MODE" section of linkgit:git-rebase[1]. [[patch-series-tools]] -Other tools ------------ +=== Other tools There are numerous other tools, such as StGit, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. [[problems-With-rewriting-history]] -Problems with rewriting history -------------------------------- +=== Problems with rewriting history The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into @@ -2747,8 +2674,7 @@ For true distributed development that supports proper merging, published branches should never be rewritten. [[bisect-merges]] -Why bisecting merge commits can be harder than bisecting linear history ------------------------------------------------------------------------ +=== Why bisecting merge commits can be harder than bisecting linear history The linkgit:git-bisect[1] command correctly handles history that includes merge commits. However, when the commit that it finds is a @@ -2813,12 +2739,10 @@ linear by rebasing against the latest upstream version before publishing. [[advanced-branch-management]] -Advanced branch management -========================== +== Advanced branch management [[fetching-individual-branches]] -Fetching individual branches ----------------------------- +=== Fetching individual branches Instead of using linkgit:git-remote[1], you can also choose just to update one branch at a time, and to store it locally under an @@ -2846,8 +2770,7 @@ already have a branch named example-master, it will attempt to master branch. In more detail: [[fetch-fast-forwards]] -git fetch and fast-forwards ---------------------------- +=== git fetch and fast-forwards In the previous example, when updating an existing branch, `git fetch` checks to make sure that the most recent commit on the remote @@ -2884,8 +2807,7 @@ unless you've already created a reference of your own pointing to them. [[forcing-fetch]] -Forcing git fetch to do non-fast-forward updates ------------------------------------------------- +=== Forcing git fetch to do non-fast-forward updates If git fetch fails because the new head of a branch is not a descendant of the old head, you may force the update with: @@ -2905,8 +2827,7 @@ Be aware that commits that the old version of example/master pointed at may be lost, as we saw in the previous section. [[remote-branch-configuration]] -Configuring remote-tracking branches ------------------------------------- +=== Configuring remote-tracking branches We saw above that `origin` is just a shortcut to refer to the repository that you originally cloned from. This information is @@ -2957,8 +2878,7 @@ the refspec syntax. [[git-concepts]] -Git concepts -============ +== Git concepts Git is built on a small number of simple but powerful ideas. While it is possible to get things done without understanding them, you will find @@ -2968,8 +2888,7 @@ We start with the most important, the <<def_object_database,object database>> and the <<def_index,index>>. [[the-object-database]] -The Object Database -------------------- +=== The Object Database We already saw in <<understanding-commits>> that all commits are stored @@ -3013,8 +2932,7 @@ There are four different types of objects: "blob", "tree", "commit", and The object types in some more detail: [[commit-object]] -Commit Object -~~~~~~~~~~~~~ +==== Commit Object The "commit" object links a physical state of a tree with a description of how we got there and why. Use the `--pretty=raw` option to @@ -3066,8 +2984,7 @@ commit whose parent is normally the current HEAD, and whose tree is taken from the content currently stored in the index. [[tree-object]] -Tree Object -~~~~~~~~~~~ +==== Tree Object The ever-versatile linkgit:git-show[1] command can also be used to examine tree objects, but linkgit:git-ls-tree[1] will give you more @@ -3106,8 +3023,7 @@ Note that the files all have mode 644 or 755: Git actually only pays attention to the executable bit. [[blob-object]] -Blob Object -~~~~~~~~~~~ +==== Blob Object You can use linkgit:git-show[1] to examine the contents of a blob; take, for example, the blob in the entry for `COPYING` from the tree above: @@ -3136,8 +3052,7 @@ sometimes be useful for browsing the contents of a tree that is not currently checked out. [[trust]] -Trust -~~~~~ +==== Trust If you receive the SHA-1 name of a blob from one source, and its contents from another (possibly untrusted) source, you can still trust that those @@ -3166,8 +3081,7 @@ like GPG/PGP. To assist in this, Git also provides the tag object... [[tag-object]] -Tag Object -~~~~~~~~~~ +==== Tag Object A tag object contains an object, object type, tag name, the name of the person ("tagger") who created the tag, and a message, which may contain @@ -3196,8 +3110,7 @@ objects. (Note that linkgit:git-tag[1] can also be used to create references whose names begin with `refs/tags/`). [[pack-files]] -How Git stores objects efficiently: pack files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== How Git stores objects efficiently: pack files Newly created objects are initially created in a file named after the object's SHA-1 hash (stored in `.git/objects`). @@ -3255,8 +3168,7 @@ The linkgit:git-gc[1] command performs packing, pruning, and more for you, so is normally the only high-level command you need. [[dangling-objects]] -Dangling objects -~~~~~~~~~~~~~~~~ +==== Dangling objects The linkgit:git-fsck[1] command will sometimes complain about dangling objects. They are not a problem. @@ -3336,8 +3248,7 @@ don't want to do that while the filesystem is mounted. accesses to a repository but you might receive confusing or scary messages.) [[recovering-from-repository-corruption]] -Recovering from repository corruption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Recovering from repository corruption By design, Git treats data trusted to it with caution. However, even in the absence of bugs in Git itself, it is still possible that hardware or @@ -3454,8 +3365,7 @@ whole thing. It's up to you--Git does *have* a lot of information, it is just missing one particular blob version. [[the-index]] -The index ---------- +=== The index The index is a binary file (generally kept in `.git/index`) containing a sorted list of path names, each with permissions and the SHA-1 of a blob @@ -3513,8 +3423,7 @@ If you blow the index away entirely, you generally haven't lost any information as long as you have the name of the tree that it described. [[submodules]] -Submodules -========== +== Submodules Large projects are often composed of smaller, self-contained modules. For example, an embedded Linux distribution's source tree would include every @@ -3668,13 +3577,13 @@ change within the submodule, and then update the superproject to reference the new commit: ------------------------------------------------- -$ git checkout master +$ git switch master ------------------------------------------------- or ------------------------------------------------- -$ git checkout -b fix-up +$ git switch -c fix-up ------------------------------------------------- then @@ -3700,8 +3609,8 @@ $ git push You have to run `git submodule update` after `git pull` if you want to update submodules, too. -Pitfalls with submodules ------------------------- +[[pitfalls-with-submodules]] +=== Pitfalls with submodules Always publish the submodule change before publishing the change to the superproject that references it. If you forget to publish the submodule change, @@ -3770,8 +3679,7 @@ submodule update` will not overwrite them. Instead, you get the usual warning about not being able switch from a dirty branch. [[low-level-operations]] -Low-level Git operations -======================== +== Low-level Git operations Many of the higher-level commands were originally implemented as shell scripts using a smaller core of low-level Git commands. These can still @@ -3779,8 +3687,7 @@ be useful when doing unusual things with Git, or just as a way to understand its inner workings. [[object-manipulation]] -Object access and manipulation ------------------------------- +=== Object access and manipulation The linkgit:git-cat-file[1] command can show the contents of any object, though the higher-level linkgit:git-show[1] is usually more useful. @@ -3797,11 +3704,10 @@ verified by linkgit:git-verify-tag[1], though it is normally simpler to use linkgit:git-tag[1] for both. [[the-workflow]] -The Workflow ------------- +=== The Workflow -High-level operations such as linkgit:git-commit[1], -linkgit:git-checkout[1] and linkgit:git-reset[1] work by moving data +High-level operations such as linkgit:git-commit[1] and +linkgit:git-restore[1] work by moving data between the working tree, the index, and the object database. Git provides low-level operations which perform each of these steps individually. @@ -3813,8 +3719,7 @@ the database or the working directory. Thus there are four main combinations: [[working-directory-to-index]] -working directory -> index -~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== working directory -> index The linkgit:git-update-index[1] command updates the index with information from the working directory. You generally update the @@ -3850,8 +3755,7 @@ The previously introduced linkgit:git-add[1] is just a wrapper for linkgit:git-update-index[1]. [[index-to-object-database]] -index -> object database -~~~~~~~~~~~~~~~~~~~~~~~~ +==== index -> object database You write your current index file to a "tree" object with the program @@ -3866,8 +3770,7 @@ use that tree to re-generate the index at any time by going in the other direction: [[object-database-to-index]] -object database -> index -~~~~~~~~~~~~~~~~~~~~~~~~ +==== object database -> index You read a "tree" file from the object database, and use that to populate (and overwrite--don't do this if your index contains any @@ -3883,8 +3786,7 @@ earlier. However, that is only your 'index' file: your working directory contents have not been modified. [[index-to-working-directory]] -index -> working directory -~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== index -> working directory You update your working directory from the index by "checking out" files. This is not a very common operation, since normally you'd just @@ -3913,8 +3815,7 @@ Finally, there are a few odds and ends which are not purely moving from one representation to the other: [[tying-it-all-together]] -Tying it all together -~~~~~~~~~~~~~~~~~~~~~ +==== Tying it all together To commit a tree you have instantiated with `git write-tree`, you'd create a "commit" object that refers to that tree and the history @@ -3988,8 +3889,7 @@ Here is a picture that illustrates how various pieces fit together: [[examining-the-data]] -Examining the data ------------------- +=== Examining the data You can examine the data represented in the object database and the index with various helper tools. For every object, you can use @@ -4024,8 +3924,7 @@ $ git cat-file commit HEAD to see what the top commit was. [[merging-multiple-trees]] -Merging multiple trees ----------------------- +=== Merging multiple trees Git can help you perform a three-way merge, which can in turn be used for a many-way merge by repeating the merge procedure several @@ -4075,8 +3974,7 @@ index file, and you can just write the result out with [[merging-multiple-trees-2]] -Merging multiple trees, continued ---------------------------------- +=== Merging multiple trees, continued Sadly, many merges aren't trivial. If there are files that have been added, moved or removed, or if both branches have modified the @@ -4146,15 +4044,13 @@ $ git merge-index git-merge-one-file hello.c and that is what higher level `git merge -s resolve` is implemented with. [[hacking-git]] -Hacking Git -=========== +== Hacking Git This chapter covers internal details of the Git implementation which probably only Git developers need to understand. [[object-details]] -Object storage format ---------------------- +=== Object storage format All objects have a statically determined "type" which identifies the format of the object (i.e. how it is used, and how it can refer to other @@ -4184,8 +4080,7 @@ of all objects, and verifies their internal consistency (in addition to just verifying their superficial consistency through the hash). [[birdview-on-the-source-code]] -A birds-eye view of Git's source code -------------------------------------- +=== A birds-eye view of Git's source code It is not always easy for new developers to find their way through Git's source code. This section gives you a little guidance to show where to @@ -4194,7 +4089,7 @@ start. A good place to start is with the contents of the initial commit, with: ---------------------------------------------------- -$ git checkout e83c5163 +$ git switch --detach e83c5163 ---------------------------------------------------- The initial revision lays the foundation for almost everything Git has @@ -4394,25 +4289,22 @@ You see, Git is actually the best tool to find out about the source of Git itself! [[glossary]] -Git Glossary -============ +== Git Glossary [[git-explained]] -Git explained -------------- +=== Git explained include::glossary-content.txt[] [[git-quick-start]] -Appendix A: Git Quick Reference -=============================== +[appendix] +== Git Quick Reference This is a quick summary of the major commands; the previous chapters explain how these work in more detail. [[quick-creating-a-new-repository]] -Creating a new repository -------------------------- +=== Creating a new repository From a tarball: @@ -4433,14 +4325,13 @@ $ cd project ----------------------------------------------- [[managing-branches]] -Managing branches ------------------ +=== Managing branches ----------------------------------------------- -$ git branch # list all local branches in this repo -$ git checkout test # switch working directory to branch "test" -$ git branch new # create branch "new" starting at current HEAD -$ git branch -d new # delete branch "new" +$ git branch # list all local branches in this repo +$ git switch test # switch working directory to branch "test" +$ git branch new # create branch "new" starting at current HEAD +$ git branch -d new # delete branch "new" ----------------------------------------------- Instead of basing a new branch on current HEAD (the default), use: @@ -4456,7 +4347,7 @@ $ git branch new test~10 # ten commits before tip of branch "test" Create and switch to a new branch at the same time: ----------------------------------------------- -$ git checkout -b new v2.6.15 +$ git switch -c new v2.6.15 ----------------------------------------------- Update and examine branches from the repository you cloned from: @@ -4467,7 +4358,7 @@ $ git branch -r # list origin/master origin/next ... -$ git checkout -b masterwork origin/master +$ git switch -c masterwork origin/master ----------------------------------------------- Fetch a branch from a different repository, and give it a new @@ -4498,8 +4389,7 @@ $ git branch -r # list all remote branches [[exploring-history]] -Exploring history ------------------ +=== Exploring history ----------------------------------------------- $ gitk # visualize and browse history @@ -4534,8 +4424,7 @@ $ git bisect bad # if this revision is bad. ----------------------------------------------- [[making-changes]] -Making changes --------------- +=== Making changes Make sure Git knows who to blame: @@ -4565,8 +4454,7 @@ $ git commit -a # use latest content of all tracked files ----------------------------------------------- [[merging]] -Merging -------- +=== Merging ----------------------------------------------- $ git merge test # merge branch "test" into the current branch @@ -4576,8 +4464,7 @@ $ git pull . test # equivalent to git merge test ----------------------------------------------- [[sharing-your-changes]] -Sharing your changes --------------------- +=== Sharing your changes Importing or exporting patches: @@ -4622,8 +4509,7 @@ $ git push example test ----------------------------------------------- [[repository-maintenance]] -Repository maintenance ----------------------- +=== Repository maintenance Check for corruption: @@ -4639,12 +4525,11 @@ $ git gc [[todo]] -Appendix B: Notes and todo list for this manual -=============================================== +[appendix] +== Notes and todo list for this manual [[todo-list]] -Todo list ---------- +=== Todo list This is a work in progress. @@ -4689,5 +4574,5 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. More on recovery from repository corruption. See: - http://marc.info/?l=git&m=117263864820799&w=2 - http://marc.info/?l=git&m=117147855503798&w=2 + https://lore.kernel.org/git/Pine.LNX.4.64.0702272039540.12485@woody.linux-foundation.org/ + https://lore.kernel.org/git/Pine.LNX.4.64.0702141033400.3604@woody.linux-foundation.org/ |