diff options
Diffstat (limited to 'Documentation')
228 files changed, 11463 insertions, 4745 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index c7096f11f1..9022d48355 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -12,3 +12,6 @@ cmds-*.txt 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..32210a4386 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -118,6 +118,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 @@ -358,7 +376,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 @@ -559,11 +580,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 d079d7c73a..dbf5a0f276 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 @@ -30,20 +32,26 @@ MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.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 @@ -73,9 +81,11 @@ TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/index-format TECH_DOCS += technical/long-running-process-protocol +TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/pack-protocol +TECH_DOCS += technical/partial-clone TECH_DOCS += technical/protocol-capabilities TECH_DOCS += technical/protocol-common TECH_DOCS += technical/protocol-v2 @@ -87,11 +97,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 @@ -284,7 +296,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 $@+ $@ @@ -322,6 +334,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 @@ -331,30 +352,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 $@+ $@ @@ -364,7 +386,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 @@ -421,7 +444,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) - >$@+ && \ @@ -455,4 +478,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/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.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.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.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.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.19.0.txt b/Documentation/RelNotes/2.19.0.txt new file mode 100644 index 0000000000..a06ccf6e2a --- /dev/null +++ b/Documentation/RelNotes/2.19.0.txt @@ -0,0 +1,615 @@ +Git 2.19 Release Notes +====================== + +Updates since v2.18 +------------------- + +UI, Workflows & Features + + * "git diff" compares the index and the working tree. For paths + added with intent-to-add bit, the command shows the full contents + of them as added, but the paths themselves were not marked as new + files. They are now shown as new by default. + + "git apply" learned the "--intent-to-add" option so that an + otherwise working-tree-only application of a patch will add new + paths to the index marked with the "intent-to-add" bit. + + * "git grep" learned the "--column" option that gives not just the + line number but the column number of the hit. + + * The "-l" option in "git branch -l" is an unfortunate short-hand for + "--create-reflog", but many users, both old and new, somehow expect + it to be something else, perhaps "--list". This step warns when "-l" + is used as a short-hand for "--create-reflog" and warns about the + future repurposing of the it when it is used. + + * The userdiff pattern for .php has been updated. + + * The content-transfer-encoding of the message "git send-email" sends + out by default was 8bit, which can cause trouble when there is an + overlong line to bust RFC 5322/2822 limit. A new option 'auto' to + automatically switch to quoted-printable when there is such a line + in the payload has been introduced and is made the default. + + * "git checkout" and "git worktree add" learned to honor + checkout.defaultRemote when auto-vivifying a local branch out of a + remote tracking branch in a repository with multiple remotes that + have tracking branches that share the same names. + (merge 8d7b558bae ab/checkout-default-remote later to maint). + + * "git grep" learned the "--only-matching" option. + + * "git rebase --rebase-merges" mode now handles octopus merges as + well. + + * Add a server-side knob to skip commits in exponential/fibbonacci + stride in an attempt to cover wider swath of history with a smaller + number of iterations, potentially accepting a larger packfile + transfer, instead of going back one commit a time during common + ancestor discovery during the "git fetch" transaction. + (merge 42cc7485a2 jt/fetch-negotiator-skipping later to maint). + + * A new configuration variable core.usereplacerefs has been added, + primarily to help server installations that want to ignore the + replace mechanism altogether. + + * Teach "git tag -s" etc. a few configuration variables (gpg.format + that can be set to "openpgp" or "x509", and gpg.<format>.program + that is used to specify what program to use to deal with the format) + to allow x.509 certs with CMS via "gpgsm" to be used instead of + openpgp via "gnupg". + + * Many more strings are prepared for l10n. + + * "git p4 submit" learns to ask its own pre-submit hook if it should + continue with submitting. + + * The test performed at the receiving end of "git push" to prevent + bad objects from entering repository can be customized via + receive.fsck.* configuration variables; we now have gained a + counterpart to do the same on the "git fetch" side, with + fetch.fsck.* configuration variables. + + * "git pull --rebase=interactive" learned "i" as a short-hand for + "interactive". + + * "git instaweb" has been adjusted to run better with newer Apache on + RedHat based distros. + + * "git range-diff" is a reimplementation of "git tbdiff" that lets us + compare individual patches in two iterations of a topic. + + * 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. + + * The bulk of "git submodule foreach" has been rewritten in C. + + * The in-core "commit" object had an all-purpose "void *util" field, + which was tricky to use especially in library-ish part of the + code. All of the existing uses of the field has been migrated to a + more dedicated "commit-slab" mechanism and the field is eliminated. + + * A less often used command "git show-index" has been modernized. + (merge fb3010c31f jk/show-index later to maint). + + * The conversion to pass "the_repository" and then "a_repository" + throughout the object access API continues. + + * Continuing with the idea to programatically 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. + + * Separate "rebase -p" codepath out of "rebase -i" implementation to + slim down the latter and make it easier to manage. + + * Make refspec parsing codepath more robust. + + * Some flaky tests have been fixed. + + * Continuing with the idea to programmatically enumerate various + pieces of data required for command line completion, the codebase + has been taught to enumerate options prefixed with "--no-" to + negate them. + + * Build and test procedure for netrc credential helper (in contrib/) + has been updated. + + * Remove unused function definitions and declarations from ewah + bitmap subsystem. + + * Code preparation to make "git p4" closer to be usable with Python 3. + + * Tighten the API to make it harder to misuse in-tree .gitmodules + file, even though it shares the same syntax with configuration + files, to read random configuration items from it. + + * "git fast-import" has been updated to avoid attempting to create + delta against a zero-byte-long string, which is pointless. + + * The codebase has been updated to compile cleanly with -pedantic + option. + (merge 2b647a05d7 bb/pedantic later to maint). + + * The character display width table has been updated to match the + latest Unicode standard. + (merge 570951eea2 bb/unicode-11-width later to maint). + + * test-lint now looks for broken use of "VAR=VAL shell_func" in test + scripts. + + * Conversion from uchar[40] to struct object_id continues. + + * Recent "security fix" to pay attention to contents of ".gitmodules" + while accepting "git push" was a bit overly strict than necessary, + which has been adjusted. + + * "git fsck" learns to make sure the optional commit-graph file is in + a sane state. + + * "git diff --color-moved" feature has further been tweaked. + + * Code restructuring and a small fix to transport protocol v2 during + fetching. + + * Parsing of -L[<N>][,[<M>]] parameters "git blame" and "git log" + take has been tweaked. + + * lookup_commit_reference() and friends have been updated to find + in-core object for a specific in-core repository instance. + + * Various glitches in the heuristics of merge-recursive strategy have + been documented in new tests. + + * "git fetch" learned a new option "--negotiation-tip" to limit the + set of commits it tells the other end as "have", to reduce wasted + bandwidth and cycles, which would be helpful when the receiving + repository has a lot of refs that have little to do with the + history at the remote it is fetching from. + + * For a large tree, the index needs to hold many cache entries + allocated on heap. These cache entries are now allocated out of a + dedicated memory pool to amortize malloc(3) overhead. + + * Tests to cover various conflicting cases have been added for + merge-recursive. + + * Tests to cover conflict cases that involve submodules have been + added for merge-recursive. + + * Look for broken "&&" chains that are hidden in subshell, many of + which have been found and corrected. + + * The singleton commit-graph in-core instance is made per in-core + repository instance. + + * "make DEVELOPER=1 DEVOPTS=pedantic" allows developers to compile + with -pedantic option, which may catch more problematic program + constructs and potential bugs. + + * Preparatory code to later add json output for telemetry data has + been added. + + * Update the way we use Coccinelle to find out-of-style code that + need to be modernised. + + * It is too easy to misuse system API functions such as strcat(); + these selected functions are now forbidden in this codebase and + will cause a compilation failure. + + * Add a script (in contrib/) to help users of VSCode work better with + our codebase. + + * The Travis CI scripts were taught to ship back the test data from + failed tests. + (merge aea8879a6a sg/travis-retrieve-trash-upon-failure later to maint). + + * The parse-options machinery learned to refrain from enclosing + placeholder string inside a "<bra" and "ket>" pair automatically + without PARSE_OPT_LITERAL_ARGHELP. Existing help text for option + arguments that are not formatted correctly have been identified and + fixed. + (merge 5f0df44cd7 rs/parse-opt-lithelp later to maint). + + * Noiseword "extern" has been removed from function decls in the + header files. + + * A few atoms like %(objecttype) and %(objectsize) in the format + specifier of "for-each-ref --format=<format>" can be filled without + getting the full contents of the object, but just with the object + header. These cases have been optimized by calling + oid_object_info() API (instead of reading and inspecting the data). + + * The end result of documentation update has been made to be + inspected more easily to help developers. + + * The API to iterate over all objects learned to optionally list + objects in the order they appear in packfiles, which helps locality + of access if the caller accesses these objects while as objects are + enumerated. + + * Improve built-in facility to catch broken &&-chain in the tests. + + * The more library-ish parts of the codebase learned to work on the + in-core index-state instance that is passed in by their callers, + instead of always working on the singleton "the_index" instance. + + * A test prerequisite defined by various test scripts with slightly + different semantics has been consolidated into a single copy and + made into a lazily defined one. + (merge 6ec633059a wc/make-funnynames-shared-lazy-prereq later to maint). + + * After a partial clone, repeated fetches from promisor remote would + have accumulated many packfiles marked with .promisor bit without + 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 +----------------- + + * "git remote update" can take both a single remote nickname and a + nickname for remote groups, and the completion script (in contrib/) + has been taught about it. + (merge 9cd4382ad5 ls/complete-remote-update-names later to maint). + + * "git fetch --shallow-since=<cutoff>" that specifies the cut-off + point that is newer than the existing history used to end up + grabbing the entire history. Such a request now errors out. + (merge e34de73c56 nd/reject-empty-shallow-request later to maint). + + * Fix for 2.17-era regression around `core.safecrlf`. + (merge 6cb09125be as/safecrlf-quiet-fix later to maint). + + * The recent addition of "partial clone" experimental feature kicked + in when it shouldn't, namely, when there is no partial-clone filter + defined even if extensions.partialclone is set. + (merge cac1137dc4 jh/partial-clone later to maint). + + * "git send-pack --signed" (hence "git push --signed" over the http + transport) did not read user ident from the config mechanism to + determine whom to sign the push certificate as, which has been + corrected. + (merge d067d98887 ms/send-pack-honor-config later to maint). + + * "git fetch-pack --all" used to unnecessarily fail upon seeing an + annotated tag that points at an object other than a commit. + (merge c12c9df527 jk/fetch-all-peeled-fix later to maint). + + * When user edits the patch in "git add -p" and the user's editor is + set to strip trailing whitespaces indiscriminately, an empty line + that is unchanged in the patch would become completely empty + (instead of a line with a sole SP on it). The code introduced in + Git 2.17 timeframe failed to parse such a patch, but now it learned + to notice the situation and cope with it. + (merge f4d35a6b49 pw/add-p-recount later to maint). + + * The code to try seeing if a fetch is necessary in a submodule + during a fetch with --recurse-submodules got confused when the path + to the submodule was changed in the range of commits in the + superproject, sometimes showing "(null)". This has been corrected. + + * Bugfix for "rebase -i" corner case regression. + (merge a9279c6785 pw/rebase-i-keep-reword-after-conflict later to maint). + + * Recently added "--base" option to "git format-patch" command did + not correctly generate prereq patch ids. + (merge 15b76c1fb3 xy/format-patch-prereq-patch-id-fix later to maint). + + * POSIX portability fix in Makefile to fix a glitch introduced a few + releases ago. + (merge 6600054e9b dj/runtime-prefix later to maint). + + * "git filter-branch" when used with the "--state-branch" option + still attempted to rewrite the commits whose filtered result is + known from the previous attempt (which is recorded on the state + branch); the command has been corrected not to waste cycles doing + so. + (merge 709cfe848a mb/filter-branch-optim later to maint). + + * Clarify that setting core.ignoreCase to deviate from reality would + not turn a case-incapable filesystem into a case-capable one. + (merge 48294b512a ms/core-icase-doc later to maint). + + * "fsck.skipList" did not prevent a blob object listed there from + being inspected for is contents (e.g. we recently started to + inspect the contents of ".gitmodules" for certain malicious + patterns), which has been corrected. + (merge fb16287719 rj/submodule-fsck-skip later to maint). + + * "git checkout --recurse-submodules another-branch" did not report + in which submodule it failed to update the working tree, which + resulted in an unhelpful error message. + (merge ba95d4e4bd sb/submodule-move-head-error-msg later to maint). + + * "git rebase" behaved slightly differently depending on which one of + the three backends gets used; this has been documented and an + effort to make them more uniform has begun. + (merge b00bf1c9a8 en/rebase-consistency later to maint). + + * The "--ignore-case" option of "git for-each-ref" (and its friends) + did not work correctly, which has been fixed. + (merge e674eb2528 jk/for-each-ref-icase later to maint). + + * "git fetch" failed to correctly validate the set of objects it + received when making a shallow history deeper, which has been + corrected. + (merge cf1e7c0770 jt/connectivity-check-after-unshallow later to maint). + + * Partial clone support of "git clone" has been updated to correctly + validate the objects it receives from the other side. The server + side has been corrected to send objects that are directly + requested, even if they may match the filtering criteria (e.g. when + doing a "lazy blob" partial clone). + (merge a7e67c11b8 jt/partial-clone-fsck-connectivity later to maint). + + * Handling of an empty range by "git cherry-pick" was inconsistent + depending on how the range ended up to be empty, which has been + corrected. + (merge c5e358d073 jk/empty-pick-fix later to maint). + + * "git reset --merge" (hence "git merge ---abort") and "git reset --hard" + had trouble working correctly in a sparsely checked out working + tree after a conflict, which has been corrected. + (merge b33fdfc34c mk/merge-in-sparse-checkout later to maint). + + * Correct a broken use of "VAR=VAL shell_func" in a test. + (merge 650161a277 jc/t3404-one-shot-export-fix later to maint). + + * "git rev-parse ':/substring'" did not consider the history leading + only to HEAD when looking for a commit with the given substring, + when the HEAD is detached. This has been fixed. + (merge 6b3351e799 wc/find-commit-with-pattern-on-detached-head later to maint). + + * Build doc update for Windows. + (merge ede8d89bb1 nd/command-list later to maint). + + * core.commentchar is now honored when preparing the list of commits + to replay in "rebase -i". + + * "git pull --rebase" on a corrupt HEAD caused a segfault. In + general we substitute an empty tree object when running the in-core + equivalent of the diff-index command, and the codepath has been + corrected to do so as well to fix this issue. + (merge 3506dc9445 jk/has-uncommitted-changes-fix later to maint). + + * httpd tests saw occasional breakage due to the way its access log + gets inspected by the tests, which has been updated to make them + less flaky. + (merge e8b3b2e275 sg/httpd-test-unflake later to maint). + + * Tests to cover more D/F conflict cases have been added for + merge-recursive. + + * "git gc --auto" opens file descriptors for the packfiles before + spawning "git repack/prune", which would upset Windows that does + not want a process to work on a file that is open by another + process. The issue has been worked around. + (merge 12e73a3ce4 kg/gc-auto-windows-workaround later to maint). + + * The recursive merge strategy did not properly ensure there was no + change between HEAD and the index before performing its operation, + which has been corrected. + (merge 55f39cf755 en/dirty-merge-fixes later to maint). + + * "git rebase" started exporting GIT_DIR environment variable and + exposing it to hook scripts when part of it got rewritten in C. + Instead of matching the old scripted Porcelains' behaviour, + compensate by also exporting GIT_WORK_TREE environment as well to + lessen the damage. This can harm existing hooks that want to + operate on different repository, but the current behaviour is + already broken for them anyway. + (merge ab5e67d751 bc/sequencer-export-work-tree-as-well later to maint). + + * "git send-email" when using in a batched mode that limits the + number of messages sent in a single SMTP session lost the contents + of the variable used to choose between tls/ssl, unable to send the + second and later batches, which has been fixed. + (merge 636f3d7ac5 jm/send-email-tls-auth-on-batch later to maint). + + * The lazy clone support had a few places where missing but promised + objects were not correctly tolerated, which have been fixed. + + * One of the "diff --color-moved" mode "dimmed_zebra" that was named + in an unusual way has been deprecated and replaced by + "dimmed-zebra". + (merge e3f2f5f9cd es/diff-color-moved-fix later to maint). + + * The wire-protocol v2 relies on the client to send "ref prefixes" to + limit the bandwidth spent on the initial ref advertisement. "git + clone" when learned to speak v2 forgot to do so, which has been + corrected. + (merge 402c47d939 bw/clone-ref-prefixes later to maint). + + * "git diff --histogram" had a bad memory usage pattern, which has + been rearranged to reduce the peak usage. + (merge 79cb2ebb92 sb/histogram-less-memory later to maint). + + * Code clean-up to use size_t/ssize_t when they are the right type. + (merge 7726d360b5 jk/size-t later to maint). + + * The wire-protocol v2 relies on the client to send "ref prefixes" to + limit the bandwidth spent on the initial ref advertisement. "git + fetch $remote branch:branch" that asks tags that point into the + history leading to the "branch" automatically followed sent to + narrow prefix and broke the tag following, which has been fixed. + (merge 2b554353a5 jt/tag-following-with-proto-v2-fix later to maint). + + * When the sparse checkout feature is in use, "git cherry-pick" and + other mergy operations lost the skip_worktree bit when a path that + is excluded from checkout requires content level merge, which is + resolved as the same as the HEAD version, without materializing the + merge result in the working tree, which made the path appear as + deleted. This has been corrected by preserving the skip_worktree + bit (and not materializing the file in the working tree). + (merge 2b75fb601c en/merge-recursive-skip-fix later to maint). + + * The "author-script" file "git rebase -i" creates got broken when + we started to move the command away from shell script, which is + getting fixed now. + (merge 5522bbac20 es/rebase-i-author-script-fix later to maint). + + * The automatic tree-matching in "git merge -s subtree" was broken 5 + years ago and nobody has noticed since then, which is now fixed. + (merge 2ec4150713 jk/merge-subtree-heuristics later to maint). + + * "git fetch $there refs/heads/s" ought to fetch the tip of the + branch 's', but when "refs/heads/refs/heads/s", i.e. a branch whose + name is "refs/heads/s" exists at the same time, fetched that one + instead by mistake. This has been corrected to honor the usual + disambiguation rules for abbreviated refnames. + (merge 60650a48c0 jt/refspec-dwim-precedence-fix later to maint). + + * Futureproofing a helper function that can easily be misused. + (merge 65bb21e77e es/want-color-fd-defensive later to maint). + + * The http-backend (used for smart-http transport) used to slurp the + whole input until EOF, without paying attention to CONTENT_LENGTH + that is supplied in the environment and instead expecting the Web + server to close the input stream. This has been fixed. + (merge eebfe40962 mk/http-backend-content-length later to maint). + + * "git merge --abort" etc. did not clean things up properly when + there were conflicted entries in the index in certain order that + are involved in D/F conflicts. This has been corrected. + (merge ad3762042a en/abort-df-conflict-fixes later to maint). + + * "git diff --indent-heuristic" had a bad corner case performance. + (merge 301ef85401 sb/indent-heuristic-optim later to maint). + + * The "--exec" option to "git rebase --rebase-merges" placed the exec + commands at wrong places, which has been corrected. + + * "git verify-tag" and "git verify-commit" have been taught to use + the exit status of underlying "gpg --verify" to signal bad or + untrusted signature they found. + (merge 4e5dc9ca17 jc/gpg-status later to maint). + + * "git mergetool" stopped and gave an extra prompt to continue after + the last path has been handled, which did not make much sense. + (merge d651a54b8a ng/mergetool-lose-final-prompt later to maint). + + * Among the three codepaths we use O_APPEND to open a file for + appending, one used for writing GIT_TRACE output requires O_APPEND + implementation that behaves sensibly when multiple processes are + writing to the same file. POSIX emulation used in the Windows port + has been updated to improve in this area. + (merge d641097589 js/mingw-o-append later to maint). + + * "git pull --rebase -v" in a repository with a submodule barfed as + an intermediate process did not understand what "-v(erbose)" flag + meant, which has been fixed. + (merge e84c3cf3dc sb/pull-rebase-submodule later to maint). + + * Recent update to "git config" broke updating variable in a + subsection, which has been corrected. + (merge bff7df7a87 sb/config-write-fix later to maint). + + * When "git rebase -i" is told to squash two or more commits into + one, it labeled the log message for each commit with its number. + It correctly called the first one "1st commit", but the next one + was "commit #1", which was off-by-one. This has been corrected. + (merge dd2e36ebac pw/rebase-i-squash-number-fix later to maint). + + * "git rebase -i", when a 'merge <branch>' insn in its todo list + fails, segfaulted, which has been (minimally) corrected. + (merge bc9238bb09 pw/rebase-i-merge-segv-fix later to maint). + + * "git cherry-pick --quit" failed to remove CHERRY_PICK_HEAD even + though we won't be in a cherry-pick session after it returns, which + 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). + (merge 5b26c3c941 en/merge-recursive-cleanup later to maint). + (merge 0dcbc0392e bw/config-refer-to-gitsubmodules-doc later to maint). + (merge bb4d000e87 bw/protocol-v2 later to maint). + (merge 928f0ab4ba vs/typofixes later to maint). + (merge d7f590be84 en/rebase-i-microfixes later to maint). + (merge 81d395cc85 js/rebase-recreate-merge later to maint). + (merge 51d1863168 tz/exclude-doc-smallfixes later to maint). + (merge a9aa3c0927 ds/commit-graph later to maint). + (merge 5cf8e06474 js/enhanced-version-info later to maint). + (merge 6aaded5509 tb/config-default later to maint). + (merge 022d2ac1f3 sb/blame-color later to maint). + (merge 5a06a20e0c bp/test-drop-caches-for-windows later to maint). + (merge dd61cc1c2e jk/ui-color-always-to-auto later to maint). + (merge 1e83b9bfdd sb/trailers-docfix later to maint). + (merge ab29f1b329 sg/fast-import-dump-refs-on-checkpoint-fix later to maint). + (merge 6a8ad880f0 jn/subtree-test-fixes later to maint). + (merge ffbd51cc60 nd/pack-objects-threading-doc later to maint). + (merge e9dac7be60 es/mw-to-git-chain-fix later to maint). + (merge fe583c6c7a rs/remote-mv-leakfix later to maint). + (merge 69885ab015 en/t3031-title-fix later to maint). + (merge 8578037bed nd/config-blame-sort later to maint). + (merge 8ad169c4ba hn/config-in-code-comment later to maint). + (merge b7446fcfdf ar/t4150-am-scissors-test-fix later to maint). + (merge a8132410ee js/typofixes later to maint). + (merge 388d0ff6e5 en/update-index-doc later to maint). + (merge e05aa688dd jc/update-index-doc later to maint). + (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.20.0.txt b/Documentation/RelNotes/2.20.0.txt new file mode 100644 index 0000000000..e71fe3dee1 --- /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 crufts" 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.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.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/SubmittingPatches b/Documentation/SubmittingPatches index 2488544407..6d589e118c 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 @@ -298,7 +300,7 @@ smaller project it is a good discipline to follow it. The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have -the right to pass it on as a open-source patch. The rules are +the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below D-C-O: [[dco]] @@ -370,15 +372,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 Pat Thoyts: git://repo.or.cz/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/ @@ -403,7 +405,7 @@ don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would help you find out who they are. . You get comments and suggestions for improvements. You may - even get them in a "on top of your change" patch form. + even get them in an "on top of your change" patch form. . Polish, refine, and re-send to the list and the people who spend their time to improve your patch. Go back to step (2). diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index ec83b4959e..0089e0cfb8 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -11,12 +11,12 @@ module Git 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) + %(<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 diff --git a/Documentation/config.txt b/Documentation/config.txt index ab641bf5a9..7e2a6f61f5 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2,8 +2,9 @@ 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 +the Git commands' behavior. The files `.git/config` and optionally +`config.worktree` (see `extensions.worktreeConfig` below) 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. @@ -225,7 +226,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). @@ -287,3301 +288,154 @@ 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. - 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 an 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:: - If true, this option enables various workarounds to enable - Git to work better on filesystems that are not case sensitive, - like FAT. 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. - -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]. - -core.commitGraph:: - Enable git commit graph feature. Allows reading from the - commit-graph file. - -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.showRoot:: - Do not treat root commits as boundaries in linkgit:git-blame[1]. - This option defaults to false. - -blame.blankBoundary:: - Show blank commit object name for boundary commits in - linkgit:git-blame[1]. This option defaults to false. - -blame.showEmail:: - Show the author email instead of author name in linkgit:git-blame[1]. - This option defaults to false. - -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]. - -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]). - -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.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. - -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` - and `newMovedAlternativeDimmed` (See the '<mode>' - setting of '--color-moved' in linkgit:git-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. - -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`) -`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.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.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.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. - -blame.coloring:: - This determines the coloring scheme to be applied to blame - output. It can be 'repeatedLines', 'highlightRecent', - or 'none' which is the default. - -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. It will abort in the case of a malformed object or a - broken link. The result of an abort are only dangling objects. - Defaults to false. If not set, the value of `transfer.fsckObjects` - is used instead. - -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. - -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>:: - Allows overriding the message type (error, warn or ignore) of a - specific message ID such as `missingEmail`. -+ -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. -+ -This feature is intended to support working with legacy repositories -which cannot be repaired without disruptive changes. - -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. - -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.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. - -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. It will abort in the case of a malformed object or a - broken link. The result of an abort are only dangling objects. - Defaults to false. If not set, the value of `transfer.fsckObjects` - is used instead. - -receive.fsck.<msg-id>:: - When `receive.fsckObjects` is set to true, errors can be switched - to warnings and vice versa by configuring the `receive.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 - `receive.fsck.missingEmail = ignore` will hide that issue. -+ -This feature is intended to support working with legacy repositories -which would not pass pushing when `receive.fsckObjects = true`, allowing -the host to accept repositories with certain known issues but still catch -other issues. - -receive.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. - -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. - -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. - -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. - -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). - -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/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/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..4d753f006e --- /dev/null +++ b/Documentation/config/add.txt @@ -0,0 +1,7 @@ +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. diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt new file mode 100644 index 0000000000..ec4f6ae658 --- /dev/null +++ b/Documentation/config/advice.txt @@ -0,0 +1,95 @@ +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. + 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. + 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. + 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. + 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. + nestedTag:: + Advice shown if a user attempts to recursively tag a tag object. +-- diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt new file mode 100644 index 0000000000..0b14178314 --- /dev/null +++ b/Documentation/config/alias.txt @@ -0,0 +1,18 @@ +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]. 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..67b5c1d1e0 --- /dev/null +++ b/Documentation/config/blame.txt @@ -0,0 +1,21 @@ +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. diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt new file mode 100644 index 0000000000..8f4b3faadd --- /dev/null +++ b/Documentation/config/branch.txt @@ -0,0 +1,102 @@ +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.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`, 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` (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`, 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..c4118fa196 --- /dev/null +++ b/Documentation/config/checkout.txt @@ -0,0 +1,23 @@ +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. + +checkout.optimizeNewBranch:: + Optimizes the performance of "git checkout -b <new_branch>" when + using sparse-checkout. When set to true, git will not update the + repo based on the current sparse-checkout settings. This means it + will not update the skip-worktree bit in the index nor add/remove + files in the working directory to reflect the current sparse checkout + settings nor will it show the local changes. 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..8375596c44 --- /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 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..75538d27e7 --- /dev/null +++ b/Documentation/config/core.txt @@ -0,0 +1,603 @@ +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:: + 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.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 false. 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 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. diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt new file mode 100644 index 0000000000..60fb3189e1 --- /dev/null +++ b/Documentation/config/credential.txt @@ -0,0 +1,26 @@ +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. diff --git a/Documentation/diff-config.txt b/Documentation/config/diff.txt index 77caa66c2f..2c4c9ba27a 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,7 +73,7 @@ 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 @@ -177,7 +177,15 @@ 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 @@ -208,3 +216,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/fetch.txt b/Documentation/config/fetch.txt new file mode 100644 index 0000000000..cbfad6cdbb --- /dev/null +++ b/Documentation/config/fetch.txt @@ -0,0 +1,65 @@ +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]. 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..dc77941c48 --- /dev/null +++ b/Documentation/config/format.txt @@ -0,0 +1,87 @@ +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. 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..02b92b18b5 --- /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 false. 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..f999f8ea49 --- /dev/null +++ b/Documentation/config/gpg.txt @@ -0,0 +1,20 @@ +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". 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..5a32f5b0a5 --- /dev/null +++ b/Documentation/config/http.txt @@ -0,0 +1,280 @@ +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.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. Actually 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. Actually 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. + +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..f181503041 --- /dev/null +++ b/Documentation/config/index.txt @@ -0,0 +1,26 @@ +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. 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..ad846dd7c9 --- /dev/null +++ b/Documentation/config/interactive.txt @@ -0,0 +1,16 @@ +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). diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt new file mode 100644 index 0000000000..78d9e4453a --- /dev/null +++ b/Documentation/config/log.txt @@ -0,0 +1,43 @@ +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`. 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..6a313937f8 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 @@ -63,7 +76,13 @@ merge.tool:: 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..9cdcfa7324 --- /dev/null +++ b/Documentation/config/pack.txt @@ -0,0 +1,127 @@ +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.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. + +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..bfccc07491 --- /dev/null +++ b/Documentation/config/protocol.txt @@ -0,0 +1,64 @@ +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:: + 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. + +* `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..b87cab31b3 --- /dev/null +++ b/Documentation/config/pull.txt @@ -0,0 +1,36 @@ +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` (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`, 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..0a0e000569 --- /dev/null +++ b/Documentation/config/push.txt @@ -0,0 +1,113 @@ +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: ++ +-- + +* `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. + +* `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'. diff --git a/Documentation/rebase-config.txt b/Documentation/config/rebase.txt index 42e1ba7575..d98e32d812 100644 --- a/Documentation/rebase-config.txt +++ b/Documentation/config/rebase.txt @@ -1,3 +1,10 @@ +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.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. @@ -50,3 +57,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..6c4cad83a2 --- /dev/null +++ b/Documentation/config/remote.txt @@ -0,0 +1,78 @@ +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]. 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..7710758efb --- /dev/null +++ b/Documentation/config/stash.txt @@ -0,0 +1,24 @@ +stash.useBuiltin:: + Set to `false` to use the legacy shell script implementation of + linkgit:git-stash[1]. Is `true` by default, which means use + the built-in rewrite of it in C. ++ +The C rewrite is first included with Git version 2.22 (and Git for Windows +version 2.19). This option serves an an escape hatch to re-enable the +legacy version in case any bugs are found in the rewrite. This option and +the shell script version of linkgit:git-stash[1] will be removed in some +future release. ++ +If you find some reason to set this option to `false`, other than +one-off testing, you should report the behavior difference as a bug in +Git (see https://git-scm.com/community for details). + +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..ed72fa7dae --- /dev/null +++ b/Documentation/config/status.txt @@ -0,0 +1,72 @@ +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. diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt new file mode 100644 index 0000000000..0a1293b051 --- /dev/null +++ b/Documentation/config/submodule.txt @@ -0,0 +1,82 @@ +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`. diff --git a/Documentation/config/tag.txt b/Documentation/config/tag.txt new file mode 100644 index 0000000000..663663bdec --- /dev/null +++ b/Documentation/config/tag.txt @@ -0,0 +1,16 @@ +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]. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt new file mode 100644 index 0000000000..2edbfb02fe --- /dev/null +++ b/Documentation/config/trace2.txt @@ -0,0 +1,56 @@ +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.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. diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt new file mode 100644 index 0000000000..4a5dfe2fc1 --- /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 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. 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..0557cbbceb --- /dev/null +++ b/Documentation/config/user.txt @@ -0,0 +1,33 @@ +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. + See linkgit:git-commit-tree[1] for more information. + +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/diff-format.txt b/Documentation/diff-format.txt index 706916c94c..4d846d7346 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: @@ -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..f10ca410ad 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -143,6 +143,19 @@ 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 diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 41064909ee..09faee3b44 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. @@ -276,17 +293,58 @@ plain:: that are added somewhere else in the diff. This mode picks up any moved line, but it is not very useful in a review to determine if a block of code was moved without permutation. -zebra:: +blocks:: Blocks of moved text of at least 20 alphanumeric characters are detected greedily. The detected blocks are - painted using either the 'color.diff.{old,new}Moved' color or + painted using either the 'color.diff.{old,new}Moved' color. + Adjacent blocks cannot be told apart. +zebra:: + Blocks of moved text are detected as in 'blocks' mode. The blocks + are painted using either the 'color.diff.{old,new}Moved' color or 'color.diff.{old,new}MovedAlternative'. The change between the two colors indicates that a new block was detected. -dimmed_zebra:: +dimmed-zebra:: Similar to 'zebra', but additional dimming of uninteresting parts of moved code is performed. The bordering lines of two adjacent blocks are considered interesting, the rest is uninteresting. + `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 whitespace is ignored when performing the + move detection for `--color-moved`. +ifdef::git-diff[] + It can be set by the `diff.colorMovedWS` configuration setting. +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:: + Ignore changes in amount of whitespace. This ignores whitespace + at line end, and considers all other sequences of one or + more whitespace characters to be equivalent. +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 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. @@ -345,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. @@ -375,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 @@ -494,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 @@ -513,6 +576,9 @@ While `git log -G"regexec\(regexp"` will show this commit, `git log -S"regexec\(regexp" --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 new file mode 100755 index 0000000000..3355be4798 --- /dev/null +++ b/Documentation/doc-diff @@ -0,0 +1,187 @@ +#!/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 +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-header-footer cut away header and footer +" +SUBDIRECTORY_OK=1 +. "$(git --exec-path)/git-sh-setup" + +parallel= +force= +clean= +from_program= +to_program= +cut_header_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-header-footer) + cut_header_footer=-cut-header-footer ;; + --) + shift; break ;; + *) + usage ;; + esac + 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) + if test $? != 0 || test -z "$parallel" + then + parallel=1 + fi +fi + +test $# -gt 1 || usage +from=$1; shift +to=$1; shift + +from_oid=$(git rev-parse --verify "$from") || exit 1 +to_oid=$(git rev-parse --verify "$to") || exit 1 + +if test -n "$force" +then + rm -rf "$tmp" +fi + +# We'll do both builds in a single worktree, which lets "make" reuse +# results that don't differ between the two trees. +if ! test -d "$tmp/worktree" +then + 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_header_footer && +to_dir=$to_oid$to_program$cut_header_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 '%s: %s\n' "$dst" "$src" + printf '\t@echo >&2 " RENDER $(notdir $@)" && \\\n' + printf '\tmkdir -p $(dir $@) && \\\n' + printf '\tMANWIDTH=80 man $< >$@+ && \\\n' + printf '\tmv $@+ $@\n' + done +} + +# 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 + # copies the files (spending effort, but also updating timestamps that + # 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. + oid=$1 && + dname=$2 && + makemanflags=$3 && + if ! test -d "$tmp/installed/$dname" + then + git -C "$tmp/worktree" checkout --detach "$oid" && + make -j$parallel -C "$tmp/worktree" \ + $makemanflags \ + GIT_VERSION=omitted \ + SOURCE_DATE_EPOCH=0 \ + DESTDIR="$tmp/installed/$dname+" \ + install-man && + 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/$dname" + then + generate_render_makefile "$tmp/installed/$dname" \ + "$tmp/rendered/$dname+" | + make -j$parallel -f - && + mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname" + + if test "$cut_header_footer" = "-cut-header-footer" + then + for f in $(find "$tmp/rendered/$dname" -type f) + do + tail -n +3 "$f" | head -n -2 | + sed -e '1{/^$/d}' -e '${/^$/d}' >"$f+" && + mv "$f+" "$f" || + return 1 + done + fi + fi +} + +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 97d3217df9..91c47752ec 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -42,6 +42,25 @@ the current repository has the same history as the source repository. .git/shallow. This option updates .git/shallow and accept such refs. +--negotiation-tip=<commit|glob>:: + By default, Git will report, to the server, commits reachable + from all local refs to find common commits in an attempt to + reduce the size of the to-be-received packfile. If specified, + Git will only report commits reachable from the given tips. + This is useful to speed up fetches when the user knows which + local ref is likely to have commits in common with the + upstream ref being fetched. ++ +This option may be specified more than once; if so, Git will report +commits reachable from any of the given commits. ++ +The argument to this option may be a glob on ref names, a ref, or the (possibly +abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying +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. @@ -49,11 +68,16 @@ 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:: @@ -192,7 +216,8 @@ 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. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 45652fe4a6..8b0e4c7fa8 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -58,9 +58,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 +124,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 @@ -193,20 +193,11 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. 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..fc3b993c33 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -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>:: diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 67228494c0..b9aa39000f 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -9,7 +9,7 @@ git-apply - Apply a patch to files and/or to the index SYNOPSIS -------- [verse] -'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way] +'git apply' [--stat] [--numstat] [--summary] [--check] [--index | --intent-to-add] [--3way] [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] @@ -74,6 +74,14 @@ OPTIONS cached data, apply the patch, and store the result in the index without using the working tree. This implies `--index`. +--intent-to-add:: + When applying the patch only to the working tree, mark new + files to be added to the index later (see `--intent-to-add` + option in linkgit:git-add[1]). This option is ignored unless + running in a Git repository and `--index` is not specified. + Note that `--index` could be implied by other options such + as `--cached` or `--3way`. + -3:: --3way:: When the patch does not apply cleanly, fall back on 3-way merge if 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 78479b003e..e99925184d 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -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" @@ -1103,7 +1103,7 @@ _____________ Combining test suites, git bisect and other systems together ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We have seen that test suites an git bisect are very powerful when +We have seen that test suites and git bisect are very powerful when used together. It can be even more powerful if you can combine them with other systems. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 02eccbb931..6ebd512b4f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -9,12 +9,12 @@ SYNOPSIS -------- [verse] 'git branch' [--color[=<when>] | --no-color] [-r | -a] - [--list] [-v [--abbrev=<length> | --no-abbrev]] + [--list] [--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>] +'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> @@ -45,7 +45,11 @@ 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 @@ -91,7 +95,6 @@ OPTIONS -D:: Shortcut for `--delete --force`. --l:: --create-reflog:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date @@ -155,14 +158,15 @@ This option is only applicable in non-verbose mode. --all:: List both remote-tracking branches and local branches. +-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:: @@ -267,10 +271,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>:: @@ -300,7 +305,7 @@ $ git checkout 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:: + @@ -312,10 +317,10 @@ $ 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. NOTES diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index f90f09b03f..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:: @@ -104,6 +104,16 @@ OPTIONS buffering; this is much more efficient when invoking `--batch-check` on a large number of objects. +--unordered:: + When `--batch-all-objects` is in use, visit objects in an + order which may be more efficient for accessing the object + contents than hash order. The exact details of the order are + unspecified, but if you do not require a specific order, this + should generally result in faster output, especially with + `--batch`. Note that `cat-file` will still show each object + only once, even if it is stored multiple times in the + repository. + --allow-unknown-type:: Allow -s or -t to query broken/corrupt objects of unknown type. @@ -242,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-checkout.txt b/Documentation/git-checkout.txt index ca5fc9c798..964f912d29 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -38,6 +38,15 @@ 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 "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, @@ -233,6 +242,8 @@ 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 @@ -251,6 +262,9 @@ the conflicted merge in the specified paths. 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 +`--[no-]overlay`), and currently doesn't support overlay mode. --ignore-other-worktrees:: `git checkout` refuses when the wanted ref is already checked @@ -267,6 +281,17 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. Just like linkgit:git-submodule[1], this will detach the submodules HEAD. +--no-guess:: + Do not attempt to create a branch if a remote tracking branch + of the same name exists. + +--[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. + <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 @@ -276,7 +301,7 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. + 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 merge base of `A` and `B` if there is exactly one merge base. You can @@ -288,6 +313,10 @@ 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. ++ +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, @@ -302,9 +331,9 @@ 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: ------------ - HEAD (refers to branch 'master') - | - v + HEAD (refers to branch 'master') + | + v a---b---c branch 'master' (refers to commit 'c') ^ | @@ -320,9 +349,9 @@ 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') ^ | @@ -389,7 +418,7 @@ 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') @@ -411,14 +440,14 @@ $ 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. + 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. + but leaves HEAD detached. <3> creates a new tag 'foo', which refers to commit 'f', -leaving HEAD detached. + leaving HEAD detached. 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 @@ -446,8 +475,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> @@ -481,7 +510,7 @@ $ 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 @@ -509,7 +538,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 diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index d35d771fc8..754b16ce0c 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -57,6 +57,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 @@ -148,6 +155,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 +225,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..db876f7dde 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -55,14 +55,13 @@ 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 working directory to test a clean build. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index a55536f0bf..a0f14b51f2 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -131,6 +131,14 @@ objects from the source repository into a pack in the cloned repository. is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. +--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. + --no-checkout:: -n:: No checkout of HEAD is performed after the clone is complete. @@ -189,6 +197,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 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 4c97b555cc..624470e198 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -3,80 +3,91 @@ 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>] 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 at `<dir>/info/commit-graph` and + the packfiles are expected to be in `<dir>/pack`. 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 -with --stdin-commits.) +with `--stdin-commits` or `--reachable`.) + With the `--stdin-commits` option, generate the new commit graph by walking commits starting at the commits specified in stdin as a list of OIDs in hex, one OID per line. (Cannot be combined with ---stdin-packs.) +`--stdin-packs` or `--reachable`.) ++ +With the `--reachable` option, generate the new commit graph by walking +commits starting at all refs. (Cannot be combined with `--stdin-commits` +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. +Read the commit-graph file and output basic details about it. +Used for debugging purposes. + +'verify':: + +Read the commit-graph file and verify its contents against the object +database. Used to check for corrupted data. 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 diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 002dae625e..4b90b9c12a 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,7 +56,8 @@ 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>]:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index f970a43422..a85c2c2a4c 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -17,16 +17,20 @@ SYNOPSIS 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 diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 18ddc78f42..ff9310f958 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -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 @@ -233,7 +240,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 +290,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 +312,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 @@ -442,9 +456,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 @@ -453,6 +467,27 @@ http.sslverify false include::config.txt[] +BUGS +---- +When using the deprecated `[section.subsection]` syntax, changing a value +will result in adding a multi-line key instead of a change, if the subsection +is given with at least one uppercase character. For example when the config +looks like + +-------- + [section.subsection] + key = value1 +-------- + +and running `git config section.Subsection.key value2` will result in + +-------- + [section.subsection] + key = value1 + key = value2 +-------- + + GIT --- Part of the linkgit:git[1] suite 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..72179d993c 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -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..64c01ba918 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -110,6 +110,25 @@ 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 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). + --refspec:: Apply the specified refspec to each ref exported. Multiple of them can be specified. @@ -119,7 +138,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..d65cdb3d08 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 @@ -384,6 +385,7 @@ 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 data @@ -420,7 +422,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 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` ^^^^^^^^ @@ -740,6 +747,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 @@ -748,6 +768,7 @@ lightweight (non-annotated) tags see the `reset` command below. .... 'tag' SP <name> LF 'from' SP <commit-ish> LF + original-oid? 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF data .... @@ -822,6 +843,7 @@ assigned mark. .... 'blob' LF mark? + original-oid? data .... @@ -949,10 +971,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 +997,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 +1013,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 +1398,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..266d63cf11 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -266,7 +266,7 @@ The `pu` branch will be updated even if it is 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 diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e6f08ab189..6b53dd7e06 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -189,7 +189,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:: 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 085d177d97..774cecc7ed 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -57,7 +57,7 @@ OPTIONS `xx`; for example `%00` interpolates to `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). ---color[=<when>]: +--color[=<when>]:: Respect any colors specified in the `--format` option. The `<when>` field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). @@ -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'' @@ -361,6 +366,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..1af85d404f 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -23,6 +23,8 @@ SYNOPSIS [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] + [--interdiff=<previous>] + [--range-diff=<previous> [--creation-factor=<percent>]] [--progress] [<common diff options>] [ <since> | <revision range> ] @@ -228,6 +230,38 @@ 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. +--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>]:: Append the notes (see linkgit:git-notes[1]) for the commit after the three-dash line. @@ -470,9 +504,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 +629,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 +645,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 +664,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 b9f060e3b2..e0eae642c1 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 @@ -110,6 +118,9 @@ Any corrupt objects you will have to find in backups or other archives (i.e., you can just remove them and do an 'rsync' with some other site in the hopes that somebody else has the object you have corrupted). +If core.commitGraph is true, the commit-graph file will also be inspected +using 'git commit-graph verify'. See linkgit:git-commit-graph[1]. + Extracted Diagnostics --------------------- @@ -137,9 +148,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 24b2dd44fe..247f765604 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,65 +77,39 @@ 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.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 ----- @@ -163,8 +119,8 @@ 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). +refs/original/, 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. @@ -185,8 +141,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 312409a607..2d27969057 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -13,12 +13,12 @@ SYNOPSIS [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] [-P | --perl-regexp] - [-F | --fixed-strings] [-n | --line-number] + [-F | --fixed-strings] [-n | --line-number] [--column] [-l | --files-with-matches] [-L | --files-without-match] [(-O | --open-files-in-pager) [<pager>]] [-z | --null] - [-c | --count] [--all-match] [-q | --quiet] - [--max-depth <depth>] + [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet] + [--max-depth <depth>] [--[no-]recursive] [--color[=<when>] | --no-color] [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] @@ -44,6 +44,9 @@ CONFIGURATION grep.lineNumber:: If set to true, enable `-n` option by default. +grep.column:: + If set to true, enable the `--column` option by default. + grep.patternType:: Set the default matching behavior. Using a value of 'basic', 'extended', 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, @@ -85,7 +88,7 @@ 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`. @@ -116,11 +119,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 @@ -169,6 +179,10 @@ providing this option will cause it to die. --line-number:: Prefix the line number to matching lines. +--column:: + Prefix the 1-indexed byte-offset of the first match from the start of the + matching line. + -l:: --files-with-matches:: --name-only:: @@ -194,6 +208,11 @@ providing this option will cause it to die. Output \0 instead of the character that normally follows a file name. +-o:: +--only-matching:: + Print only the matched (non-empty) parts of a matching line, with each such + part on a separate output line. + -c:: --count:: Instead of showing every matched line, show the number of diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index a40fc38d8b..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,15 @@ 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:: + List all available configuration variables. This is a short + summary of the list in linkgit:git-config[1]. -g:: --guides:: @@ -107,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). @@ -160,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 032613c420..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 a `imap://` prefix for non-secure - connections and a `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..32880aafb0 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -38,8 +38,6 @@ the repository to another place if --separate-git-dir is given). OPTIONS ------- --- - -q:: --quiet:: @@ -111,8 +109,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 +128,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 9111c47a1b..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 @@ -88,7 +89,8 @@ OPTIONS Specify where all new trailers will be added. A setting provided with '--where' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. + '--where' or '--no-where'. Possible values are `after`, `before`, + `end` or `start`. --if-exists <action>:: --no-if-exists:: @@ -96,7 +98,8 @@ OPTIONS least one trailer with the same <token> in the message. A setting provided with '--if-exists' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. + '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, + `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. --if-missing <action>:: --no-if-missing:: @@ -104,7 +107,8 @@ OPTIONS trailer with the same <token> in the message. A setting provided with '--if-missing' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. + '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` + or `add`. --only-trailers:: Output only the trailers, not any other parts of the input. @@ -122,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..b02e922dc3 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -192,6 +192,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..8461c0e83e 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 diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index b9fd3770a6..0b057cbb10 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -31,7 +31,7 @@ OPTIONS displayed. --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:: 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..9f07f4f6ed 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -154,13 +154,13 @@ 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---B2 / ---o---o---B1--o---o---o---B (origin/master) \ - B0 + B0 \ - D0---D1---D (topic) + 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 diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 6a5c00e2c2..6294dbc09d 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--[no-]allow-unrelated-histories] - [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] + [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...] 'git merge' --abort 'git merge' --continue @@ -75,7 +75,16 @@ The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' invocations. The automated message can include the branch description. ---[no-]rerere-autoupdate:: +-F <file>:: +--file=<file>:: + Read the commit message to be used for the merge commit (in + case one is created). ++ +If `--log` is specified, a shortlog of the commits being merged +will be appended to the specified message. + +--rerere-autoupdate:: +--no-rerere-autoupdate:: Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. @@ -122,9 +131,9 @@ merge' may need to update. To avoid recording unrelated changes in the merge commit, 'git pull' and 'git merge' will also abort if there are any changes -registered in the index relative to the `HEAD` commit. (One -exception is when the changed index entries are in the state that -would result from the merge already.) +registered in the index relative to the `HEAD` commit. (Special +narrow exceptions to this rule may exist depending on which merge +strategy is in use, but generally, the index must match HEAD.) If all named commits are already ancestors of `HEAD`, 'git merge' will exit early with the message "Already up to date." @@ -334,7 +343,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 new file mode 100644 index 0000000000..f7778a2c85 --- /dev/null +++ b/Documentation/git-multi-pack-index.txt @@ -0,0 +1,66 @@ +git-multi-pack-index(1) +======================= + +NAME +---- +git-multi-pack-index - Write and verify multi-pack-indexes + + +SYNOPSIS +-------- +[verse] +'git multi-pack-index' [--object-dir=<dir>] <verb> + +DESCRIPTION +----------- +Write or verify a multi-pack-index (MIDX) file. + +OPTIONS +------- + +--object-dir=<dir>:: + Use given directory for the location of Git objects. We check + `<dir>/packs/multi-pack-index` for the current MIDX file, and + `<dir>/packs` for the pack-files to index. + +write:: + When given as the verb, write a new MIDX file to + `<dir>/packs/multi-pack-index`. + +verify:: + When given as the verb, verify the contents of the MIDX file + at `<dir>/packs/multi-pack-index`. + + +EXAMPLES +-------- + +* Write a MIDX file for the packfiles in the current .git folder. ++ +----------------------------------------------- +$ git multi-pack-index write +----------------------------------------------- + +* Write a MIDX file for the packfiles in an alternate object store. ++ +----------------------------------------------- +$ git multi-pack-index --object-dir <alt> write +----------------------------------------------- + +* Verify the MIDX file for the packfiles in the current .git folder. ++ +----------------------------------------------- +$ git multi-pack-index verify +----------------------------------------------- + + +SEE ALSO +-------- +See link:technical/multi-pack-index.html[The Multi-Pack-Index Design +Document] and link:technical/pack-format.html[The Multi-Pack-Index +Format] for more information on the multi-pack-index feature. + + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index e8dec1b3c8..f56a5a9197 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -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.) @@ -199,7 +199,7 @@ OPTIONS .git/NOTES_MERGE_REF symref is updated to the resulting commit. --abort:: - Abort/reset a in-progress 'git notes merge', i.e. a notes merge + Abort/reset an in-progress 'git notes merge', i.e. a notes merge with conflicts. This simply removes all files related to the notes merge. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index f0de3b891b..3494a1db3e 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,6 +374,14 @@ 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 +~~~~~~~~~~~~~~~ +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. + +One usage scenario is to run unit tests in the hook. + 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..e45f3e680d 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] [--sparse] < object-list DESCRIPTION @@ -196,6 +196,15 @@ depth is 4095. Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. +--sparse:: + Use 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. + --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 +298,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..a5e9501a0a 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -112,8 +112,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. + diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 55277a9781..6a8a0d958b 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 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 new file mode 100644 index 0000000000..8a6ea2c6c5 --- /dev/null +++ b/Documentation/git-range-diff.txt @@ -0,0 +1,269 @@ +git-range-diff(1) +================= + +NAME +---- +git-range-diff - Compare two commit ranges (e.g. two versions of a branch) + +SYNOPSIS +-------- +[verse] +'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>] + [--no-dual-color] [--creation-factor=<factor>] + ( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> ) + +DESCRIPTION +----------- + +This command shows the differences between two versions of a patch +series, or more generally, two commit ranges (ignoring merge commits). + +To that end, it first finds pairs of commits from both commit ranges +that correspond with each other. Two commits are said to correspond when +the diff between their patches (i.e. the author information, the commit +message and the commit diff) is reasonably small compared to the +patches' size. See ``Algorithm`` below for details. + +Finally, the list of matching commits is shown in the order of the +second commit range, with unmatched commits being inserted just after +all of their ancestors have been shown. + + +OPTIONS +------- +--no-dual-color:: + When the commit diffs differ, `git range-diff` recreates the + original diffs' coloring, and adds outer -/+ diff markers with + the *background* being red/green to make it easier to see e.g. + when there was a change in what exact lines were added. ++ +Additionally, the commit diff lines that are only present in the first commit +range are shown "dimmed" (this can be overridden using the `color.diff.<slot>` +config setting where `<slot>` is one of `contextDimmed`, `oldDimmed` and +`newDimmed`), and the commit diff lines that are only present in the second +commit range are shown in bold (which can be overridden using the config +settings `color.diff.<slot>` with `<slot>` being one of `contextBold`, +`oldBold` or `newBold`). ++ +This is known to `range-diff` as "dual coloring". Use `--no-dual-color` +to revert to color all lines according to the outer diff markers +(and completely ignore the inner diff when it comes to color). + +--creation-factor=<percent>:: + Set the creation/deletion cost fudge factor to `<percent>`. + Defaults to 60. Try a larger value if `git range-diff` erroneously + considers a large change a total rewrite (deletion of one commit + and addition of another), and a smaller one in the reverse case. + See the ``Algorithm`` section below for an explanation why this is + needed. + +<range1> <range2>:: + Compare the commits specified by the two ranges, where + `<range1>` is considered an older version of `<range2>`. + +<rev1>...<rev2>:: + Equivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`. + +<base> <rev1> <rev2>:: + Equivalent to passing `<base>..<rev1>` and `<base>..<rev2>`. + Note that `<base>` does not need to be the exact branch point + of the branches. Example: after rebasing a branch `my-topic`, + `git range-diff my-topic@{u} my-topic@{1} my-topic` would + show the differences introduced by the rebase. + +`git range-diff` also accepts the regular diff options (see +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 +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 +------------- +This command uses the `diff.color.*` and `pager.range-diff` settings +(the latter is on by default). +See linkgit:git-config[1]. + + +EXAMPLES +-------- + +When a rebase required merge conflicts to be resolved, compare the changes +introduced by the rebase directly afterwards using: + +------------ +$ git range-diff @{u} @{1} @ +------------ + + +A typical output of `git range-diff` would look like this: + +------------ +-: ------- > 1: 0ddba11 Prepare for the inevitable! +1: c0debee = 2: cab005e Add a helpful message at the start +2: f00dbal ! 3: decafe1 Describe a bug + @@ -1,3 +1,3 @@ + Author: A U Thor <author@example.com> + + -TODO: Describe a bug + +Describe a bug + @@ -324,5 +324,6 + This is expected. + + -+What is unexpected is that it will also crash. + ++Unexpectedly, it also crashes. This is a bug, and the jury is + ++still out there how to fix it best. See ticket #314 for details. + + Contact +3: bedead < -: ------- TO-UNDO +------------ + +In this example, there are 3 old and 3 new commits, where the developer +removed the 3rd, added a new one before the first two, and modified the +commit message of the 2nd commit as well its diff. + +When the output goes to a terminal, it is color-coded by default, just +like regular `git diff`'s output. In addition, the first line (adding a +commit) is green, the last line (deleting a commit) is red, the second +line (with a perfect match) is yellow like the commit header of `git +show`'s output, and the third line colors the old commit red, the new +one green and the rest like `git show`'s commit header. + +A naive color-coded diff of diffs is actually a bit hard to read, +though, as it colors the entire lines red or green. The line that added +"What is unexpected" in the old commit, for example, is completely red, +even if the intent of the old commit was to add something. + +To help with that, `range` uses the `--dual-color` mode by default. In +this mode, the diff of diffs will retain the original diff colors, and +prefix the lines with -/+ markers that have their *background* red or +green, to make it more obvious that they describe how the diff itself +changed. + + +Algorithm +--------- + +The general idea is this: we generate a cost matrix between the commits +in both commit ranges, then solve the least-cost assignment. + +The cost matrix is populated thusly: for each pair of commits, both +diffs are generated and the "diff of diffs" is generated, with 3 context +lines, then the number of lines in that diff is used as cost. + +To avoid false positives (e.g. when a patch has been removed, and an +unrelated patch has been added between two iterations of the same patch +series), the cost matrix is extended to allow for that, by adding +fixed-cost entries for wholesale deletes/adds. + +Example: Let commits `1--2` be the first iteration of a patch series and +`A--C` the second iteration. Let's assume that `A` is a cherry-pick of +`2,` and `C` is a cherry-pick of `1` but with a small modification (say, +a fixed typo). Visualize the commits as a bipartite graph: + +------------ + 1 A + + 2 B + + C +------------ + +We are looking for a "best" explanation of the new series in terms of +the old one. We can represent an "explanation" as an edge in the graph: + + +------------ + 1 A + / + 2 --------' B + + C +------------ + +This explanation comes for "free" because there was no change. Similarly +`C` could be explained using `1`, but that comes at some cost c>0 +because of the modification: + +------------ + 1 ----. A + | / + 2 ----+---' B + | + `----- C + c>0 +------------ + +In mathematical terms, what we are looking for is some sort of a minimum +cost bipartite matching; `1` is matched to `C` at some cost, etc. The +underlying graph is in fact a complete bipartite graph; the cost we +associate with every edge is the size of the diff between the two +commits' patches. To explain also new commits, we introduce dummy nodes +on both sides: + +------------ + 1 ----. A + | / + 2 ----+---' B + | + o `----- C + c>0 + o o + + o o +------------ + +The cost of an edge `o--C` is the size of `C`'s diff, modified by a +fudge factor that should be smaller than 100%. The cost of an edge +`o--o` is free. The fudge factor is necessary because even if `1` and +`C` have nothing in common, they may still share a few empty lines and +such, possibly making the assignment `1--C`, `o--o` slightly cheaper +than `1--o`, `o--C` even if `1` and `C` have nothing in common. With the +fudge factor we require a much larger common part to consider patches as +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 +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: + +------------ + 1 ----. A + | / + 2 ----+---' B + .--+-----' + o -' `----- C + c>0 + o ---------- o + + o ---------- o +------------ + + +SEE ALSO +-------- +linkgit:git-log[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 5c70bc2878..d271842608 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 @@ -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. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 0e20a66e73..5e4e927647 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -203,7 +203,7 @@ Alternatively, you can undo the 'git rebase' with CONFIGURATION ------------- -include::rebase-config.txt[] +include::config/rebase.txt[] OPTIONS ------- @@ -243,11 +243,15 @@ leave out at most one of A and B, in which case it defaults to HEAD. --keep-empty:: Keep the commits that do not change anything from its parents in the result. ++ +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. ++ +See also INCOMPATIBLE OPTIONS below. --skip:: Restart the rebasing process by skipping the current patch. @@ -271,6 +275,8 @@ branch on top of the <upstream> branch. Because of this, when a merge conflict happens, the side reported as 'ours' is the so-far rebased series, starting with <upstream>, and 'theirs' is the working branch. In other words, the sides are swapped. ++ +See also INCOMPATIBLE OPTIONS below. -s <strategy>:: --strategy=<strategy>:: @@ -280,8 +286,10 @@ other words, the sides are swapped. + Because 'git rebase' replays each commit from the working branch on top of the <upstream> branch using the given strategy, using -the 'ours' strategy simply discards all patches from the <branch>, +the 'ours' strategy simply empties all patches from the <branch>, which makes little sense. ++ +See also INCOMPATIBLE OPTIONS below. -X <strategy-option>:: --strategy-option=<strategy-option>:: @@ -289,6 +297,13 @@ which makes little sense. This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and 'theirs' as noted above for the `-m` option. ++ +See also INCOMPATIBLE OPTIONS below. + +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -324,17 +339,21 @@ which makes little sense. and after each change. When fewer lines of surrounding context exist they all must match. By default no context is ever ignored. ++ +See also INCOMPATIBLE OPTIONS below. --f:: +--no-ff:: --force-rebase:: - Force a rebase even if the current branch is up to date and - the command without `--force` would return without doing anything. +-f:: + Individually replay all rebased commits instead of fast-forwarding + over the unchanged ones. This ensures that the entire history of + the rebased branch is composed of new commits. + -You may find this (or --no-ff with an interactive rebase) helpful after -reverting a topic branch merge, as this option recreates the topic branch with -fresh commits so it can be remerged successfully without needing to "revert -the reversion" (see the -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). +You may find this helpful after reverting a topic branch merge, as this option +recreates the topic branch with fresh commits so it can be remerged +successfully without needing to "revert the reversion" (see the +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for +details). --fork-point:: --no-fork-point:: @@ -355,19 +374,22 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. --whitespace=<option>:: These flag are passed to the 'git apply' program (see linkgit:git-apply[1]) that applies the patch. - Incompatible with the --interactive option. ++ +See also INCOMPATIBLE OPTIONS below. --committer-date-is-author-date:: --ignore-date:: These flags are passed to 'git am' to easily change the dates of the rebased commits (see linkgit:git-am[1]). - Incompatible with the --interactive option. ++ +See also INCOMPATIBLE OPTIONS below. --signoff:: Add a Signed-off-by: trailer to all the rebased commits. Note that if `--interactive` is given then only commits marked to be - picked, edited or reworded will have the trailer added. Incompatible - with the `--preserve-merges` option. + picked, edited or reworded will have the trailer added. ++ +See also INCOMPATIBLE OPTIONS below. -i:: --interactive:: @@ -378,6 +400,8 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. The commit list format can be changed by setting the configuration option rebase.instructionFormat. A customized instruction format will automatically have the long commit hash prepended to the format. ++ +See also INCOMPATIBLE OPTIONS below. -r:: --rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: @@ -391,36 +415,40 @@ have the long commit hash prepended to the format. + 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 in contrast to that option works well in interactive +rebases: 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 explicit `exec git merge -s <strategy> [...]` commands. + -See also REBASING MERGES below. +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 idea unless you know what you are doing (see BUGS below). ++ +See also INCOMPATIBLE OPTIONS below. -x <cmd>:: --exec <cmd>:: Append "exec <cmd>" after each line creating a commit in the final history. <cmd> will be interpreted as one or more shell - 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: @@ -437,6 +465,8 @@ squash/fixup series. + This uses the `--interactive` machinery internally, but it can be run without an explicit `--interactive`. ++ +See also INCOMPATIBLE OPTIONS below. --root:: Rebase all commits reachable from <branch>, instead of @@ -447,6 +477,8 @@ without an explicit `--interactive`. When used together with both --onto and --preserve-merges, 'all' root commits will be rewritten to have <newbase> as parent instead. ++ +See also INCOMPATIBLE OPTIONS below. --autosquash:: --no-autosquash:: @@ -461,11 +493,11 @@ without an explicit `--interactive`. too. The recommended way to create fixup/squash commits is by using the `--fixup`/`--squash` options of linkgit:git-commit[1]. + -This option is only valid when the `--interactive` option is used. -+ If the `--autosquash` option is enabled by default using the configuration variable `rebase.autoSquash`, this option can be used to override and disable this setting. ++ +See also INCOMPATIBLE OPTIONS below. --autostash:: --no-autostash:: @@ -475,17 +507,69 @@ used to override and disable this setting. with care: the final stash application after a successful rebase might result in non-trivial conflicts. ---no-ff:: - With --interactive, cherry-pick all rebased commits instead of - fast-forwarding over the unchanged ones. This ensures that the - entire history of the rebased branch is composed of new commits. -+ -Without --interactive, this is a synonym for --force-rebase. -+ -You may find this helpful after reverting a topic branch merge, as this option -recreates the topic branch with fresh commits so it can be remerged -successfully without needing to "revert the reversion" (see the -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). +--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 +-------------------- + +The following options: + + * --committer-date-is-author-date + * --ignore-date + * --whitespace + * --ignore-whitespace + * -C + +are incompatible with the following options: + + * --merge + * --strategy + * --strategy-option + * --allow-empty-message + * --[no-]autosquash + * --rebase-merges + * --preserve-merges + * --interactive + * --exec + * --keep-empty + * --edit-todo + * --root when used in combination with --onto + +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 + +BEHAVIORAL DIFFERENCES +----------------------- + +There are some subtle differences how the backends behave. + +Empty commits +~~~~~~~~~~~~~ + +The am backend drops any "empty" commits, regardless of 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). + +The interactive backend drops commits by default that +started empty and halts if it hits a commit that ended up empty. +The `--keep-empty` option exists for the interactive backend to allow +it to keep commits that started empty. + +Directory rename detection +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Directory rename heuristics are enabled in the merge and interactive +backends. Due to the lack of accurate tree information, directory +rename detection is disabled in the am backend. include::merge-strategies.txt[] @@ -560,6 +644,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". @@ -588,7 +675,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 @@ -602,7 +690,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 @@ -804,7 +892,7 @@ The ripple effect of a "hard case" recovery is especially bad: case" recovery too! REBASING MERGES ------------------ +--------------- The interactive rebase command was originally designed to handle individual patch series. As such, it makes sense to exclude merge @@ -873,14 +961,14 @@ 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 list manually and contains a typo). -The `merge` command will merge the specified revision into whatever is -HEAD at that time. With `-C <original-commit>`, the commit message of +The `merge` command will merge the specified revision(s) into whatever +is HEAD at that time. With `-C <original-commit>`, the commit message of the specified merge commit will be used. When the `-C` is changed to a lower-case `-c`, the message will be opened in an editor after a successful merge so that the user can edit the message. @@ -889,7 +977,8 @@ If a `merge` command fails for any reason other than merge conflicts (i.e. when the merge operation did not even start), it is rescheduled immediately. At this time, the `merge` command will *always* use the `recursive` -merge strategy, with no way to choose a different one. To work around +merge strategy for regular merges, and `octopus` for octopus merges, +with no way to choose a different one. To work around this, an `exec` command can be used to call `git merge` explicitly, using the fact that the labels are worktree-local refs (the ref `refs/rewritten/onto` would correspond to the label `onto`, for example). @@ -938,11 +1027,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-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-repack.txt b/Documentation/git-repack.txt index d90e7907f4..aa0cc8bd44 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -40,6 +40,11 @@ OPTIONS Note that users fetching over dumb protocols will have to fetch the whole new pack in order to get any contained object, no matter how many other objects in that pack they already have locally. ++ +Promisor packfiles are repacked separately: if there are packfiles that +have an associated ".promisor" file, these packfiles will be repacked +into another separate pack, and an empty ".promisor" file corresponding +to the new separate pack will be written. -A:: Same as `-a`, unless `-d` is used. Then any unreachable @@ -155,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-rerere.txt b/Documentation/git-rerere.txt index 031f31fa47..95763d7581 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. @@ -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..26e746c53f 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -14,14 +14,14 @@ SYNOPSIS 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. +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 + 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 @@ -36,7 +36,7 @@ working tree in one go. 'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]:: 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 +44,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,24 +66,24 @@ 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. -- If you want to undo a commit other than the latest on a branch, @@ -95,7 +95,10 @@ 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. EXAMPLES @@ -112,17 +115,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,14 +137,14 @@ $ 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:: + @@ -152,11 +155,11 @@ $ git checkout 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 +168,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 +189,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 +214,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:: @@ -284,13 +287,13 @@ $ git checkout -b 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 checkout -b 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 +317,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 +354,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-revert.txt b/Documentation/git-revert.txt index 837707a8fd..0c82ca5bc0 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -66,6 +66,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 @@ -101,6 +108,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-send-email.txt b/Documentation/git-send-email.txt index cf4e3d99bc..a861934c69 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 @@ -329,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. -- + @@ -412,7 +420,7 @@ have been specified, in which case default to 'compose'. 998 characters unless a suitable transfer encoding ('auto', 'base64', or 'quoted-printable') is used; this is due to SMTP limits as described by - http://www.ietf.org/rfc/rfc2821.txt. + http://www.ietf.org/rfc/rfc5322.txt. -- + Default is the value of `sendemail.validate`; if this is not set, 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-index.txt b/Documentation/git-show-index.txt index a8a9509e0e..424e4ba84c 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -14,13 +14,27 @@ SYNOPSIS DESCRIPTION ----------- -Read the idx file for a Git packfile created with -'git pack-objects' command from the standard input, and -dump its contents. +Read the `.idx` file for a Git packfile (created with +linkgit:git-pack-objects[1] or linkgit:git-index-pack[1]) from the +standard input, and dump its contents. The output consists of one object +per line, with each line containing two or three space-separated +columns: -The information it outputs is subset of what you can get from -'git verify-pack -v'; this command only shows the packfile -offset and SHA-1 of each object. + - the first column is the offset in bytes of the object within the + corresponding packfile + + - the second column is the object id of the object + + - if the index version is 2 or higher, the third column contains the + CRC32 of the object data + +The objects are output in the order in which they are found in the index +file, which should be (in a correctly constructed file) sorted by object +id. + +Note that you can get more information on a packfile by calling +linkgit:git-verify-pack[1]. However, as this command considers only the +index file itself, it's both faster and more flexible. GIT --- 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-stash.txt b/Documentation/git-stash.txt index 7ef8c47911..e31ea7d303 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,7 +9,7 @@ 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>] @@ -106,7 +106,7 @@ 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 diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index c4467ffb98..d4e8f24f0c 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -106,7 +106,7 @@ It is optional: it defaults to 'traditional'. The possible options are: + - 'traditional' - Shows ignored files and directories, unless - --untracked-files=all is specifed, in which case + --untracked-files=all is specified, in which case individual files in ignored directories are displayed. - 'no' - Show no ignored files. @@ -197,31 +197,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 +278,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 +312,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 +382,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 ef9d9d28a9..0ed5c24dc1 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,11 +9,13 @@ 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] summary [<options>] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--recursive] [--] [<path>...] @@ -28,6 +30,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 +43,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). + @@ -168,6 +173,12 @@ 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 ((-d|--default)|(-b|--branch <branch>)) [--] <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'. + 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 @@ -183,12 +194,17 @@ information too. foreach [--recursive] <command>:: Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $path, $sha1 and - $toplevel: + The command has access to the variables $name, $sm_path, $displaypath, + $sha1 and $toplevel: $name is the name of the relevant submodule section in `.gitmodules`, - $path is the name of the submodule directory relative to the - superproject, $sha1 is the commit as recorded in the superproject, - and $toplevel is the absolute path to the top-level of the superproject. + $sm_path is the path of the submodule as recorded in the immediate + superproject, $displaypath contains the relative path from the + current working directory to the submodules root directory, + $sha1 is the commit as recorded in the immediate + superproject, and $toplevel is the absolute path to the top-level + of the immediate superproject. + Note that to avoid conflicts with '$PATH' on Windows, the '$path' + variable is now a deprecated synonym of '$sm_path' variable. Any submodules defined in the superproject but not checked out are ignored by this command. Unless given `--quiet`, foreach prints the name of each submodule before evaluating the command. @@ -250,13 +266,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:: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 7ea24fc942..30711625fd 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;; @@ -452,7 +452,7 @@ Any other arguments are passed directly to 'git log' 'commit-diff':: Commits the diff of two tree-ish arguments from the - command-line. This command does not rely on being inside an `git svn + command-line. This command does not rely on being inside a `git svn init`-ed repository. This command takes three arguments, (a) the original tree to diff against, (b) the new tree result, (c) the URL of the target Subversion repository. The final argument @@ -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. @@ -760,7 +760,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 @@ -1100,10 +1100,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 +1154,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-tag.txt b/Documentation/git-tag.txt index 87c4288ffc..a74e7b926d 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -115,7 +115,7 @@ options for details. variable if it exists, or lexicographic order otherwise. See linkgit:git-config[1]. ---color[=<when>]: +--color[=<when>]:: Respect any colors specified in the `--format` option. The `<when>` field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). @@ -187,6 +187,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 +204,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 +237,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 4e8e762e68..1c4d146a41 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -245,10 +245,10 @@ USING --CACHEINFO OR --INFO-ONLY current working directory. This is useful for minimum-checkout merging. -To pretend you have a file with mode and sha1 at path, say: +To pretend you have a file at path with mode and sha1, say: ---------------- -$ git update-index --cacheinfo <mode>,<sha1>,<path> +$ git update-index --add --cacheinfo <mode>,<sha1>,<path> ---------------- `--info-only` is used to register files without placing them in the object @@ -268,23 +268,20 @@ USING --INDEX-INFO multiple entry definitions from the standard input, and designed specifically for scripts. It can take inputs of three formats: - . mode SP sha1 TAB path -+ -The first format is what "git-apply --index-info" -reports, and used to reconstruct a partial tree -that is used for phony merge base tree when falling -back on 3-way merge. - . mode SP type SP sha1 TAB path + -The second format is to stuff 'git ls-tree' output -into the index file. +This format is to stuff `git ls-tree` output into the index. . mode SP sha1 SP stage TAB path + This format is to put higher order stages into the index file and matches 'git ls-files --stage' output. + . mode SP sha1 TAB path ++ +This format is no longer produced by any Git command, but is +and will continue to be supported by `update-index --index-info`. + To place a higher stage entry to the index, the path should first be removed by feeding a mode=0 entry for the path, and then feeding necessary input lines in the third format. diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index bc8fdfd469..9671423117 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 ----------- @@ -129,8 +129,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 +138,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-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 afc6576a14..85d92c9761 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -60,6 +60,15 @@ with a matching name, treat as equivalent to: $ git worktree add --track -b <branch> <path> <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]. ++ If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, then, as a convenience, the new worktree is associated with a branch (call it `<branch>`) named after `$(basename <path>)`. If `<branch>` @@ -111,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>:: @@ -164,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. @@ -183,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 @@ -207,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 @@ -232,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 @@ -249,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..6ddc1e2ca6 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -76,7 +76,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. @@ -402,11 +402,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 @@ -536,7 +536,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 +598,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 +660,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 +905,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://public-inbox.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..4fb20cd0e9 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 @@ -124,7 +124,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:: @@ -303,21 +305,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 +346,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. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index f970196bc1..adc759612d 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -133,6 +133,12 @@ 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. +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 --------------------- 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 10c8ff93c0..9f2528fc8c 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt @@ -244,7 +244,7 @@ commands in addition to the ones needed by participants. This section can also be used by those who respond to `git request-pull` or pull-request on GitHub (www.github.com) to -integrate the work of others into their history. An sub-area +integrate the work of others into their history. A sub-area lieutenant for a repository will act both as a participant and as an integrator. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index e3c283a174..786e778ab8 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -99,6 +99,10 @@ 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. + prepare-commit-msg ~~~~~~~~~~~~~~~~~~ @@ -485,6 +489,31 @@ 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-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. + +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 --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index ff5d7f9ed6..b5bc9dbff0 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -7,7 +7,7 @@ gitignore - Specifies intentionally untracked files to ignore SYNOPSIS -------- -$HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore +$XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore DESCRIPTION ----------- @@ -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 ----- diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 244cd01493..1eabb0aaf3 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -168,12 +168,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..a66e95b70c 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -67,7 +67,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). @@ -84,12 +85,14 @@ submodule.<name>.ignore:: 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-submodule" 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 @@ -112,7 +115,7 @@ Consider the following .gitmodules file: 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 diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 9d1459aac6..43f80c8068 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -1,4 +1,4 @@ -gitremote-helpers(1) +gitremote-helpers(7) ==================== NAME @@ -468,7 +468,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>':: @@ -513,8 +513,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..216b11ee88 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -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 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 @@ -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 3b9faabdbb..0a890205b8 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -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,12 +193,12 @@ 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, -if we have an `submodule.<name>.active` set to `false` or if the +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 the example that follows. diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 9c8982ec98..35317e71c8 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. @@ -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..c7436098c9 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -36,7 +36,7 @@ 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 +51,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 +231,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 +407,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 +431,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 +456,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 +503,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 +575,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 +585,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 +596,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 +614,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 +645,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 +681,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 +697,7 @@ SEE ALSO -------- linkgit:gitweb.conf[5], linkgit:git-instaweb[1] -'gitweb/README', 'gitweb/INSTALL' +`gitweb/README`, `gitweb/INSTALL` GIT --- diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 6c2d23dc48..8d38ae6010 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -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). @@ -334,7 +343,7 @@ The optional colon that terminates the "magic signature" can be omitted if the pattern begins with a character that does not belong to "magic signature" symbol set and is not a colon. + -In the long form, the leading colon `:` is followed by a open +In the long form, the leading colon `:` is followed by an open parenthesis `(`, a comma-separated list of zero or more "magic words", and a close parentheses `)`, and the remainder is the pattern to match against the path. @@ -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/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/merge-options.txt b/Documentation/merge-options.txt index 63a3fc0954..61876dbc33 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,6 +32,13 @@ 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. +--cleanup=<mode>:: + This option determines how the merge message will be cleaned up before + commiting. 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:: When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 6109ef09aa..079598307a 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -102,115 +102,160 @@ 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]) +'%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. +'%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 +'%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/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index c579793af5..7d3a60f5b9 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -33,11 +33,40 @@ name. it requests fetching everything up to the given tag. + The remote ref that matches <src> -is fetched, and if <dst> is not 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..71a1fcc093 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>:: @@ -272,13 +270,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. -- @@ -308,8 +306,6 @@ ifdef::git-rev-list[] `<header>` text will be printed with each progress update. endif::git-rev-list[] --- - History Simplification ~~~~~~~~~~~~~~~~~~~~~~ @@ -729,15 +725,26 @@ 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. --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 +763,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 +770,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. @@ -799,12 +806,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 +820,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 +836,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 @@ -947,6 +961,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 diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 7d1bd44094..82c1e5754e 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,12 +103,12 @@ 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: + @@ -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}{}':: @@ -184,7 +186,8 @@ existing tag object. A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. The regular expression can match any part of the + reachable from any ref, including HEAD. + The regular expression can match any part of the commit message. To match messages starting with a string, one can use e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a @@ -193,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 @@ -301,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..5a57c4a407 100644 --- a/Documentation/sequencer.txt +++ b/Documentation/sequencer.txt @@ -1,6 +1,6 @@ --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. --quit:: diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index fa39ac9d71..7d20716c32 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -229,7 +229,7 @@ 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; diff --git a/Documentation/technical/api-diff.txt b/Documentation/technical/api-diff.txt index 8b001de0db..30fc0e9c93 100644 --- a/Documentation/technical/api-diff.txt +++ b/Documentation/technical/api-diff.txt @@ -18,8 +18,8 @@ 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. + then call `repo_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 diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index 4f44ca24f6..5abb8e8b1f 100644 --- a/Documentation/technical/api-directory-listing.txt +++ b/Documentation/technical/api-directory-listing.txt @@ -54,7 +54,7 @@ The notable options are: this case, the contents are returned as individual entries. + If this is set, files and directories that explicitly match an ignore -pattern are reported. Implicity ignored directories (directories that +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. diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt index e7cbb7c13a..45f0df600f 100644 --- a/Documentation/technical/api-gitattributes.txt +++ b/Documentation/technical/api-gitattributes.txt @@ -146,7 +146,7 @@ To get the values of all attributes associated with a file: * Iterate over the `attr_check.items[]` array to examine the attribute names and values. The name of the attribute - described by a `attr_check.items[]` object can be retrieved via + 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.) diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt index 18142b6d29..d0d1707c8c 100644 --- a/Documentation/technical/api-history-graph.txt +++ b/Documentation/technical/api-history-graph.txt @@ -80,7 +80,7 @@ Calling sequence it is invoked. * For each commit, call `graph_next_line()` repeatedly, until - `graph_is_commit_finished()` returns non-zero. Each call go + `graph_is_commit_finished()` returns non-zero. Each call to `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 @@ -115,7 +115,6 @@ 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; diff --git a/Documentation/technical/api-oid-array.txt b/Documentation/technical/api-oid-array.txt index 9febfb1d52..c97428c2c3 100644 --- a/Documentation/technical/api-oid-array.txt +++ b/Documentation/technical/api-oid-array.txt @@ -48,6 +48,11 @@ Functions is not sorted, this function has the side effect of sorting it. +`oid_array_filter`:: + Apply the callback function `want` to each entry in the array, + retaining only the entries for which the function returns true. + Preserve the order of the entries that are retained. + Examples -------- 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-revision-walking.txt b/Documentation/technical/api-revision-walking.txt index 55b878ade8..03f9ea6ac4 100644 --- a/Documentation/technical/api-revision-walking.txt +++ b/Documentation/technical/api-revision-walking.txt @@ -15,9 +15,9 @@ revision list. Functions --------- -`init_revisions`:: +`repo_init_revisions`:: - Initialize a rev_info structure with default values. The second + Initialize a rev_info structure with default values. The third 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 diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt new file mode 100644 index 0000000000..23c3cc7a37 --- /dev/null +++ b/Documentation/technical/api-trace2.txt @@ -0,0 +1,1378 @@ += 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_TR` +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":"1","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[] + +If the target already exists and is a directory, the traces will be +written to files (one per process) underneath the given 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 messsage 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. + +`void trace2_initialize_clock()`:: + + Initialize the Trace2 start clock and nothing else. This should + be called at the very top of main() to capture the process start + time and reduce startup order dependencies. + +`void trace2_initialize()`:: + + Determines if any Trace2 Targets should be enabled and + initializes the Trace2 facility. This includes setting up the + Trace2 thread local storage (TLS). ++ +This function emits a "version" message containing the version of git +and the Trace2 protocol. ++ +This function should be called from `main()` as early as possible in +the life of the process after essential process initialization. + +`int trace2_is_enabled()`:: + + Returns 1 if Trace2 is enabled (at least one target is + active). + +`void trace2_cmd_start(int argc, const char **argv)`:: + + Emits a "start" message containing the process command line + arguments. + +`int trace2_cmd_exit(int exit_code)`:: + + Emits an "exit" message containing the process exit-code and + elapsed time. ++ +Returns the exit-code. + +`void trace2_cmd_error(const char *fmt, va_list ap)`:: + + Emits an "error" message containing a formatted error message. + +`void trace2_cmd_path(const char *pathname)`:: + + Emits a "cmd_path" message with the full pathname of the + current process. + +=== Command Detail Messages + +These are concerned with describing the specific Git command +after the command line, config, and environment are inspected. + +`void trace2_cmd_name(const char *name)`:: + + Emits a "cmd_name" message with the canonical name of the + command, for example "status" or "checkout". + +`void trace2_cmd_mode(const char *mode)`:: + + Emits a "cmd_mode" message with a qualifier name to further + describe the current git command. ++ +This message is intended to be used with git commands having multiple +major modes. For example, a "checkout" command can checkout a new +branch or it can checkout a single file, so the checkout code could +emit a cmd_mode message of "branch" or "file". + +`void trace2_cmd_alias(const char *alias, const char **argv_expansion)`:: + + Emits an "alias" message containing the alias used and the + argument expansion. + +`void trace2_def_param(const char *parameter, const char *value)`:: + + Emits a "def_param" message containing a key/value pair. ++ +This message is intended to report some global aspect of the current +command, such as a configuration setting or command line switch that +significantly affects program performance or behavior, such as +`core.abbrev`, `status.showUntrackedFiles`, or `--no-ahead-behind`. + +`void trace2_cmd_list_config()`:: + + Emits a "def_param" messages for "important" configuration + settings. ++ +The environment variable `GIT_TRACE2_CONFIG_PARAMS` or the `trace2.configParams` +config value can be set to a +list of patterns of important configuration settings, for example: +`core.*,remote.*.url`. This function will iterate over all config +settings and emit a "def_param" message for each match. + +`void trace2_cmd_set_config(const char *key, const char *value)`:: + + Emits a "def_param" message for a new or updated key/value + pair IF `key` is considered important. ++ +This is used to hook into `git_config_set()` and catch any +configuration changes and update a value previously reported by +`trace2_cmd_list_config()`. + +`void trace2_def_repo(struct repository *repo)`:: + + Registers a repository with the Trace2 layer. Assigns a + unique "repo-id" to `repo->trace2_repo_id`. ++ +Emits a "worktree" messages containing the repo-id and the worktree +pathname. ++ +Region and data messages (described later) may refer to this repo-id. ++ +The main/top-level repository will have repo-id value 1 (aka "r1"). ++ +The repo-id field is in anticipation of future in-proc submodule +repositories. + +=== Child Process Messages + +These are concerned with the various spawned child processes, +including shell scripts, git commands, editors, pagers, and hooks. + +`void trace2_child_start(struct child_process *cmd)`:: + + Emits a "child_start" message containing the "child-id", + "child-argv", and "child-classification". ++ +Before calling this, set `cmd->trace2_child_class` to a name +describing the type of child process, for example "editor". ++ +This function assigns a unique "child-id" to `cmd->trace2_child_id`. +This field is used later during the "child_exit" message to associate +it with the "child_start" message. ++ +This function should be called before spawning the child process. + +`void trace2_child_exit(struct child_proess *cmd, int child_exit_code)`:: + + Emits a "child_exit" message containing the "child-id", + the child's elapsed time and exit-code. ++ +The reported elapsed time includes the process creation overhead and +time spend waiting for it to exit, so it may be slightly longer than +the time reported by the child itself. ++ +This function should be called after reaping the child process. + +`int trace2_exec(const char *exe, const char **argv)`:: + + Emits a "exec" message containing the "exec-id" and the + argv of the new process. ++ +This function should be called before calling one of the `exec()` +variants, such as `execvp()`. ++ +This function returns a unique "exec-id". This value is used later +if the exec() fails and a "exec-result" message is necessary. + +`void trace2_exec_result(int exec_id, int error_code)`:: + + Emits a "exec_result" message containing the "exec-id" + and the error code. ++ +On Unix-based systems, `exec()` does not return if successful. +This message is used to indicate that the `exec()` failed and +that the current program is continuing. + +=== Git Thread Messages + +These messages are concerned with Git thread usage. + +`void trace2_thread_start(const char *thread_name)`:: + + Emits a "thread_start" message. ++ +The `thread_name` field should be a descriptive name, such as the +unique name of the thread-proc. A unique "thread-id" will be added +to the name to uniquely identify thread instances. ++ +Region and data messages (described later) may refer to this thread +name. ++ +This function must be called by the thread-proc of the new thread +(so that TLS data is properly initialized) and not by the caller +of `pthread_create()`. + +`void trace2_thread_exit()`:: + + Emits a "thread_exit" message containing the thread name + and the thread elapsed time. ++ +This function must be called by the thread-proc before it returns +(so that the coorect TLS data is used and cleaned up. It should +not be called by the caller of `pthread_join()`. + +=== Region and Data Messages + +These are concerned with recording performance data +over regions or spans of code. + +`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`:: + +`void trace2_region_enter_printf(const char *category, const char *label, const struct repository *repo, const char *fmt, ...)`:: + +`void trace2_region_enter_printf_va(const char *category, const char *label, const struct repository *repo, const char *fmt, va_list ap)`:: + + Emits a thread-relative "region_enter" message with optional + printf string. ++ +This function pushes a new region nesting stack level on the current +thread and starts a clock for the new stack frame. ++ +The `category` field is an arbitrary category name used to classify +regions by feature area, such as "status" or "index". At this time +it is only just printed along with the rest of the message. It may +be used in the future to filter messages. ++ +The `label` field is an arbitrary label used to describe the activity +being started, such as "read_recursive" or "do_read_index". ++ +The `repo` field, if set, will be used to get the "repo-id", so that +recursive oerations can be attributed to the correct repository. + +`void trace2_region_leave(const char *category, const char *label, const struct repository *repo)`:: + +`void trace2_region_leave_printf(const char *category, const char *label, const struct repository *repo, const char *fmt, ...)`:: + +`void trace2_region_leave_printf_va(const char *category, const char *label, const struct repository *repo, const char *fmt, va_list ap)`:: + + Emits a thread-relative "region_leave" message with optional + printf string. ++ +This function pops the region nesting stack on the current thread +and reports the elapsed time of the stack frame. ++ +The `category`, `label`, and `repo` fields are the same as above. +The `category` and `label` do not need to match the correpsonding +"region_enter" message, but it makes the data stream easier to +understand. + +`void trace2_data_string(const char *category, const struct repository *repo, const char *key, const char * value)`:: + +`void trace2_data_intmax(const char *category, const struct repository *repo, const char *key, intmax value)`:: + +`void trace2_data_json(const char *category, const struct repository *repo, const char *key, const struct json_writer *jw)`:: + + Emits a region- and thread-relative "data" or "data_json" message. ++ +This is a key/value pair message containing information about the +current thread, region stack, and repository. This could be used +to print the number of files in a directory during a multi-threaded +recursive tree walk. + +`void trace2_printf(const char *fmt, ...)`:: + +`void trace2_printf_va(const char *fmt, va_list ap)`:: + + Emits a region- and thread-relative "printf" message. + +== 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. ++ +------------ +{ + "event":"version", + ... + "evt":"1", # EVENT format version + "exe":"2.20.1.155.g426c96fcdb" # git version +} +------------ + +`"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 + "signal":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 +proces 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. ++ +------------ +{ + "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 correpsonding 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 itemts +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/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index ad6af8105c..16452a0504 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -18,9 +18,9 @@ metadata, including: the graph file. These positional references are stored as unsigned 32-bit integers -corresponding to the array position withing the list of commit OIDs. We -use the most-significant bit for special purposes, so we can store at most -(1 << 31) - 1 (around 2 billion) commits. +corresponding to the array position within the list of commit OIDs. Due +to some special constants we use to track parents, we can store at most +(1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits. == Commit graph files have the following format: @@ -70,13 +70,13 @@ CHUNK DATA: OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) The OIDs for all commits in the graph, sorted in ascending order. - Commit Data (ID: {'C', 'G', 'E', 'T' }) (N * (H + 16) bytes) + Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) * The first H bytes are for the OID of the root tree. * The next 8 bytes are for the positions of the first two parents - of the ith commit. Stores value 0xffffffff if no parent in that + 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 +84,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 diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index 0550c6d0dc..7805b0968c 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -15,13 +15,13 @@ 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 +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 @@ -77,10 +77,33 @@ in the commit graph. We can treat these commits as having "infinite" generation number and walk until reaching commits with known generation number. +We use the macro GENERATION_NUMBER_INFINITY = 0xFFFFFFFF to mark commits not +in the commit-graph file. If a commit-graph file was written by a version +of Git that did not compute generation numbers, then those commits will +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, + and N < M, then A cannot reach B. + +Note how the strict inequality differs from the inequality when we have +fully-computed generation numbers. Using strict inequality may result in +walking a few extra commits, but the simplicity in dealing with commits +with generation number *_INFINITY or *_ZERO is valuable. + +We use the macro GENERATION_NUMBER_MAX = 0x3FFFFFFF to for commits whose +generation numbers are computed to be at least this value. We limit at +this value since it is the largest value that can be stored in the +commit-graph file using the 30 bits available to generation numbers. This +presents another case where a commit can have generation number equal to +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. @@ -89,48 +112,34 @@ 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. +- 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. + Future Work ----------- -- The commit graph feature currently does not honor commit grafts. This can - be remedied by duplicating or refactoring the current graft logic. - -- The 'commit-graph' subcommand does not have a "verify" mode that is - necessary for integration with fsck. - -- The file format includes room for precomputed generation numbers. These - are not currently computed, so all generation numbers will be marked as - 0 (or "uncomputed"). A later patch will include this calculation. - - 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: - - paint_down_to_common() - 'log --topo-order' + - 'tag --merged' -- Currently, parse_commit_gently() requires filling in the root tree - object for a commit. This passes through lookup_tree() and consequently - lookup_object(). Also, it calls lookup_commit() when loading the parents. - These method calls check the ODB for object existence, even if the - consumer does not need the content. For example, we do not need the - tree contents when computing merge bases. Now that commit parsing is - removed from the computation time, these lookup operations are the - slowest operations keeping graph walks from being fast. Consider - loading these objects without verifying their existence in the ODB and - only loading them fully when consumers need them. Consider a method - such as "ensure_tree_loaded(commit)" that fully loads a tree before - using commit->tree. - -- The current design uses the 'commit-graph' subcommand to generate the graph. - When this feature stabilizes enough to recommend to most users, we should - add automatic graph writes to common operations that create many commits. - For example, one could compute a graph on 'clone', 'fetch', or 'repack' - commands. - -- A server could provide a commit graph file as part of the network protocol +- 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. diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt new file mode 100644 index 0000000000..844629c8c4 --- /dev/null +++ b/Documentation/technical/directory-rename-detection.txt @@ -0,0 +1,115 @@ +Directory rename detection +========================== + +Rename detection logic in diffcore-rename that checks for renames of +individual files is aggregated and analyzed in merge-recursive for cases +where combinations of renames indicate that a full directory has been +renamed. + +Scope of abilities +------------------ + +It is perhaps easiest to start with an example: + + * When all of x/a, x/b and x/c have moved to z/a, z/b and z/c, it is + likely that x/d added in the meantime would also want to move to z/d by + taking the hint that the entire directory 'x' moved to 'z'. + +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. + + * both 'x' and 'y' being merged into a single directory 'z', with a + directory rename being detected for both x->z and y->z. + + * not all files in a directory being renamed to the same location; + i.e. perhaps most the files in 'x' are now found under 'z', but a few + are found under 'w'. + + * a directory being renamed, which also contained a subdirectory that was + renamed to some entirely different location. (And perhaps the inner + directory itself contained inner directories that were renamed to yet + other locations). + + * combinations of the above; see t/t6043-merge-rename-directories.sh for + various interesting cases. + +Limitations -- applicability of directory renames +------------------------------------------------- + +In order to prevent edge and corner cases resulting in either conflicts +that cannot be represented in the index or which might be too complex for +users to try to understand and resolve, a couple basic rules limit when +directory rename detection applies: + + 1) If a given directory still exists on both sides of a merge, we do + not consider it to have been renamed. + + 2) If a subset of to-be-renamed files have a file or directory in the + way (or would be in the way of each other), "turn off" the directory + rename for those specific sub-paths and report the conflict to the + user. + + 3) If the other side of history did a directory rename to a path that + your side of history renamed away, then ignore that particular + rename from the other side of history for any implicit directory + renames (but warn the user). + +Limitations -- detailed rules and testcases +------------------------------------------- + +t/t6043-merge-rename-directories.sh contains extensive tests and commentary +which generate and explore the rules listed above. It also lists a few +additional rules: + + a) If renames split a directory into two or more others, the directory + with the most renames, "wins". + + b) Avoid directory-rename-detection for a path, if that path is the + source of a rename on either side of a merge. + + c) Only apply implicit directory renames to directories if the other side + of history is the one doing the renaming. + +Limitations -- support in different commands +-------------------------------------------- + +Directory rename detection is supported by 'merge' and 'cherry-pick'. +Other git commands which users might be surprised to see limited or no +directory rename detection support in: + + * diff + + Folks have requested in the past that `git diff` detect directory + renames and somehow simplify its output. It is not clear whether this + would be desirable or how the output should be simplified, so this was + simply not implemented. Further, to implement this, directory rename + detection logic would need to move from merge-recursive to + diffcore-rename. + + * am + + git-am tries to avoid a full three way merge, instead calling + git-apply. That prevents us from detecting renames at all, which may + defeat the directory rename detection. There is a fallback, though; if + the initial git-apply fails and the user has specified the -3 option, + git-am will fall back to a three way merge. However, git-am lacks the + necessary information to do a "real" three way merge. Instead, it has + to use build_fake_ancestor() to get a merge base that is missing files + whose rename may have been important to detect for directory rename + detection to function. + + * rebase + + Since am-based rebases work by first generating a bunch of patches + (which no longer record what the original commits were and thus don't + have the necessary info from which we can find a real merge-base), and + then calling git-am, this implies that am-based rebases will not always + successfully detect directory renames either (see the 'am' section + above). merged-based rebases (rebase -m) and cherry-pick-based rebases + (rebase -i) are not affected by this shortcoming, and fully support + directory rename detection. diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 4ab6cd1012..bc2ace2a6e 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -59,14 +59,11 @@ that are believed to be cryptographically secure. Goals ----- -Where NewHash is a strong 256-bit hash function to replace SHA-1 (see -"Selection of a New Hash", below): - -1. The transition to NewHash can be done one local repository at a time. +1. The transition to SHA-256 can be done one local repository at a time. a. Requiring no action by any other party. - b. A NewHash repository can communicate with SHA-1 Git servers + b. A SHA-256 repository can communicate with SHA-1 Git servers (push/fetch). - c. Users can use SHA-1 and NewHash identifiers for objects + c. Users can use SHA-1 and SHA-256 identifiers for objects interchangeably (see "Object names on the command line", below). d. New signed objects make use of a stronger hash function than SHA-1 for their security guarantees. @@ -79,7 +76,7 @@ Where NewHash is a strong 256-bit hash function to replace SHA-1 (see Non-Goals --------- -1. Add NewHash support to Git protocol. This is valuable and the +1. Add SHA-256 support to Git protocol. This is valuable and the logical next step but it is out of scope for this initial design. 2. Transparently improving the security of existing SHA-1 signed objects. @@ -87,26 +84,26 @@ Non-Goals repository. 4. Taking the opportunity to fix other bugs in Git's formats and protocols. -5. Shallow clones and fetches into a NewHash repository. (This will - change when we add NewHash support to Git protocol.) -6. Skip fetching some submodules of a project into a NewHash - repository. (This also depends on NewHash support in Git +5. Shallow clones and fetches into a SHA-256 repository. (This will + change when we add SHA-256 support to Git protocol.) +6. Skip fetching some submodules of a project into a SHA-256 + repository. (This also depends on SHA-256 support in Git protocol.) Overview -------- We introduce a new repository format extension. Repositories with this -extension enabled use NewHash instead of SHA-1 to name their objects. +extension enabled use SHA-256 instead of SHA-1 to name their objects. This affects both object names and object content --- both the names of objects and all references to other objects within an object are switched to the new hash function. -NewHash repositories cannot be read by older versions of Git. +SHA-256 repositories cannot be read by older versions of Git. -Alongside the packfile, a NewHash repository stores a bidirectional -mapping between NewHash and SHA-1 object names. The mapping is generated +Alongside the packfile, a SHA-256 repository stores a bidirectional +mapping between SHA-256 and SHA-1 object names. The mapping is generated locally and can be verified using "git fsck". Object lookups use this -mapping to allow naming objects using either their SHA-1 and NewHash names +mapping to allow naming objects using either their SHA-1 and SHA-256 names interchangeably. "git cat-file" and "git hash-object" gain options to display an object @@ -116,7 +113,7 @@ object database so that they can be named using the appropriate name (using the bidirectional hash mapping). Fetches from a SHA-1 based server convert the fetched objects into -NewHash form and record the mapping in the bidirectional mapping table +SHA-256 form and record the mapping in the bidirectional mapping table (see below for details). Pushes to a SHA-1 based server convert the objects being pushed into sha1 form so the server does not have to be aware of the hash function the client is using. @@ -125,19 +122,19 @@ Detailed Design --------------- Repository format extension ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A NewHash repository uses repository format version `1` (see +A SHA-256 repository uses repository format version `1` (see Documentation/technical/repository-version.txt) with extensions `objectFormat` and `compatObjectFormat`: [core] repositoryFormatVersion = 1 [extensions] - objectFormat = newhash + objectFormat = sha256 compatObjectFormat = sha1 The combination of setting `core.repositoryFormatVersion=1` and populating `extensions.*` ensures that all versions of Git later than -`v0.99.9l` will die instead of trying to operate on the NewHash +`v0.99.9l` will die instead of trying to operate on the SHA-256 repository, instead producing an error message. # Between v0.99.9l and v2.7.0 @@ -155,36 +152,36 @@ repository extensions. Object names ~~~~~~~~~~~~ Objects can be named by their 40 hexadecimal digit sha1-name or 64 -hexadecimal digit newhash-name, plus names derived from those (see +hexadecimal digit sha256-name, plus names derived from those (see gitrevisions(7)). The sha1-name of an object is the SHA-1 of the concatenation of its type, length, a nul byte, and the object's sha1-content. This is the traditional <sha1> used in Git to name objects. -The newhash-name of an object is the NewHash of the concatenation of its -type, length, a nul byte, and the object's newhash-content. +The sha256-name of an object is the SHA-256 of the concatenation of its +type, length, a nul byte, and the object's sha256-content. Object format ~~~~~~~~~~~~~ The content as a byte sequence of a tag, commit, or tree object named -by sha1 and newhash differ because an object named by newhash-name refers to -other objects by their newhash-names and an object named by sha1-name +by sha1 and sha256 differ because an object named by sha256-name refers to +other objects by their sha256-names and an object named by sha1-name refers to other objects by their sha1-names. -The newhash-content of an object is the same as its sha1-content, except -that objects referenced by the object are named using their newhash-names +The sha256-content of an object is the same as its sha1-content, except +that objects referenced by the object are named using their sha256-names instead of sha1-names. Because a blob object does not refer to any -other object, its sha1-content and newhash-content are the same. +other object, its sha1-content and sha256-content are the same. -The format allows round-trip conversion between newhash-content and +The format allows round-trip conversion between sha256-content and sha1-content. Object storage ~~~~~~~~~~~~~~ Loose objects use zlib compression and packed objects use the packed format described in Documentation/technical/pack-format.txt, just like -today. The content that is compressed and stored uses newhash-content +today. The content that is compressed and stored uses sha256-content instead of sha1-content. Pack index @@ -255,10 +252,10 @@ network byte order): up to and not including the table of CRC32 values. - Zero or more NUL bytes. - The trailer consists of the following: - - A copy of the 20-byte NewHash checksum at the end of the + - A copy of the 20-byte SHA-256 checksum at the end of the corresponding packfile. - - 20-byte NewHash checksum of all of the above. + - 20-byte SHA-256 checksum of all of the above. Loose object index ~~~~~~~~~~~~~~~~~~ @@ -266,7 +263,7 @@ A new file $GIT_OBJECT_DIR/loose-object-idx contains information about all loose objects. Its format is # loose-object-idx - (newhash-name SP sha1-name LF)* + (sha256-name SP sha1-name LF)* where the object names are in hexadecimal format. The file is not sorted. @@ -292,8 +289,8 @@ To remove entries (e.g. in "git pack-refs" or "git-prune"): Translation table ~~~~~~~~~~~~~~~~~ The index files support a bidirectional mapping between sha1-names -and newhash-names. The lookup proceeds similarly to ordinary object -lookups. For example, to convert a sha1-name to a newhash-name: +and sha256-names. The lookup proceeds similarly to ordinary object +lookups. For example, to convert a sha1-name to a sha256-name: 1. Look for the object in idx files. If a match is present in the idx's sorted list of truncated sha1-names, then: @@ -301,8 +298,8 @@ lookups. For example, to convert a sha1-name to a newhash-name: name order mapping. b. Read the corresponding entry in the full sha1-name table to verify we found the right object. If it is, then - c. Read the corresponding entry in the full newhash-name table. - That is the object's newhash-name. + c. Read the corresponding entry in the full sha256-name table. + That is the object's sha256-name. 2. Check for a loose object. Read lines from loose-object-idx until we find a match. @@ -318,25 +315,25 @@ for all objects in the object store. Reading an object's sha1-content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The sha1-content of an object can be read by converting all newhash-names -its newhash-content references to sha1-names using the translation table. +The sha1-content of an object can be read by converting all sha256-names +its sha256-content references to sha1-names using the translation table. Fetch ~~~~~ Fetching from a SHA-1 based server requires translating between SHA-1 -and NewHash based representations on the fly. +and SHA-256 based representations on the fly. SHA-1s named in the ref advertisement that are present on the client -can be translated to NewHash and looked up as local objects using the +can be translated to SHA-256 and looked up as local objects using the translation table. Negotiation proceeds as today. Any "have"s generated locally are converted to SHA-1 before being sent to the server, and SHA-1s -mentioned by the server are converted to NewHash when looking them up +mentioned by the server are converted to SHA-256 when looking them up locally. After negotiation, the server sends a packfile containing the -requested objects. We convert the packfile to NewHash format using +requested objects. We convert the packfile to SHA-256 format using the following steps: 1. index-pack: inflate each object in the packfile and compute its @@ -351,12 +348,12 @@ the following steps: (This list only contains objects reachable from the "wants". If the pack from the server contained additional extraneous objects, then they will be discarded.) -3. convert to newhash: open a new (newhash) packfile. Read the topologically +3. convert to sha256: open a new (sha256) packfile. Read the topologically sorted list just generated. For each object, inflate its - sha1-content, convert to newhash-content, and write it to the newhash - pack. Record the new sha1<->newhash mapping entry for use in the idx. + sha1-content, convert to sha256-content, and write it to the sha256 + pack. Record the new sha1<->sha256 mapping entry for use in the idx. 4. sort: reorder entries in the new pack to match the order of objects - in the pack the server generated and include blobs. Write a newhash idx + in the pack the server generated and include blobs. Write a sha256 idx file 5. clean up: remove the SHA-1 based pack file, index, and topologically sorted list obtained from the server in steps 1 @@ -388,16 +385,16 @@ send-pack. Signed Commits ~~~~~~~~~~~~~~ -We add a new field "gpgsig-newhash" to the commit object format to allow +We add a new field "gpgsig-sha256" to the commit object format to allow signing commits without relying on SHA-1. It is similar to the -existing "gpgsig" field. Its signed payload is the newhash-content of the -commit object with any "gpgsig" and "gpgsig-newhash" fields removed. +existing "gpgsig" field. Its signed payload is the sha256-content of the +commit object with any "gpgsig" and "gpgsig-sha256" fields removed. This means commits can be signed 1. using SHA-1 only, as in existing signed commit objects -2. using both SHA-1 and NewHash, by using both gpgsig-newhash and gpgsig +2. using both SHA-1 and SHA-256, by using both gpgsig-sha256 and gpgsig fields. -3. using only NewHash, by only using the gpgsig-newhash field. +3. using only SHA-256, by only using the gpgsig-sha256 field. Old versions of "git verify-commit" can verify the gpgsig signature in cases (1) and (2) without modifications and view case (3) as an @@ -405,24 +402,24 @@ ordinary unsigned commit. Signed Tags ~~~~~~~~~~~ -We add a new field "gpgsig-newhash" to the tag object format to allow +We add a new field "gpgsig-sha256" to the tag object format to allow signing tags without relying on SHA-1. Its signed payload is the -newhash-content of the tag with its gpgsig-newhash field and "-----BEGIN PGP +sha256-content of the tag with its gpgsig-sha256 field and "-----BEGIN PGP SIGNATURE-----" delimited in-body signature removed. This means tags can be signed 1. using SHA-1 only, as in existing signed tag objects -2. using both SHA-1 and NewHash, by using gpgsig-newhash and an in-body +2. using both SHA-1 and SHA-256, by using gpgsig-sha256 and an in-body signature. -3. using only NewHash, by only using the gpgsig-newhash field. +3. using only SHA-256, by only using the gpgsig-sha256 field. Mergetag embedding ~~~~~~~~~~~~~~~~~~ The mergetag field in the sha1-content of a commit contains the sha1-content of a tag that was merged by that commit. -The mergetag field in the newhash-content of the same commit contains the -newhash-content of the same tag. +The mergetag field in the sha256-content of the same commit contains the +sha256-content of the same tag. Submodules ~~~~~~~~~~ @@ -497,7 +494,7 @@ Caveats ------- Invalid objects ~~~~~~~~~~~~~~~ -The conversion from sha1-content to newhash-content retains any +The conversion from sha1-content to sha256-content retains any brokenness in the original object (e.g., tree entry modes encoded with leading 0, tree objects whose paths are not sorted correctly, and commit objects without an author or committer). This is a deliberate @@ -516,7 +513,7 @@ allow lifting this restriction. Alternates ~~~~~~~~~~ -For the same reason, a newhash repository cannot borrow objects from a +For the same reason, a sha256 repository cannot borrow objects from a sha1 repository using objects/info/alternates or $GIT_ALTERNATE_OBJECT_REPOSITORIES. @@ -524,20 +521,20 @@ git notes ~~~~~~~~~ The "git notes" tool annotates objects using their sha1-name as key. This design does not describe a way to migrate notes trees to use -newhash-names. That migration is expected to happen separately (for +sha256-names. That migration is expected to happen separately (for example using a file at the root of the notes tree to describe which hash it uses). Server-side cost ~~~~~~~~~~~~~~~~ -Until Git protocol gains NewHash support, using NewHash based storage +Until Git protocol gains SHA-256 support, using SHA-256 based storage on public-facing Git servers is strongly discouraged. Once Git -protocol gains NewHash support, NewHash based servers are likely not +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. The design described here allows fetches by SHA-1 clients of a -personal NewHash repository because it's not much more difficult than +personal SHA-256 repository because it's not much more difficult than allowing pushes from that repository. This support needs to be guarded by a configuration option --- servers like git.kernel.org that serve a large number of clients would not be expected to bear that cost. @@ -547,7 +544,7 @@ Meaning of signatures The signed payload for signed commits and tags does not explicitly name the hash used to identify objects. If some day Git adopts a new hash function with the same length as the current SHA-1 (40 -hexadecimal digit) or NewHash (64 hexadecimal digit) objects then the +hexadecimal digit) or SHA-256 (64 hexadecimal digit) objects then the intent behind the PGP signed payload in an object signature is unclear: @@ -562,7 +559,7 @@ Does this mean Git v2.12.0 is the commit with sha1-name e7e07d5a4fcc2a203d9873968ad3e6bd4d7419d7 or the commit with new-40-digit-hash-name e7e07d5a4fcc2a203d9873968ad3e6bd4d7419d7? -Fortunately NewHash and SHA-1 have different lengths. If Git starts +Fortunately SHA-256 and SHA-1 have different lengths. If Git starts using another hash with the same length to name objects, then it will need to change the format of signed payloads using that hash to address this issue. @@ -574,24 +571,24 @@ supports four different modes of operation: 1. ("dark launch") Treat object names input by the user as SHA-1 and convert any object names written to output to SHA-1, but store - objects using NewHash. This allows users to test the code with no + objects using SHA-256. This allows users to test the code with no visible behavior change except for performance. This allows allows running even tests that assume the SHA-1 hash function, to sanity-check the behavior of the new mode. - 2. ("early transition") Allow both SHA-1 and NewHash object names in + 2. ("early transition") Allow both SHA-1 and SHA-256 object names in input. Any object names written to output use SHA-1. This allows users to continue to make use of SHA-1 to communicate with peers (e.g. by email) that have not migrated yet and prepares for mode 3. - 3. ("late transition") Allow both SHA-1 and NewHash object names in - input. Any object names written to output use NewHash. In this + 3. ("late transition") Allow both SHA-1 and SHA-256 object names in + input. Any object names written to output use SHA-256. In this mode, users are using a more secure object naming method by default. The disruption is minimal as long as most of their peers are in mode 2 or mode 3. 4. ("post-transition") Treat object names input by the user as - NewHash and write output using NewHash. This is safer than mode 3 + SHA-256 and write output using SHA-256. This is safer than mode 3 because there is less risk that input is incorrectly interpreted using the wrong hash function. @@ -601,27 +598,31 @@ The user can also explicitly specify which format to use for a particular revision specifier and for output, overriding the mode. For example: -git --output-format=sha1 log abac87a^{sha1}..f787cac^{newhash} +git --output-format=sha1 log abac87a^{sha1}..f787cac^{sha256} -Selection of a New Hash ------------------------ +Choice of Hash +-------------- 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 published until 10 years later, in 2017. -The hash function NewHash to replace SHA-1 should be stronger than -SHA-1 was: we would like it to be trustworthy and useful in practice -for at least 10 years. +Git v2.13.0 and later subsequently moved to a hardened SHA-1 +implementation by default that mitigates the SHAttered attack, but +SHA-1 is still believed to be weak. + +The hash to replace this hardened SHA-1 should be stronger than SHA-1 +was: we would like it to be trustworthy and useful in practice for at +least 10 years. Some other relevant properties: 1. A 256-bit hash (long enough to match common security practice; not excessively long to hurt performance and disk usage). -2. High quality implementations should be widely available (e.g. in - OpenSSL). +2. High quality implementations should be widely available (e.g., in + OpenSSL and Apple CommonCrypto). 3. The hash function's properties should match Git's needs (e.g. Git requires collision and 2nd preimage resistance and does not require @@ -630,14 +631,13 @@ Some other relevant properties: 4. As a tiebreaker, the hash should be fast to compute (fortunately many contenders are faster than SHA-1). -Some hashes under consideration are SHA-256, SHA-512/256, SHA-256x16, -K12, and BLAKE2bp-256. +We choose SHA-256. Transition plan --------------- Some initial steps can be implemented independently of one another: - adding a hash function API (vtable) -- teaching fsck to tolerate the gpgsig-newhash field +- teaching fsck to tolerate the gpgsig-sha256 field - excluding gpgsig-* from the fields copied by "git commit --amend" - annotating tests that depend on SHA-1 values with a SHA1 test prerequisite @@ -664,7 +664,7 @@ Next comes introduction of compatObjectFormat: - adding appropriate index entries when adding a new object to the object store - --output-format option -- ^{sha1} and ^{newhash} revision notation +- ^{sha1} and ^{sha256} revision notation - configuration to specify default input and output format (see "Object names on the command line" above) @@ -672,7 +672,7 @@ The next step is supporting fetches and pushes to SHA-1 repositories: - allow pushes to a repository using the compat format - generate a topologically sorted list of the SHA-1 names of fetched objects -- convert the fetched packfile to newhash format and generate an idx +- convert the fetched packfile to sha256 format and generate an idx file - re-sort to match the order of objects in the fetched packfile @@ -680,30 +680,30 @@ The infrastructure supporting fetch also allows converting an existing repository. In converted repositories and new clones, end users can gain support for the new hash function without any visible change in behavior (see "dark launch" in the "Object names on the command line" -section). In particular this allows users to verify NewHash signatures +section). In particular this allows users to verify SHA-256 signatures on objects in the repository, and it should ensure the transition code is stable in production in preparation for using it more widely. Over time projects would encourage their users to adopt the "early transition" and then "late transition" modes to take advantage of the -new, more futureproof NewHash object names. +new, more futureproof SHA-256 object names. When objectFormat and compatObjectFormat are both set, commands -generating signatures would generate both SHA-1 and NewHash signatures +generating signatures would generate both SHA-1 and SHA-256 signatures by default to support both new and old users. -In projects using NewHash heavily, users could be encouraged to adopt +In projects using SHA-256 heavily, users could be encouraged to adopt the "post-transition" mode to avoid accidentally making implicit use of SHA-1 object names. Once a critical mass of users have upgraded to a version of Git that -can verify NewHash signatures and have converted their existing +can verify SHA-256 signatures and have converted their existing repositories to support verifying them, we can add support for a -setting to generate only NewHash signatures. This is expected to be at +setting to generate only SHA-256 signatures. This is expected to be at least a year later. That is also a good moment to advertise the ability to convert -repositories to use NewHash only, stripping out all SHA-1 related +repositories to use SHA-256 only, stripping out all SHA-1 related metadata. This improves performance by eliminating translation overhead and security by avoiding the possibility of accidentally relying on the safety of SHA-1. @@ -742,16 +742,16 @@ using the old hash function. Signed objects with multiple hashes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Instead of introducing the gpgsig-newhash field in commit and tag objects -for newhash-content based signatures, an earlier version of this design -added "hash newhash <newhash-name>" fields to strengthen the existing +Instead of introducing the gpgsig-sha256 field in commit and tag objects +for sha256-content based signatures, an earlier version of this design +added "hash sha256 <sha256-name>" fields to strengthen the existing sha1-content based signatures. In other words, a single signature was used to attest to the object content using both hash functions. This had some advantages: * Using one signature instead of two speeds up the signing process. * Having one signed payload with both hashes allows the signer to - attest to the sha1-name and newhash-name referring to the same object. + attest to the sha1-name and sha256-name referring to the same object. * All users consume the same signature. Broken signatures are likely to be detected quickly using current versions of git. @@ -760,11 +760,11 @@ However, it also came with disadvantages: objects it references, even after the transition is complete and translation table is no longer needed for anything else. To support this, the design added fields such as "hash sha1 tree <sha1-name>" - and "hash sha1 parent <sha1-name>" to the newhash-content of a signed + and "hash sha1 parent <sha1-name>" to the sha256-content of a signed commit, complicating the conversion process. * Allowing signed objects without a sha1 (for after the transition is complete) complicated the design further, requiring a "nohash sha1" - field to suppress including "hash sha1" fields in the newhash-content + field to suppress including "hash sha1" fields in the sha256-content and signed payload. Lazily populated translation table @@ -772,7 +772,7 @@ Lazily populated translation table Some of the work of building the translation table could be deferred to push time, but that would significantly complicate and slow down pushes. Calculating the sha1-name at object creation time at the same time it is -being streamed to disk and having its newhash-name calculated should be +being streamed to disk and having its sha256-name calculated should be an acceptable cost. Document History @@ -814,6 +814,12 @@ Incorporated suggestions from jonathantanmy and sbeller: * avoid loose object overhead by packing more aggressively in "git gc --auto" +Later history: + + See the history of this file in git.git for the history of subsequent + 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/ diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 64f49d0bbb..9c5b6f0fac 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -338,11 +338,11 @@ server advertises capability `allow-tip-sha1-in-want` or request_end request_end = "0000" / "done" - want_list = PKT-LINE(want NUL cap_list LF) + want_list = PKT-LINE(want SP cap_list LF) *(want_pkt) want_pkt = PKT-LINE(want LF) want = "want" SP id - cap_list = *(SP capability) SP + cap_list = capability *(SP capability) have_list = *PKT-LINE("have" SP id LF) diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index db3572626b..7c4d67aa6a 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 begining 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 begining 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 new file mode 100644 index 0000000000..d7e57639f7 --- /dev/null +++ b/Documentation/technical/multi-pack-index.txt @@ -0,0 +1,109 @@ +Multi-Pack-Index (MIDX) Design Notes +==================================== + +The Git object directory contains a 'pack' directory containing +packfiles (with suffix ".pack") and pack-indexes (with suffix +".idx"). The pack-indexes provide a way to lookup objects and +navigate to their offset within the pack, but these must come +in pairs with the packfiles. This pairing depends on the file +names, as the pack-index differs only in suffix with its pack- +file. While the pack-indexes provide fast lookup per packfile, +this performance degrades as the number of packfiles increases, +because abbreviations need to inspect every packfile and we are +more likely to have a miss on our most-recently-used packfile. +For some large repositories, repacking into a single packfile +is not feasible due to storage space or excessive repack times. + +The multi-pack-index (MIDX for short) stores a list of objects +and their offsets into multiple packfiles. It contains: + +- A list of packfile names. +- A sorted list of object IDs. +- A list of metadata for the ith object ID including: + - A value j referring to the jth packfile. + - An offset within the jth packfile for the object. +- If large offsets are required, we use another list of large + offsets similar to version 2 pack-indexes. + +Thus, we can provide O(log N) lookup time for any number +of packfiles. + +Design Details +-------------- + +- The MIDX is stored in a file named 'multi-pack-index' in the + .git/objects/pack directory. This could be stored in the pack + 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 file format includes parameters for the object ID hash + function, so a future change of hash algorithm does not require + a change in format. + +- The MIDX keeps only one record per object ID. If an object appears + in multiple packfiles, then the MIDX selects the copy in the most- + recently modified packfile. + +- If there exist packfiles in the pack directory not registered in + the MIDX, then those packfiles are loaded into the `packed_git` + list and `packed_git_mru` cache. + +- The pack-indexes (.idx files) remain in the pack directory so we + can delete the MIDX file, set core.midx to false, or downgrade + without any loss of information. + +- The MIDX file format uses a chunk-based approach (similar to the + commit-graph file) that allows optional data to be added. + +Future Work +----------- + +- Add a 'verify' subcommand to the 'git midx' builtin to verify the + contents of the multi-pack-index file match the offsets listed in + the corresponding pack-indexes. + +- The multi-pack-index allows many packfiles, especially in a context + where repacking is expensive (such as a very large repo), or + unexpected maintenance time is unacceptable (such as a high-demand + build machine). However, the multi-pack-index needs to be rewritten + in full every time. We can extend the format to be incremental, so + writes are fast. By storing a small "tip" multi-pack-index that + points to large "base" MIDX files, we can keep writes fast while + still reducing the number of binary searches required for object + lookups. + +- The reachability bitmap is currently paired directly with a single + packfile, using the pack-order as the object order to hopefully + compress the bitmaps well using run-length encoding. This could be + extended to pair a reachability bitmap with a multi-pack-index. If + the multi-pack-index is extended to store a "stable object order" + (a function Order(hash) = integer that is constant for a given hash, + even as the multi-pack-index is updated) then a reachability bitmap + could point to a multi-pack-index and be updated independently. + +- Packfiles can be marked as "special" using empty files that share + the initial name but replace ".pack" with ".keep" or ".promisor". + We can add an optional chunk of data to the multi-pack-index that + records flags of information about the packfiles. This allows new + states, such as 'repacked' or 'redeltified', that can help with + pack maintenance in a multi-pack environment. It may also be + helpful to organize packfiles by object type (commit, tree, blob, + etc.) and use this metadata to help that maintenance. + +- The partial clone feature records special "promisor" packs that + may point to objects that are not stored locally, but available + on request to a server. The multi-pack-index does not currently + track these promisor packs. + +Related Links +------------- +[0] https://bugs.chromium.org/p/git/issues/detail?id=6 + Chromium work item for: Multi-Pack Index (MIDX) + +[1] https://public-inbox.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/ + 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 70a99fd142..cab5bdd2ff 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -252,3 +252,80 @@ Pack file entry: <+ corresponding packfile. 20-byte SHA-1-checksum of all of the above. + +== multi-pack-index (MIDX) files have the following format: + +The multi-pack-index files refer to multiple pack-files and loose objects. + +In order to allow extensions that add extra data to the MIDX, we organize +the body into "chunks" and provide a lookup table at the beginning of the +body. The header includes certain length values, such as the number of packs, +the number of base MIDX files, hash lengths and types. + +All 4-byte numbers are in network order. + +HEADER: + + 4-byte signature: + The signature is: {'M', 'I', 'D', 'X'} + + 1-byte version number: + Git only writes or recognizes version 1. + + 1-byte Object Id Version + Git only writes or recognizes version 1 (SHA1). + + 1-byte number of "chunks" + + 1-byte number of base multi-pack-index files: + This value is currently always zero. + + 4-byte number of pack files + +CHUNK LOOKUP: + + (C + 1) * 12 bytes providing the chunk offsets: + First 4 bytes describe chunk id. Value 0 is a terminating label. + Other 8 bytes provide offset in current file for chunk to start. + (Chunks are provided in file-order, so you can infer the length + using the next chunk position if necessary.) + + The remaining data in the body is described one chunk at a time, and + these chunks may be given in any order. Chunks are required unless + otherwise specified. + +CHUNK DATA: + + Packfile Names (ID: {'P', 'N', 'A', 'M'}) + Stores the packfile names as concatenated, null-terminated strings. + Packfiles must be listed in lexicographic order for fast lookups by + name. This is the only chunk not guaranteed to be a multiple of four + bytes in length, so should be the last chunk for alignment reasons. + + OID Fanout (ID: {'O', 'I', 'D', 'F'}) + The ith entry, F[i], stores the number of OIDs with first + byte at most i. Thus F[255] stores the total + number of objects. + + OID Lookup (ID: {'O', 'I', 'D', 'L'}) + The OIDs for all objects in the MIDX are stored in lexicographic + order in this chunk. + + Object Offsets (ID: {'O', 'O', 'F', 'F'}) + 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 + 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 + 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. + + [Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'}) + 8-byte offsets into large packfiles. + +TRAILER: + + 20-byte SHA1-checksum of the above contents. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 7fee6b780a..c73e72de0e 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 @@ -50,7 +60,8 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is -"version=1". +"version" with a value of '1' or '2'. See protocol-v2.txt for more +information on protocol version 2. Git Transport ------------- @@ -88,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 ------------- @@ -284,7 +288,9 @@ information is sent back to the client in the next step. The client can optionally request that pack-objects omit various objects from the packfile 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. +operations. An object that does not meet a filter-spec value is +omitted unless explicitly requested in a 'want' line. See `rev-list` +for possible filter-spec values. Once all the 'want's and 'shallow's (and optional 'deepen') are transferred, clients MUST send a flush-pkt, to tell the server side @@ -395,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): @@ -652,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 0bed2472c8..896c7b3878 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -69,24 +69,24 @@ Design Details - A new pack-protocol capability "filter" is added to the fetch-pack and upload-pack negotiation. - - This uses the existing capability discovery mechanism. - See "filter" in Documentation/technical/pack-protocol.txt. ++ +This uses the existing capability discovery mechanism. +See "filter" in Documentation/technical/pack-protocol.txt. - Clients pass a "filter-spec" to clone and fetch which is passed to the server to request filtering during packfile construction. - - There are various filters available to accommodate different situations. - See "--filter=<filter-spec>" in Documentation/rev-list-options.txt. ++ +There are various filters available to accommodate different situations. +See "--filter=<filter-spec>" in Documentation/rev-list-options.txt. - On the server pack-objects applies the requested filter-spec as it creates "filtered" packfiles for the client. - - These filtered packfiles are *incomplete* in the traditional sense because - they may contain objects that reference objects not contained in the - packfile and that the client doesn't already have. For example, the - filtered packfile may contain trees or tags that reference missing blobs - or commits that reference missing trees. ++ +These filtered packfiles are *incomplete* in the traditional sense because +they may contain objects that reference objects not contained in the +packfile and that the client doesn't already have. For example, the +filtered packfile may contain trees or tags that reference missing blobs +or commits that reference missing trees. - On the client these incomplete packfiles are marked as "promisor packfiles" and treated differently by various commands. @@ -104,47 +104,47 @@ Handling Missing Objects to repository corruption. To differentiate these cases, the local repository specially indicates such filtered packfiles obtained from the promisor remote 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. ++ +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 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 - 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 - expensive-to-modify list of missing objects.[a] ++ +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 +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. - - 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. - - For efficiency reasons, no check as to whether the missing object is - actually a promisor object is performed. - - Dynamic object fetching tends to be slow as objects are fetched one at - a time. ++ +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. ++ +For efficiency reasons, no check as to whether the missing object is +actually a promisor object is performed. ++ +Dynamic object fetching tends to be slow as objects are fetched one at +a time. - `checkout` (and any other command using `unpack-trees`) has been taught to bulk pre-fetch all required missing blobs in a single batch. - `rev-list` has been taught to print missing objects. - - This can be used by other commands to bulk prefetch objects. - For example, a "git log -p A..B" may internally want to first do - something like "git rev-list --objects --quiet --missing=print A..B" - and prefetch those objects in bulk. ++ +This can be used by other commands to bulk prefetch objects. +For example, a "git log -p A..B" may internally want to first do +something like "git rev-list --objects --quiet --missing=print A..B" +and prefetch those objects in bulk. - `fsck` has been updated to be fully aware of promisor objects. @@ -154,11 +154,11 @@ Handling Missing Objects - The global variable "fetch_if_missing" is used to control whether an object lookup will attempt to dynamically fetch a missing object or report an error. - - 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. ++ +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. Fetching Missing Objects @@ -168,10 +168,10 @@ Fetching Missing Objects transport_fetch_refs(), setting a new transport option TRANS_OPT_NO_DEPENDENTS to indicate that only the objects themselves are desired, not any object that they refer to. - - Because some transports invoke fetch_pack() in the same process, fetch_pack() - has been updated to not use any object flags when the corresponding argument - (no_dependents) is set. ++ +Because some transports invoke fetch_pack() in the same process, fetch_pack() +has been updated to not use any object flags when the corresponding argument +(no_dependents) is set. - The local repository sends a request with the hashes of all requested objects as "want" lines, and does not perform any packfile negotiation. @@ -187,13 +187,13 @@ Current Limitations - The remote used for a partial clone (or the first partial fetch following a regular clone) is marked as the "promisor remote". - - We are currently limited to a single promisor remote and only that - remote may be used for subsequent partial fetches. - - We accept this limitation because we believe initial users of this - feature will be using it on repositories with a strong single central - server. ++ +We are currently limited to a single promisor remote and only that +remote may be used for subsequent partial fetches. ++ +We accept this limitation because we believe initial users of this +feature will be using it on repositories with a strong single central +server. - Dynamic object fetching will only ask the promisor remote for missing objects. We assume that the promisor remote has a complete view of the @@ -221,13 +221,13 @@ 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. - - 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. - - Or the user might want to work in a triangular work flow with multiple - promisor remotes that each have an incomplete view of the repository. ++ +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. ++ +Or 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 from non-promisor packfiles). @@ -238,25 +238,25 @@ Future Work - Investigate use of a long-running process to dynamically fetch a series of objects, such as proposed in [5,6] to reduce process startup and overhead costs. - - It would be nice if pack protocol V2 could allow that long-running - process to make a series of requests over a single long-running - connection. ++ +It would be nice if pack protocol V2 could allow that long-running +process to make a series of requests over a single long-running +connection. - Investigate pack protocol V2 to avoid the info/refs broadcast on each connection with the server to dynamically fetch missing objects. - Investigate the need to handle loose promisor objects. - - Objects in promisor packfiles are allowed to reference missing objects - that can be dynamically fetched from the server. An assumption was - made that loose objects are only created locally and therefore should - not reference a missing object. We may need to revisit that assumption - if, for example, we dynamically fetch a missing tree and store it as a - loose object rather than a single object packfile. - - This does not necessarily mean we need to mark loose objects as promisor; - it may be sufficient to relax the object lookup or is-promisor functions. ++ +Objects in promisor packfiles are allowed to reference missing objects +that can be dynamically fetched from the server. An assumption was +made that loose objects are only created locally and therefore should +not reference a missing object. We may need to revisit that assumption +if, for example, we dynamically fetch a missing tree and store it as a +loose object rather than a single object packfile. ++ +This does not necessarily mean we need to mark loose objects as promisor; +it may be sufficient to relax the object lookup or is-promisor functions. Non-Tasks @@ -265,13 +265,13 @@ Non-Tasks - Every time the subject of "demand loading blobs" comes up it seems that someone suggests that the server be allowed to "guess" and send additional objects that may be related to the requested objects. - - No work has gone into actually doing that; we're just documenting that - it is a common suggestion. We're not sure how it would work and have - no plans to work on it. - - It is valid for the server to send more objects than requested (even - for a dynamic object fetch), but we are not building on that. ++ +No work has gone into actually doing that; we're just documenting that +it is a common suggestion. We're not sure how it would work and have +no plans to work on it. ++ +It is valid for the server to send more objects than requested (even +for a dynamic object fetch), but we are not building on that. Footnotes @@ -282,43 +282,43 @@ Footnotes This would essentially be a sorted linear list of OIDs that the were omitted by the server during a clone or subsequent fetches. - This file would need to be loaded into memory on every object lookup. - It would need to be read, updated, and re-written (like the .git/index) - on every explicit "git fetch" command *and* on any dynamic object fetch. +This file would need to be loaded into memory on every object lookup. +It would need to be read, updated, and re-written (like the .git/index) +on every explicit "git fetch" command *and* on any dynamic object fetch. - The cost to read, update, and write this file could add significant - overhead to every command if there are many missing objects. For example, - if there are 100M missing blobs, this file would be at least 2GiB on disk. +The cost to read, update, and write this file could add significant +overhead to every command if there are many missing objects. For example, +if there are 100M missing blobs, this file would be at least 2GiB on disk. - With the "promisor" concept, we *infer* a missing object based upon the - type of packfile that references it. +With the "promisor" concept, we *infer* a missing object based upon the +type of packfile that references it. Related Links ------------- -[0] https://bugs.chromium.org/p/git/issues/detail?id=2 - Chromium work item for: Partial Clone +[0] https://crbug.com/git/2 + Bug#2: Partial Clone -[1] https://public-inbox.org/git/20170113155253.1644-1-benpeart@microsoft.com/ - Subject: [RFC] Add support for downloading blobs on demand +[1] https://public-inbox.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/ - Subject: [PATCH 00/18] Partial clone (from clone to lazy fetch in 18 patches) +[2] https://public-inbox.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/ - Subject: Proposal for missing blob support in Git repos +[3] https://public-inbox.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/ - Subject: [PATCH 00/10] RFC Partial Clone and Fetch +[4] https://public-inbox.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/ - Subject: [PATCH v7 00/10] refactor the filter process code into a reusable module +[5] https://public-inbox.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/ - Subject: [RFC/PATCH v2 0/1] Add support for downloading blobs on demand +[6] https://public-inbox.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 49bda76d23..03264c7d9a 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,30 +43,29 @@ 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 v2 be used by supplying "version=2" in the `Git-Protocol` header. - C: Git-Protocol: version=2 - C: C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 + C: Git-Protocol: version=2 A v2 server would reply: @@ -80,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 @@ -102,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 @@ -138,8 +137,8 @@ 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 @@ -154,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 @@ -169,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 @@ -200,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 @@ -297,14 +296,39 @@ 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 +the 'wanted-refs' section in the server's response as explained below. + + want-ref <ref> + Indicates to the server that the client wants to retrieve a + particular ref, where <ref> is the full name of a ref on the + server. + +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. output = *section - section = (acknowledgments | shallow-info | packfile) + section = (acknowledgments | shallow-info | wanted-refs | packfile) (flush-pkt | delim-pkt) acknowledgments = PKT-LINE("acknowledgments" LF) @@ -319,6 +343,10 @@ header. shallow = "shallow" SP obj-id unshallow = "unshallow" SP obj-id + wanted-refs = PKT-LINE("wanted-refs" LF) + *PKT-LINE(wanted-ref LF) + wanted-ref = obj-id SP refname + packfile = PKT-LINE("packfile" LF) *PKT-LINE(%x01-03 *%x00-ff) @@ -379,6 +407,19 @@ header. * This section is only included if a packfile section is also included in the response. + wanted-refs section + * This section is only included if the client has requested a + ref using a 'want-ref' line and if a packfile section is also + included in the response. + + * Always begins with the section header "wanted-refs". + + * The server will send a ref listing ("<oid> <refname>") for + each reference requested using 'want-ref' lines. + + * The server MUST NOT send any refs which were not requested + using 'want-ref' lines. + packfile section * This section is only included if the client has sent 'want' lines in its request and either requested that no more @@ -403,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/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..aa22d7ace8 --- /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 becames 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..27d3c64e66 --- /dev/null +++ b/Documentation/trace2-target-values.txt @@ -0,0 +1,10 @@ +-- +* `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. +* `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..bc354fe2dc 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -62,7 +62,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 |