diff options
Diffstat (limited to 'Documentation')
114 files changed, 2900 insertions, 468 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index ed4e443a3c..a89e8dcfbc 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -91,16 +91,10 @@ For shell scripts specifically (not exhaustive): - No shell arrays. - - No strlen ${#parameter}. - - No pattern replacement ${parameter/pattern/string}. - We use Arithmetic Expansion $(( ... )). - - Inside Arithmetic Expansion, spell shell variables with $ in front - of them, as some shells do not grok $((x)) while accepting $(($x)) - just fine (e.g. dash older than 0.5.4). - - We do not use Process Substitution <(list) or >(list). - Do not write control structures on a single line with semicolon. diff --git a/Documentation/Makefile b/Documentation/Makefile index 8fe829cc1b..15d9d04f31 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -30,6 +30,7 @@ MAN7_TXT += gitcredentials.txt MAN7_TXT += gitcvs-migration.txt MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.txt +MAN7_TXT += gitfaq.txt MAN7_TXT += gitglossary.txt MAN7_TXT += gitnamespaces.txt MAN7_TXT += gitremote-helpers.txt @@ -149,32 +150,9 @@ endif -include ../config.mak.autogen -include ../config.mak -# -# For docbook-xsl ... -# -1.68.1, no extra settings are needed? -# 1.69.0, set ASCIIDOC_ROFF? -# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? -# 1.71.1, set ASCIIDOC_ROFF? -# 1.72.0, set DOCBOOK_XSL_172. -# 1.73.0-, no extra settings are needed -# - -ifdef DOCBOOK_XSL_172 -ASCIIDOC_EXTRA += -a git-asciidoc-no-roff -MANPAGE_XSL = manpage-1.72.xsl -else - ifndef ASCIIDOC_ROFF - # docbook-xsl after 1.72 needs the regular XSL, but will not - # pass-thru raw roff codes from asciidoc.conf, so turn them off. - ASCIIDOC_EXTRA += -a git-asciidoc-no-roff - endif -endif ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif -ifdef DOCBOOK_SUPPRESS_SP -XMLTO_EXTRA += -m manpage-suppress-sp.xsl -endif # Newer DocBook stylesheet emits warning cruft in the output when # this is not set, and if set it shows an absolute link. Older diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 35b9130aa3..427274df4d 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -23,6 +23,42 @@ useful additional context: - `Documentation/SubmittingPatches` - `Documentation/howto/new-command.txt` +[[getting-help]] +=== Getting Help + +If you get stuck, you can seek help in the following places. + +==== git@vger.kernel.org + +This is the main Git project mailing list where code reviews, version +announcements, design discussions, and more take place. Those interested in +contributing are welcome to post questions here. The Git list requires +plain-text-only emails and prefers inline and bottom-posting when replying to +mail; you will be CC'd in all replies to you. Optionally, you can subscribe to +the list by sending an email to majordomo@vger.kernel.org with "subscribe git" +in the body. The https://lore.kernel.org/git[archive] of this mailing list is +available to view in a browser. + +==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] + +This mailing list is targeted to new contributors and was created as a place to +post questions and receive answers outside of the public eye of the main list. +Veteran contributors who are especially interested in helping mentor newcomers +are present on the list. In order to avoid search indexers, group membership is +required to view messages; anyone can join and no approval is required. + +==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode + +This IRC channel is for conversations between Git contributors. If someone is +currently online and knows the answer to your question, you can receive help +in real time. Otherwise, you can read the +https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see +whether someone answered you. IRC does not allow offline private messaging, so +if you try to private message someone and then log out of IRC, they cannot +respond to you. It's better to ask your questions in the channel so that you +can be answered if you disconnect and so that others can learn from the +conversation. + [[getting-started]] == Getting Started diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index aa828dfdc4..c3f2d1a831 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -357,9 +357,6 @@ static void walken_commit_walk(struct rev_info *rev) ... while ((commit = get_revision(rev))) { - if (!commit) - continue; - strbuf_reset(&prettybuf); pp_commit_easy(CMIT_FMT_ONELINE, commit, &prettybuf); puts(prettybuf.buf); diff --git a/Documentation/RelNotes/2.17.4.txt b/Documentation/RelNotes/2.17.4.txt new file mode 100644 index 0000000000..7d794ca01a --- /dev/null +++ b/Documentation/RelNotes/2.17.4.txt @@ -0,0 +1,16 @@ +Git v2.17.4 Release Notes +========================= + +This release is to address the security issue: CVE-2020-5260 + +Fixes since v2.17.3 +------------------- + + * With a crafted URL that contains a newline in it, the credential + helper machinery can be fooled to give credential information for + a wrong host. The attack has been made impossible by forbidding + a newline character in any value passed via the credential + protocol. + +Credit for finding the vulnerability goes to Felix Wilhelm of Google +Project Zero. diff --git a/Documentation/RelNotes/2.17.5.txt b/Documentation/RelNotes/2.17.5.txt new file mode 100644 index 0000000000..2abb821a73 --- /dev/null +++ b/Documentation/RelNotes/2.17.5.txt @@ -0,0 +1,22 @@ +Git v2.17.5 Release Notes +========================= + +This release is to address a security issue: CVE-2020-11008 + +Fixes since v2.17.4 +------------------- + + * With a crafted URL that contains a newline or empty host, or lacks + a scheme, the credential helper machinery can be fooled into + providing credential information that is not appropriate for the + protocol in use and host being contacted. + + Unlike the vulnerability CVE-2020-5260 fixed in v2.17.4, the + credentials are not for a host of the attacker's choosing; instead, + they are for some unspecified host (based on how the configured + credential helper handles an absent "host" parameter). + + The attack has been made impossible by refusing to work with + under-specified credential patterns. + +Credit for finding the vulnerability goes to Carlo Arenas. diff --git a/Documentation/RelNotes/2.18.3.txt b/Documentation/RelNotes/2.18.3.txt new file mode 100644 index 0000000000..25143f0cec --- /dev/null +++ b/Documentation/RelNotes/2.18.3.txt @@ -0,0 +1,5 @@ +Git v2.18.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.18.4.txt b/Documentation/RelNotes/2.18.4.txt new file mode 100644 index 0000000000..e8ef858a00 --- /dev/null +++ b/Documentation/RelNotes/2.18.4.txt @@ -0,0 +1,5 @@ +Git v2.18.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.19.4.txt b/Documentation/RelNotes/2.19.4.txt new file mode 100644 index 0000000000..35d0ae561b --- /dev/null +++ b/Documentation/RelNotes/2.19.4.txt @@ -0,0 +1,5 @@ +Git v2.19.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.19.5.txt b/Documentation/RelNotes/2.19.5.txt new file mode 100644 index 0000000000..18a4dcbfd6 --- /dev/null +++ b/Documentation/RelNotes/2.19.5.txt @@ -0,0 +1,5 @@ +Git v2.19.5 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.20.3.txt b/Documentation/RelNotes/2.20.3.txt new file mode 100644 index 0000000000..f6eccd103b --- /dev/null +++ b/Documentation/RelNotes/2.20.3.txt @@ -0,0 +1,5 @@ +Git v2.20.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.20.4.txt b/Documentation/RelNotes/2.20.4.txt new file mode 100644 index 0000000000..5a9e24e470 --- /dev/null +++ b/Documentation/RelNotes/2.20.4.txt @@ -0,0 +1,5 @@ +Git v2.20.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.21.2.txt b/Documentation/RelNotes/2.21.2.txt new file mode 100644 index 0000000000..a0fb83bb53 --- /dev/null +++ b/Documentation/RelNotes/2.21.2.txt @@ -0,0 +1,5 @@ +Git v2.21.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.21.3.txt b/Documentation/RelNotes/2.21.3.txt new file mode 100644 index 0000000000..2ca0aa5c62 --- /dev/null +++ b/Documentation/RelNotes/2.21.3.txt @@ -0,0 +1,5 @@ +Git v2.21.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.22.3.txt b/Documentation/RelNotes/2.22.3.txt new file mode 100644 index 0000000000..57296f6d17 --- /dev/null +++ b/Documentation/RelNotes/2.22.3.txt @@ -0,0 +1,5 @@ +Git v2.22.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.22.4.txt b/Documentation/RelNotes/2.22.4.txt new file mode 100644 index 0000000000..8b5f3e3f37 --- /dev/null +++ b/Documentation/RelNotes/2.22.4.txt @@ -0,0 +1,5 @@ +Git v2.22.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.23.2.txt b/Documentation/RelNotes/2.23.2.txt new file mode 100644 index 0000000000..b697cbe0e3 --- /dev/null +++ b/Documentation/RelNotes/2.23.2.txt @@ -0,0 +1,5 @@ +Git v2.23.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.23.3.txt b/Documentation/RelNotes/2.23.3.txt new file mode 100644 index 0000000000..2e35490137 --- /dev/null +++ b/Documentation/RelNotes/2.23.3.txt @@ -0,0 +1,5 @@ +Git v2.23.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.24.2.txt b/Documentation/RelNotes/2.24.2.txt new file mode 100644 index 0000000000..0049f65503 --- /dev/null +++ b/Documentation/RelNotes/2.24.2.txt @@ -0,0 +1,5 @@ +Git v2.24.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.24.3.txt b/Documentation/RelNotes/2.24.3.txt new file mode 100644 index 0000000000..5302e0f73b --- /dev/null +++ b/Documentation/RelNotes/2.24.3.txt @@ -0,0 +1,5 @@ +Git v2.24.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.25.1.txt b/Documentation/RelNotes/2.25.1.txt new file mode 100644 index 0000000000..cd869b02bb --- /dev/null +++ b/Documentation/RelNotes/2.25.1.txt @@ -0,0 +1,55 @@ +Git 2.25.1 Release Notes +======================== + +Fixes since v2.25 +----------------- + + * "git commit" gives output similar to "git status" when there is + nothing to commit, but without honoring the advise.statusHints + configuration variable, which has been corrected. + + * has_object_file() said "no" given an object registered to the + system via pretend_object_file(), making it inconsistent with + read_object_file(), causing lazy fetch to attempt fetching an + empty tree from promisor remotes. + + * The code that tries to skip over the entries for the paths in a + single directory using the cache-tree was not careful enough + against corrupt index file. + + * Complete an update to tutorial that encourages "git switch" over + "git checkout" that was done only half-way. + + * Reduce unnecessary round-trip when running "ls-remote" over the + stateless RPC mechanism. + + * "git restore --staged" did not correctly update the cache-tree + structure, resulting in bogus trees to be written afterwards, which + has been corrected. + + * The code recently added to move to the entry beyond the ones in the + same directory in the index in the sparse-cone mode did not count + the number of entries to skip over incorrectly, which has been + corrected. + + * Work around test breakages caused by custom regex engine used in + libasan, when address sanitizer is used with more recent versions + of gcc and clang. + + * "git fetch --refmap=" option has got a better documentation. + + * Corner case bugs in "git clean" that stems from a (necessarily for + performance reasons) awkward calling convention in the directory + enumeration API has been corrected. + + * "git grep --no-index" should not get affected by the contents of + the .gitmodules file but when "--recurse-submodules" is given or + the "submodule.recurse" variable is set, it did. Now these + settings are ignored in the "--no-index" mode. + + * Technical details of the bundle format has been documented. + + * Unhelpful warning messages during documentation build have been + squelched. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.25.2.txt b/Documentation/RelNotes/2.25.2.txt new file mode 100644 index 0000000000..303c53a17f --- /dev/null +++ b/Documentation/RelNotes/2.25.2.txt @@ -0,0 +1,60 @@ +Git 2.25.2 Release Notes +======================== + +Fixes since v2.25.1 +------------------- + + * Minor bugfixes to "git add -i" that has recently been rewritten in C. + + * An earlier update to show the location of working tree in the error + message did not consider the possibility that a git command may be + run in a bare repository, which has been corrected. + + * The "--recurse-submodules" option of various subcommands did not + work well when run in an alternate worktree, which has been + corrected. + + * Running "git rm" on a submodule failed unnecessarily when + .gitmodules is only cache-dirty, which has been corrected. + + * "git rebase -i" identifies existing commits in its todo file with + their abbreviated object name, which could become ambigous as it + goes to create new commits, and has a mechanism to avoid ambiguity + in the main part of its execution. A few other cases however were + not covered by the protection against ambiguity, which has been + corrected. + + * The index-pack code now diagnoses a bad input packstream that + records the same object twice when it is used as delta base; the + code used to declare a software bug when encountering such an + input, but it is an input error. + + * The code to automatically shrink the fan-out in the notes tree had + an off-by-one bug, which has been killed. + + * "git check-ignore" did not work when the given path is explicitly + marked as not ignored with a negative entry in the .gitignore file. + + * The merge-recursive machinery failed to refresh the cache entry for + a merge result in a couple of places, resulting in an unnecessary + merge failure, which has been fixed. + + * Fix for a bug revealed by a recent change to make the protocol v2 + the default. + + * "git merge signed-tag" while lacking the public key started to say + "No signature", which was utterly wrong. This regression has been + reverted. + + * MinGW's poll() emulation has been improved. + + * "git show" and others gave an object name in raw format in its + error output, which has been corrected to give it in hex. + + * Both "git ls-remote -h" and "git grep -h" give short usage help, + like any other Git subcommand, but it is not unreasonable to expect + that the former would behave the same as "git ls-remote --head" + (there is no other sensible behaviour for the latter). The + documentation has been updated in an attempt to clarify this. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.25.3.txt b/Documentation/RelNotes/2.25.3.txt new file mode 100644 index 0000000000..15f7f21f10 --- /dev/null +++ b/Documentation/RelNotes/2.25.3.txt @@ -0,0 +1,5 @@ +Git v2.25.3 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.25.4.txt b/Documentation/RelNotes/2.25.4.txt new file mode 100644 index 0000000000..0dbb5daeec --- /dev/null +++ b/Documentation/RelNotes/2.25.4.txt @@ -0,0 +1,5 @@ +Git v2.25.4 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.26.0.txt b/Documentation/RelNotes/2.26.0.txt new file mode 100644 index 0000000000..3a7a734c26 --- /dev/null +++ b/Documentation/RelNotes/2.26.0.txt @@ -0,0 +1,341 @@ +Git 2.26 Release Notes +====================== + +Updates since v2.25 +------------------- + +Backward compatibility notes + + * "git rebase" uses a different backend that is based on the 'merge' + machinery by default. There are a few known differences in the + behaviour from the traditional machinery based on patch+apply. + + If your workflow is negatively affected by this change, please + report it to git@vger.kernel.org so that we can take a look into + it. After doing so, you can set the 'rebase.backend' configuration + variable to 'apply', in order to use the old default behaviour in + the meantime. + + +UI, Workflows & Features + + * Sample credential helper for using .netrc has been updated to work + out of the box. + + * gpg.minTrustLevel configuration variable has been introduced to + tell various signature verification codepaths the required minimum + trust level. + + * The command line completion (in contrib/) learned to complete + subcommands and arguments to "git worktree". + + * Disambiguation logic to tell revisions and pathspec apart has been + tweaked so that backslash-escaped glob special characters do not + count in the "wildcards are pathspec" rule. + + * One effect of specifying where the GIT_DIR is (either with the + environment variable, or with the "git --git-dir=<where> cmd" + option) is to disable the repository discovery. This has been + placed a bit more stress in the documentation, as new users often + get confused. + + * Two help messages given when "git add" notices the user gave it + nothing to add have been updated to use advise() API. + + * A new version of fsmonitor-watchman hook has been introduced, to + avoid races. + + * "git config" learned to show in which "scope", in addition to in + which file, each config setting comes from. + + * The basic 7 colors learned the brighter counterparts + (e.g. "brightred"). + + * "git sparse-checkout" learned a new "add" subcommand. + + * A configuration element used for credential subsystem can now use + wildcard pattern to specify for which set of URLs the entry + applies. + + * "git clone --recurse-submodules --single-branch" now uses the same + single-branch option when cloning the submodules. + + * "git rm" and "git stash" learns the new "--pathspec-from-file" + option. + + * "git am --show-current-patch" is a way to show the piece of e-mail + for the stopped step, which is not suitable to directly feed "git + apply" (it is designed to be a good "git am" input). It learned a + new option to show only the patch part. + + * Handling of conflicting renames in merge-recursive have further + been made consistent with how existing codepaths try to mimic what + is done to add/add conflicts. + + +Performance, Internal Implementation, Development Support etc. + + * Tell .editorconfig that in this project, *.txt files are indented + with tabs. + + * The test-lint machinery knew to check "VAR=VAL shell_function" + construct, but did not check "VAR= shell_function", which has been + corrected. + + * Replace "git config --bool" calls with "git config --type=bool" in + sample templates. + + * The effort to move "git-add--interactive" to C continues. + + * Improve error message generation for "git submodule add". + + * Preparation of test scripts for the day when the object names will + use SHA-256 continues. + + * Warn programmers about pretend_object_file() that allows the code + to tentatively use in-core objects. + + * The way "git pack-objects" reuses objects stored in existing pack + to generate its result has been improved. + + * The transport protocol version 2 becomes the default one. + + * Traditionally, we avoided threaded grep while searching in objects + (as opposed to files in the working tree) as accesses to the object + layer is not thread-safe. This limitation is getting lifted. + + * "git rebase -i" (and friends) used to unnecessarily check out the + tip of the branch to be rebased, which has been corrected. + + * A low-level API function get_oid(), that accepts various ways to + name an object, used to issue end-user facing error messages + without l10n, which has been updated to be translatable. + + * Unneeded connectivity check is now disabled in a partial clone when + fetching into it. + + * Some rough edges in the sparse-checkout feature, especially around + the cone mode, have been cleaned up. + + * The diff-* plumbing family of subcommands now pay attention to the + diff.wsErrorHighlight configuration, which has been ignored before; + this allows "git add -p" to also show the whitespace problems to + the end user. + + * Some codepaths were given a repository instance as a parameter to + work in the repository, but passed the_repository instance to its + callees, which has been cleaned up (somewhat). + + * Memory footprint and performance of "git name-rev" has been + improved. + + * The object reachability bitmap machinery and the partial cloning + machinery were not prepared to work well together, because some + object-filtering criteria that partial clones use inherently rely + on object traversal, but the bitmap machinery is an optimization + to bypass that object traversal. There however are some cases + where they can work together, and they were taught about them. + + * "git rebase" has learned to use the merge backend (i.e. the + machinery that drives "rebase -i") by default, while allowing + "--apply" option to use the "apply" backend (e.g. the moral + equivalent of "format-patch piped to am"). The rebase.backend + configuration variable can be set to customize. + + * Underlying machinery of "git bisect--helper" is being refactored + into pieces that are more easily reused. + + +Fixes since v2.25 +----------------- + + * "git commit" gives output similar to "git status" when there is + nothing to commit, but without honoring the advise.statusHints + configuration variable, which has been corrected. + + * has_object_file() said "no" given an object registered to the + system via pretend_object_file(), making it inconsistent with + read_object_file(), causing lazy fetch to attempt fetching an + empty tree from promisor remotes. + + * Complete an update to tutorial that encourages "git switch" over + "git checkout" that was done only half-way. + + * C pedantry ;-) fix. + + * The code that tries to skip over the entries for the paths in a + single directory using the cache-tree was not careful enough + against corrupt index file. + + * Reduce unnecessary round-trip when running "ls-remote" over the + stateless RPC mechanism. + + * "git restore --staged" did not correctly update the cache-tree + structure, resulting in bogus trees to be written afterwards, which + has been corrected. + + * The code recently added to move to the entry beyond the ones in the + same directory in the index in the sparse-cone mode did not count + the number of entries to skip over incorrectly, which has been + corrected. + + * Rendering by "git log --graph" of ancestry lines leading to a merge + commit were made suboptimal to waste vertical space a bit with a + recent update, which has been corrected. + + * Work around test breakages caused by custom regex engine used in + libasan, when address sanitizer is used with more recent versions + of gcc and clang. + + * Minor bugfixes to "git add -i" that has recently been rewritten in C. + + * "git fetch --refmap=" option has got a better documentation. + + * "git checkout X" did not correctly fail when X is not a local + branch but could name more than one remote-tracking branches + (i.e. to be dwimmed as the starting point to create a corresponding + local branch), which has been corrected. + (merge fa74180d08 am/checkout-file-and-ref-ref-ambiguity later to maint). + + * Corner case bugs in "git clean" that stems from a (necessarily for + performance reasons) awkward calling convention in the directory + enumeration API has been corrected. + + * A fetch that is told to recursively fetch updates in submodules + inevitably produces reams of output, and it becomes hard to spot + error messages. The command has been taught to enumerate + submodules that had errors at the end of the operation. + (merge 0222540827 es/fetch-show-failed-submodules-atend later to maint). + + * The "--recurse-submodules" option of various subcommands did not + work well when run in an alternate worktree, which has been + corrected. + + * Futureproofing a test not to depend on the current implementation + detail. + + * Running "git rm" on a submodule failed unnecessarily when + .gitmodules is only cache-dirty, which has been corrected. + + * C pedantry ;-) fix. + + * "git grep --no-index" should not get affected by the contents of + the .gitmodules file but when "--recurse-submodules" is given or + the "submodule.recurse" variable is set, it did. Now these + settings are ignored in the "--no-index" mode. + + * Technical details of the bundle format has been documented. + + * Unhelpful warning messages during documentation build have been squelched. + + * "git rebase -i" identifies existing commits in its todo file with + their abbreviated object name, which could become ambiguous as it + goes to create new commits, and has a mechanism to avoid ambiguity + in the main part of its execution. A few other cases however were + not covered by the protection against ambiguity, which has been + corrected. + + * Allow the rebase.missingCommitsCheck configuration to kick in when + "rebase --edit-todo" and "rebase --continue" restarts the procedure. + (merge 5a5445d878 ag/edit-todo-drop-check later to maint). + + * The way "git submodule status" reports an initialized but not yet + populated submodule has not been reimplemented correctly when a + part of the "git submodule" command was rewritten in C, which has + been corrected. + (merge f38c92452d pk/status-of-uncloned-submodule later to maint). + + * The code to automatically shrink the fan-out in the notes tree had + an off-by-one bug, which has been killed. + + * The index-pack code now diagnoses a bad input packstream that + records the same object twice when it is used as delta base; the + code used to declare a software bug when encountering such an + input, but it is an input error. + + + * The code to compute the commit-graph has been taught to use a more + robust way to tell if two object directories refer to the same + thing. + (merge a7df60cac8 tb/commit-graph-object-dir later to maint). + + * "git remote rename X Y" needs to adjust configuration variables + (e.g. branch.<name>.remote) whose value used to be X to Y. + branch.<name>.pushRemote is now also updated. + + * Update to doc-diff. + + * Doc markup fix. + + * "git check-ignore" did not work when the given path is explicitly + marked as not ignored with a negative entry in the .gitignore file. + + * The merge-recursive machinery failed to refresh the cache entry for + a merge result in a couple of places, resulting in an unnecessary + merge failure, which has been fixed. + + * Fix for a bug revealed by a recent change to make the protocol v2 + the default. + + * In rare cases "git worktree add <path>" could think that <path> + was already a registered worktree even when it wasn't and refuse + to add the new worktree. This has been corrected. + (merge bb69b3b009 es/worktree-avoid-duplication-fix later to maint). + + * "git push" should stop from updating a branch that is checked out + when receive.denyCurrentBranch configuration is set, but it failed + to pay attention to checkouts in secondary worktrees. This has + been corrected. + (merge 4d864895a2 hv/receive-denycurrent-everywhere later to maint). + + * "git rebase BASE BRANCH" rebased/updated the tip of BRANCH and + checked it out, even when the BRANCH is checked out in a different + worktree. This has been corrected. + (merge b5cabb4a96 es/do-not-let-rebase-switch-to-protected-branch later to maint). + + * "git describe" in a repository with multiple root commits sometimes + gave up looking for the best tag to describe a given commit with + too early, which has been adjusted. + + * "git merge signed-tag" while lacking the public key started to say + "No signature", which was utterly wrong. This regression has been + reverted. + + * MinGW's poll() emulation has been improved. + + * "git show" and others gave an object name in raw format in its + error output, which has been corrected to give it in hex. + + * "git fetch" over HTTP walker protocol did not show any progress + output. We inherently do not know how much work remains, but still + we can show something not to bore users. + (merge 7655b4119d rs/show-progress-in-dumb-http-fetch later to maint). + + * Both "git ls-remote -h" and "git grep -h" give short usage help, + like any other Git subcommand, but it is not unreasonable to expect + that the former would behave the same as "git ls-remote --head" + (there is no other sensible behaviour for the latter). The + documentation has been updated in an attempt to clarify this. + + * Other code cleanup, docfix, build fix, etc. + (merge d0d0a357a1 am/update-pathspec-f-f-tests later to maint). + (merge f94f7bd00d am/test-pathspec-f-f-error-cases later to maint). + (merge c513a958b6 ss/t6025-modernize later to maint). + (merge b441717256 dl/test-must-fail-fixes later to maint). + (merge d031049da3 mt/sparse-checkout-doc-update later to maint). + (merge 145136a95a jc/skip-prefix later to maint). + (merge 5290d45134 jk/alloc-cleanups later to maint). + (merge 7a9f8ca805 rs/parse-options-concat-dup later to maint). + (merge 517b60564e rs/strbuf-insertstr later to maint). + (merge f696a2b1c8 jk/mailinfo-cleanup later to maint). + (merge de26f02db1 js/test-avoid-pipe later to maint). + (merge a2dc43414c es/doc-mentoring later to maint). + (merge 02bbbe9df9 es/worktree-cleanup later to maint). + (merge 2ce6d075fa rs/micro-cleanups later to maint). + (merge 27f182b3fc rs/blame-typefix-for-fingerprint later to maint). + (merge 3c29e21eb0 ma/test-cleanup later to maint). + (merge 240fc04f81 ag/rebase-remove-redundant-code later to maint). + (merge d68ce906c7 rs/commit-graph-code-simplification later to maint). + (merge a51d9e8f07 rj/t1050-use-test-path-is-file later to maint). + (merge fd0bc17557 kk/complete-diff-color-moved later to maint). + (merge 65bf820d0e en/test-cleanup later to maint). diff --git a/Documentation/RelNotes/2.26.1.txt b/Documentation/RelNotes/2.26.1.txt new file mode 100644 index 0000000000..1b4ecb3fdc --- /dev/null +++ b/Documentation/RelNotes/2.26.1.txt @@ -0,0 +1,5 @@ +Git v2.26.1 Release Notes +========================= + +This release merges the security fix that appears in v2.17.4; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.26.2.txt b/Documentation/RelNotes/2.26.2.txt new file mode 100644 index 0000000000..d434d0c695 --- /dev/null +++ b/Documentation/RelNotes/2.26.2.txt @@ -0,0 +1,5 @@ +Git v2.26.2 Release Notes +========================= + +This release merges the security fix that appears in v2.17.5; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.27.0.txt b/Documentation/RelNotes/2.27.0.txt new file mode 100644 index 0000000000..b398961c8a --- /dev/null +++ b/Documentation/RelNotes/2.27.0.txt @@ -0,0 +1,474 @@ +Git 2.27 Release Notes +====================== + +Updates since v2.26 +------------------- + +Backward compatibility notes + + * When "git describe C" finds that commit C is pointed by a signed or + annotated tag, which records T as its tagname in the object, the + command gives T as its answer. Even if the user renames or moves + such a tag from its natural location in the "refs/tags/" hierarchy, + "git describe C" would still give T as the answer, but in such a + case "git show T^0" would no longer work as expected. There may be + nothing at "refs/tags/T" or even worse there may be a different tag + instead. + + Starting from this version, "git describe" will always use the + "long" version, as if the "--long" option were given, when giving + its output based on such a misplaced tag to work around the problem. + + * "git pull" issues a warning message until the pull.rebase + configuration variable is explicitly given, which some existing + users may find annoying---those who prefer not to rebase need to + set the variable to false to squelch the warning. + + +UI, Workflows & Features + + * A handful of options to configure SSL when talking to proxies have + been added. + + * Smudge/clean conversion filters are now given more information + (e.g. the object of the tree-ish in which the blob being converted + appears, in addition to its path, which has already been given). + + * When "git describe C" finds an annotated tag with tagname A to be + the best name to explain commit C, and the tag is stored in a + "wrong" place in the refs/tags hierarchy, e.g. refs/tags/B, the + command gave a warning message but used A (not B) to describe C. + If C is exactly at the tag, the describe output would be "A", but + "git rev-parse A^0" would not be equal as "git rev-parse C^0". The + behavior of the command has been changed to use the "long" form + i.e. A-0-gOBJECTNAME, which is correctly interpreted by rev-parse. + + * "git pull" learned to warn when no pull.rebase configuration + exists, and neither --[no-]rebase nor --ff-only is given (which + would result a merge). + + * "git p4" learned four new hooks and also "--no-verify" option to + bypass them (and the existing "p4-pre-submit" hook). + + * "git pull" shares many options with underlying "git fetch", but + some of them were not documented and some of those that would make + sense to pass down were not passed down. + + * "git rebase" learned the "--no-gpg-sign" option to countermand + commit.gpgSign the user may have. + + * The output from "git format-patch" uses RFC 2047 encoding for + non-ASCII letters on From: and Subject: headers, so that it can + directly be fed to e-mail programs. A new option has been added + to produce these headers in raw. + + * "git log" learned "--show-pulls" that helps pathspec limited + history views; a merge commit that takes the whole change from a + side branch, which is normally omitted from the output, is shown + in addition to the commits that introduce real changes. + + * The interactive input from various codepaths are consolidated and + any prompt possibly issued earlier are fflush()ed before we read. + + * Allow "git rebase" to reapply all local commits, even if the may be + already in the upstream, without checking first. + + * The 'pack.useSparse' configuration variable now defaults to 'true', + enabling an optimization that has been experimental since Git 2.21. + + * "git rebase" happens to call some hooks meant for "checkout" and + "commit" by this was not a designed behaviour than historical + accident. This has been documented. + + * "git merge" learns the "--autostash" option. + + * "sparse-checkout" UI improvements. + + * "git update-ref --stdin" learned a handful of new verbs to let the + user control ref update transactions more explicitly, which helps + as an ingredient to implement two-phase commit-style atomic + ref-updates across multiple repositories. + + * "git commit-graph write" learned different ways to write out split + files. + + * Introduce an extension to the commit-graph to make it efficient to + check for the paths that were modified at each commit using Bloom + filters. + + * The approxidate parser learns to parse seconds with fraction and + ignore fractional part. + + * The userdiff patterns for Markdown documents have been added. + + * The sparse-checkout patterns have been forbidden from excluding all + paths, leaving an empty working tree, for a long time. This + limitation has been lifted. + + * "git restore --staged --worktree" now defaults to take the contents + out of "HEAD", instead of erring out. + + +Performance, Internal Implementation, Development Support etc. + + * The advise API has been revamped to allow more systematic enumeration of + advice knobs in the future. + + * SHA-256 transition continues. + + * The code to interface with GnuPG has been refactored. + + * "git stash" has kept an escape hatch to use the scripted version + for a few releases, which got stale. It has been removed. + + * Enable tests that require GnuPG on Windows. + + * Minor test usability improvement. + + * Trace2 enhancement to allow logging of the environment variables. + + * Test clean-up continues. + + * Perf-test update. + + * A Windows-specific test element has been made more robust against + misuse from both user's environment and programmer's errors. + + * Various tests have been updated to work around issues found with + shell utilities that come with busybox etc. + + * The config API made mixed uses of int and size_t types to represent + length of various pieces of text it parsed, which has been updated + to use the correct type (i.e. size_t) throughout. + + * The "--decorate-refs" and "--decorate-refs-exclude" options "git + log" takes have learned a companion configuration variable + log.excludeDecoration that sits at the lowest priority in the + family. + + * A new CI job to build and run test suite on linux with musl libc + has been added. + + * Update the CI configuration to use GitHub Actions, retiring the one + based on Azure Pipelines. + + * The directory traversal code had redundant recursive calls which + made its performance characteristics exponential with respect to + the depth of the tree, which was corrected. + + * "git blame" learns to take advantage of the "changed-paths" Bloom + filter stored in the commit-graph file. + + * The "bugreport" tool has been added. + + * The object walk with object filter "--filter=tree:0" can now take + advantage of the pack bitmap when available. + + * Instead of always building all branches at GitHub via Actions, + users can specify which branches to build. + + +Fixes since v2.26 +----------------- + + * The real_path() convenience function can easily be misused; with a + bit of code refactoring in the callers' side, its use has been + eliminated. + (merge 49d3c4b481 am/real-path-fix later to maint). + + * Update "git p4" to work with Python 3. + (merge 6bb40ed20a yz/p4-py3 later to maint). + + * The mechanism to prevent "git commit" from making an empty commit + or amending during an interrupted cherry-pick was broken during the + rewrite of "git rebase" in C, which has been corrected. + (merge 430b75f720 pw/advise-rebase-skip later to maint). + + * Fix "git checkout --recurse-submodules" of a nested submodule + hierarchy. + (merge 846f34d351 pb/recurse-submodules-fix later to maint). + + * The "--fork-point" mode of "git rebase" regressed when the command + was rewritten in C back in 2.20 era, which has been corrected. + (merge f08132f889 at/rebase-fork-point-regression-fix later to maint). + + * The import-tars importer (in contrib/fast-import/) used to create + phony files at the top-level of the repository when the archive + contains global PAX headers, which made its own logic to detect and + omit the common leading directory ineffective, which has been + corrected. + (merge c839fcff65 js/import-tars-do-not-make-phony-files-from-pax-headers later to maint). + + * Simplify the commit ancestry connectedness check in a partial clone + repository in which "promised" objects are assumed to be obtainable + lazily on-demand from promisor remote repositories. + (merge 2b98478c6f jt/connectivity-check-optim-in-partial-clone later to maint). + + * The server-end of the v2 protocol to serve "git clone" and "git + fetch" was not prepared to see a delim packets at unexpected + places, which led to a crash. + (merge cacae4329f jk/harden-protocol-v2-delim-handling later to maint). + + * When fed a midx that records no objects, some codepaths tried to + loop from 0 through (num_objects-1), which, due to integer + arithmetic wrapping around, made it nonsense operation with out of + bounds array accesses. The code has been corrected to reject such + an midx file. + (merge 796d61cdc0 dr/midx-avoid-int-underflow later to maint). + + * Utitiles run via the run_command() API were not spawned correctly + on Cygwin, when the paths to them are given as a full path with + backslashes. + (merge 05ac8582bc ak/run-command-on-cygwin-fix later to maint). + + * "git pull --rebase" tried to run a rebase even after noticing that + the pull results in a fast-forward and no rebase is needed nor + sensible, for the past few years due to a mistake nobody noticed. + (merge fbae70ddc6 en/pull-do-not-rebase-after-fast-forwarding later to maint). + + * "git rebase" with the merge backend did not work well when the + rebase.abbreviateCommands configuration was set. + (merge de9f1d3ef4 ag/rebase-merge-allow-ff-under-abbrev-command later to maint). + + * The logic to auto-follow tags by "git clone --single-branch" was + not careful to avoid lazy-fetching unnecessary tags, which has been + corrected. + (merge 167a575e2d jk/use-quick-lookup-in-clone-for-tag-following later to maint). + + * "git rebase -i" did not leave the reflog entries correctly. + (merge 1f6965f994 en/sequencer-reflog-action later to maint). + + * The more aggressive updates to remote-tracking branches we had for + the past 7 years or so were not reflected in the documentation, + which has been corrected. + (merge a44088435c pb/pull-fetch-doc later to maint). + + * We've left the command line parsing of "git log :/a/b/" broken for + about a full year without anybody noticing, which has been + corrected. + (merge 0220461071 jc/missing-ref-store-fix later to maint). + + * Misc fixes for Windows. + (merge 3efc128cd5 js/mingw-fixes later to maint). + + * "git rebase" (again) learns to honor "--no-keep-empty", which lets + the user to discard commits that are empty from the beginning (as + opposed to the ones that become empty because of rebasing). The + interactive rebase also marks commits that are empty in the todo. + (merge 50ed76148a en/rebase-no-keep-empty later to maint). + + * Parsing the host part out of URL for the credential helper has been corrected. + (merge 4c5971e18a jk/credential-parsing-end-of-host-in-URL later to maint). + + * Document the recommended way to abort a failing test early (e.g. by + exiting a loop), which is to say "return 1". + (merge 7cc112dc95 jc/doc-test-leaving-early later to maint). + + * The code that refreshes the last access and modified time of + on-disk packfiles and loose object files have been updated. + (merge 312cd76130 lr/freshen-file-fix later to maint). + + * Validation of push certificate has been made more robust against + timing attacks. + (merge 719483e547 bc/constant-memequal later to maint). + + * The custom hash function used by "git fast-import" has been + replaced with the one from hashmap.c, which gave us a nice + performance boost. + (merge d8410a816b jk/fast-import-use-hashmap later to maint). + + * The "git submodule" command did not initialize a few variables it + internally uses and was affected by variable settings leaked from + the environment. + (merge 65d100c4dd lx/submodule-clear-variables later to maint). + + * Raise the minimum required version of docbook-xsl package to 1.74, + as 1.74.0 was from late 2008, which is more than 10 years old, and + drop compatibility cruft from our documentation suite. + (merge 3c255ad660 ma/doc-discard-docbook-xsl-1.73 later to maint). + + * "git log" learns "--[no-]mailmap" as a synonym to "--[no-]use-mailmap" + (merge 88acccda38 jc/log-no-mailmap later to maint). + + * "git commit-graph write --expire-time=<timestamp>" did not use the + given timestamp correctly, which has been corrected. + (merge b09b785c78 ds/commit-graph-expiry-fix later to maint). + + * Tests update to use "test-chmtime" instead of "touch -t". + (merge e892a56845 ds/t5319-touch-fix later to maint). + + * "git diff" in a partial clone learned to avoid lazy loading blob + objects in more casese when they are not needed. + (merge 95acf11a3d jt/avoid-prefetch-when-able-in-diff later to maint). + + * "git push --atomic" used to show failures for refs that weren't + even pushed, which has been corrected. + (merge dfe1b7f19c jx/atomic-push later to maint). + + * Code in builtin/*, i.e. those can only be called from within + built-in subcommands, that implements bulk of a couple of + subcommands have been moved to libgit.a so that they could be used + by others. + (merge 9460fd48b5 dl/libify-a-few later to maint). + + * Allowing the user to split a patch hunk while "git stash -p" does + not work well; a band-aid has been added to make this (partially) + work better. + + * "git diff-tree --pretty --notes" used to hit an assertion failure, + as it forgot to initialize the notes subsystem. + (merge 5778b22b3d tb/diff-tree-with-notes later to maint). + + * "git range-diff" fixes. + (merge 8d1675eb7f vd/range-diff-with-custom-pretty-format-fix later to maint). + + * "git grep" did not quote a path with unusual character like other + commands (like "git diff", "git status") do, but did quote when run + from a subdirectory, both of which has been corrected. + (merge 45115d8490 mt/grep-cquote-path later to maint). + + * GNU/Hurd is also among the ones that need the fopen() wrapper. + (merge 274a1328fb jc/gnu-hurd-lets-fread-read-dirs later to maint). + + * Those fetching over protocol v2 from linux-next and other kernel + repositories are reporting that v2 often fetches way too much than + needed. + (merge 11c7f2a30b jn/demote-proto2-from-default later to maint). + + * The upload-pack protocol v2 gave up too early before finding a + common ancestor, resulting in a wasteful fetch from a fork of a + project. This has been corrected to match the behaviour of v0 + protocol. + (merge 2f0a093dd6 jt/v2-fetch-nego-fix later to maint). + + * The build procedure did not use the libcurl library and its include + files correctly for a custom-built installation. + (merge 0573831950 jk/build-with-right-curl later to maint). + + * Tighten "git mailinfo" to notice and error out when decoded result + contains NUL in it. + (merge 3919997447 dd/mailinfo-with-nul later to maint). + + * Fix in-core inconsistency after fetching into a shallow repository + that broke the code to write out commit-graph. + (merge 37b9dcabfc tb/reset-shallow later to maint). + + * The commit-graph code exhausted file descriptors easily when it + does not have to. + (merge c8828530b7 tb/commit-graph-fd-exhaustion-fix later to maint). + + * The multi-pack-index left mmapped file descriptors open when it + does not have to. + (merge 6c7ff7cf7f ds/multi-pack-index later to maint). + + * Recent update to Homebrew used by macOS folks breaks build by + moving gettext library and necessary headers. + (merge a0b3108618 ds/build-homebrew-gettext-fix later to maint). + + * Incompatible options "--root" and "--fork-point" of "git rebase" + have been marked and documented as being incompatible. + (merge a35413c378 en/rebase-root-and-fork-point-are-incompatible later to maint). + + * Error and verbose trace messages from "git push" did not redact + credential material embedded in URLs. + (merge d192fa5006 js/anonymise-push-url-in-errors later to maint). + + * Update the parser used for credential.<URL>.<variable> + configuration, to handle <URL>s with '/' in them correctly. + (merge b44d0118ac bc/wildcard-credential later to maint). + + * Recent updates broke parsing of "credential.<url>.<key>" where + <url> is not a full URL (e.g. [credential "https://"] helper = ...) + stopped working, which has been corrected. + (merge 9a121b0d22 js/partial-urlmatch-2.17 later to maint). + (merge cd93e6c029 js/partial-urlmatch later to maint). + + * Some of the files commit-graph subsystem keeps on disk did not + correctly honor the core.sharedRepository settings and some were + left read-write. + + * In error messages that "git switch" mentions its option to create a + new branch, "-b/-B" options were shown, where "-c/-C" options + should be, which has been corrected. + (merge 7c16ef7577 dl/switch-c-option-in-error-message later to maint). + + * With the recent tightening of the code that is used to parse + various parts of a URL for use in the credential subsystem, a + hand-edited credential-store file causes the credential helper to + die, which is a bit too harsh to the users. Demote the error + behaviour to just ignore and keep using well-formed lines instead. + (merge c03859a665 cb/credential-store-ignore-bogus-lines later to maint). + + * The samples in the credential documentation has been updated to + make it clear that we depict what would appear in the .git/config + file, by adding appropriate quotes as needed.. + (merge 177681a07e jk/credential-sample-update later to maint). + + * "git branch" and other "for-each-ref" variants accepted multiple + --sort=<key> options in the increasing order of precedence, but it + had a few breakages around "--ignore-case" handling, and tie-breaking + with the refname, which have been fixed. + (merge 7c5045fc18 jk/for-each-ref-multi-key-sort-fix later to maint). + + * The coding guideline for shell scripts instructed to refer to a + variable with dollar-sign inside arithmetic expansion to work + around a bug in old versions of dash, which is a thing of the past. + Now we are not forbidden from writing $((var+1)). + (merge 32b5fe7f0e jk/arith-expansion-coding-guidelines later to maint). + + * The <stdlib.h> header on NetBSD brings in its own definition of + hmac() function (eek), which conflicts with our own and unrelated + function with the same name. Our function has been renamed to work + around the issue. + (merge 3013118eb8 cb/avoid-colliding-with-netbsd-hmac later to maint). + + * The basic test did not honor $TEST_SHELL_PATH setting, which has + been corrected. + (merge 0555e4af58 cb/t0000-use-the-configured-shell later to maint). + + * Minor in-code comments and documentation updates around credential + API. + (merge 1aed817f99 cb/credential-doc-fixes later to maint). + + * Teach "am", "commit", "merge" and "rebase", when they are run with + the "--quiet" option, to pass "--quiet" down to "gc --auto". + (merge 7c3e9e8cfb jc/auto-gc-quiet later to maint). + + * The code to skip unmerged paths in the index when sparse checkout + is in use would have made out-of-bound access of the in-core index + when the last path was unmerged, which has been corrected. + + * Serving a "git fetch" client over "git://" and "ssh://" protocols + using the on-wire protocol version 2 was buggy on the server end + when the client needs to make a follow-up request to + e.g. auto-follow tags. + (merge 08450ef791 cc/upload-pack-v2-fetch-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 564956f358 jc/maintain-doc later to maint). + (merge 7422b2a0a1 sg/commit-slab-clarify-peek later to maint). + (merge 9c688735f6 rs/doc-passthru-fetch-options later to maint). + (merge 757c2ba3e2 en/oidset-uninclude-hashmap later to maint). + (merge 8312aa7d74 jc/config-tar later to maint). + (merge d00a5bdd50 ss/submodule-foreach-cb later to maint). + (merge 64d1022e14 ar/test-style-fixes later to maint). + (merge 4a465443a6 ds/doc-clone-filter later to maint). + (merge bb2dbe301b jk/t3419-drop-expensive-tests later to maint). + (merge d3507cc712 js/test-junit-finalization-fix later to maint). + (merge 2149b6748f bc/faq later to maint). + (merge 12dc0879f1 jk/test-cleanup later to maint). + (merge 344420bf0f pb/rebase-doc-typofix later to maint). + (merge 7cd54d37dc dl/wrapper-fix-indentation later to maint). + (merge 78725ebda9 jc/allow-strlen-substitution-in-shell-scripts later to maint). + (merge 2ecfcdecc6 jm/gitweb-fastcgi-utf8 later to maint). + (merge 0740d0a5d3 jk/oid-array-cleanups later to maint). + (merge a1aba0c95c js/t0007-typofix later to maint). + (merge 76ba7fa225 ma/config-doc-fix later to maint). + (merge 826f0c0df2 js/subtree-doc-update-to-asciidoctor-2 later to maint). + (merge 88eaf361e0 eb/mboxrd-doc later to maint). + (merge 051cc54941 tm/zsh-complete-switch-restore later to maint). + (merge 39102cf4fe ms/doc-revision-illustration-fix later to maint). + (merge 4d9378bfad eb/gitweb-more-trailers later to maint). + (merge bdccbf7047 mt/doc-worktree-ref later to maint). + (merge ce9baf234f dl/push-recurse-submodules-fix later to maint). + (merge 4153274052 bc/doc-credential-helper-value later to maint). diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 8fc4b67081..3e4c13971b 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -31,24 +31,6 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-docbook[] -ifndef::git-asciidoc-no-roff[] -# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. -# v1.72 breaks with this because it replaces dots not in roff requests. -[listingblock] -<example><title>{title}</title> -<literallayout class="monospaced"> -ifdef::doctype-manpage[] - .ft C -endif::doctype-manpage[] -| -ifdef::doctype-manpage[] - .ft -endif::doctype-manpage[] -</literallayout> -{title#}</example> -endif::git-asciidoc-no-roff[] - -ifdef::git-asciidoc-no-roff[] ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] @@ -67,7 +49,6 @@ ifdef::doctype-manpage[] {title#}</para></formalpara> {title%}<simpara></simpara> endif::doctype-manpage[] -endif::git-asciidoc-no-roff[] endif::backend-docbook[] ifdef::doctype-manpage[] diff --git a/Documentation/config.txt b/Documentation/config.txt index 83e7bba872..ef0768b91a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -3,11 +3,12 @@ CONFIGURATION FILE The Git configuration file contains a number of variables that affect 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. +`config.worktree` (see the "CONFIGURATION FILE" section of +linkgit:git-worktree[1]) in each repository are used to store the +configuration for that repository, and `$HOME/.gitconfig` is used to +store a per-user configuration as fallback values for the `.git/config` +file. The file `/etc/gitconfig` can be used to store a system-wide +default configuration. The configuration variables are used by both the Git plumbing and the porcelains. The variables are divided into sections, wherein @@ -220,12 +221,12 @@ Example ; affected by the condition [includeIf "gitdir:/path/to/group/"] path = foo.inc ----- - ; include only if we are in a worktree where foo-branch is - ; currently checked out - [includeIf "onbranch:foo-branch"] - path = foo.inc +; include only if we are in a worktree where foo-branch is +; currently checked out +[includeIf "onbranch:foo-branch"] + path = foo.inc +---- Values ~~~~~~ @@ -263,7 +264,9 @@ color:: + The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white`. The first color given is the -foreground; the second is the background. +foreground; the second is the background. All the basic colors except +`normal` have a bright variant that can be speficied by prefixing the +color with `bright`, like `brightred`. + Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If @@ -445,6 +448,8 @@ include::config/submodule.txt[] include::config/tag.txt[] +include::config/tar.txt[] + include::config/trace2.txt[] include::config/transfer.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 4be93f8ad9..bdd37c3eaa 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -110,4 +110,10 @@ advice.*:: submoduleAlternateErrorStrategyDie:: Advice shown when a submodule.alternateErrorStrategy option configured to "die" causes a fatal error. + addIgnoredFile:: + Advice shown if a user attempts to add an ignored file to + the index. + addEmptyPathspec:: + Advice shown if a user runs the add command without providing + the pathspec parameter. -- diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index a592d522a7..cc5f3249fc 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -81,15 +81,16 @@ branch.<name>.rebase:: "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' +When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When `preserve` (deprecated in favor of `merges`), also pass +When `preserve` (or just 'p', deprecated in favor of `merges`), also pass `--preserve-merges` along to 'git rebase' so that locally committed merge commits will not be flattened by running 'git pull'. + -When the value is `interactive`, the rebase is run in interactive mode. +When the value is `interactive` (or just 'i'), the rebase is run in interactive +mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 9e440b160d..74619a9c03 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -68,6 +68,17 @@ core.fsmonitor:: avoiding unnecessary processing of files that have not changed. See the "fsmonitor-watchman" section of linkgit:githooks[5]. +core.fsmonitorHookVersion:: + Sets the version of hook that is to be used when calling fsmonitor. + There are currently versions 1 and 2. When this is not set, + version 2 will be tried first and if it fails then version 1 + will be tried. Version 1 uses a timestamp as input to determine + which files have changes since that time but some monitors + like watchman have race conditions when used with a timestamp. + Version 2 uses an opaque string so that the monitor can return + something that can be used to determine what files have changed + without race conditions. + core.trustctime:: If false, the ctime differences between the index and the working tree are ignored; useful when the inode change time diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt index 60fb3189e1..9d01641c28 100644 --- a/Documentation/config/credential.txt +++ b/Documentation/config/credential.txt @@ -1,9 +1,13 @@ 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. + storage to avoid prompting the user for the credentials. This is + normally the name of a credential helper with possible + arguments, but may also be an absolute path with arguments or, if + preceded by `!`, shell commands. ++ +Note that multiple helpers may be defined. See linkgit:gitcredentials[7] +for details and examples. credential.useHttpPath:: When acquiring credentials, consider the "path" component of an http diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index 875f8c8a66..4e3a5c0ceb 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -12,9 +12,6 @@ feature.experimental:: setting if you are interested in providing feedback on experimental features. The new default values are: + -* `pack.useSparse=true` uses a new algorithm when constructing a pack-file -which can improve `git push` performance in repos with many files. -+ * `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by skipping more commits at a time, reducing the number of round trips. + diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index f11940280f..b1a9b1461d 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -1,11 +1,14 @@ fetch.recurseSubmodules:: - This option can be either set to a boolean value or to 'on-demand'. + This option controls whether `git fetch` (and the underlying fetch + in `git pull`) will recursively fetch into populated submodules. + This option can be set either to a boolean value or to 'on-demand'. Setting it to a boolean changes the behavior of fetch and pull to - 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 + recurse unconditionally into submodules when set to true or to not + recurse at all when set to false. When set to 'on-demand', fetch and + pull will only recurse into a populated submodule when its + superproject retrieves a commit that updates the submodule's reference. + Defaults to 'on-demand', or to the value of 'submodule.recurse' if set. fetch.fsckObjects:: If it is set to true, git-fetch-pack will check all fetched diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index 45c7bd5a8f..564e8091ba 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -57,6 +57,11 @@ format.suffix:: `.patch`. Use this variable to change that suffix (make sure to include the dot if you want it). +format.encodeEmailHeaders:: + Encode email headers that have non-ASCII characters with + "Q-encoding" (described in RFC 2047) for email transmission. + Defaults to true. + format.pretty:: The default pretty format for log/show/whatchanged command, See linkgit:git-log[1], linkgit:git-show[1], diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index cce2c89245..d94025cb36 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -18,3 +18,18 @@ gpg.<format>.program:: chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still be used as a legacy synonym for `gpg.openpgp.program`. The default value for `gpg.x509.program` is "gpgsm". + +gpg.minTrustLevel:: + Specifies a minimum trust level for signature verification. If + this option is unset, then signature verification for merge + operations require a key with at least `marginal` trust. Other + operations that perform signature verification require a key + with at least `undefined` trust. Setting this option overrides + the required trust-level for all operations. Supported values, + in increasing order of significance: ++ +* `undefined` +* `never` +* `marginal` +* `fully` +* `ultimate` diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 5a32f5b0a5..3968fbb697 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -29,6 +29,27 @@ http.proxyAuthMethod:: * `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) -- +http.proxySSLCert:: + The pathname of a file that stores a client certificate to use to authenticate + with an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CERT` environment + variable. + +http.proxySSLKey:: + The pathname of a file that stores a private key to use to authenticate with + an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_KEY` environment + variable. + +http.proxySSLCertPasswordProtected:: + Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL + will prompt the user, possibly many times, if the certificate or private key + is encrypted. Can be overriden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` + environment variable. + +http.proxySSLCAInfo:: + Pathname to the file containing the certificate bundle that should be used to + verify the proxy with when using an HTTPS proxy. Can be overriden by the + `GIT_PROXY_SSL_CAINFO` environment variable. + http.emptyAuth:: Attempt authentication without seeking a username or password. This can be used to attempt GSS-Negotiate authentication without specifying @@ -71,7 +92,7 @@ http.saveCookies:: 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 + on libcurl. Currently the possible values of this option are: - HTTP/2 @@ -84,7 +105,7 @@ http.sslVersion:: 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 + for the ssl version supported. Currently the possible values of this option are: - sslv2 @@ -199,6 +220,14 @@ http.postBuffer:: Transfer-Encoding: chunked is used to avoid creating a massive pack file locally. Default is 1 MiB, which is sufficient for most requests. ++ +Note that raising this limit is only effective for disabling chunked +transfer encoding and therefore should be used only where the remote +server or a proxy only supports HTTP/1.0 or is noncompliant with the +HTTP standard. Raising this is not, in general, an effective solution +for most push problems, but can increase memory consumption +significantly since the entire buffer is allocated even for small +pushes. http.lowSpeedLimit, http.lowSpeedTime:: If the HTTP transfer speed is less than 'http.lowSpeedLimit' diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt index e9e1e397f3..208d5fdcaa 100644 --- a/Documentation/config/log.txt +++ b/Documentation/config/log.txt @@ -18,6 +18,12 @@ log.decorate:: names are shown. This is the same as the `--decorate` option of the `git log`. +log.excludeDecoration:: + Exclude the specified patterns from the log decorations. This is + similar to the `--decorate-refs-exclude` command-line option, but + the config option can be overridden by the `--decorate-refs` + option. + log.follow:: If `true`, `git log` will act as if the `--follow` option was used when a single <path> is given. This has the same limitations as `--follow`, diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 6a313937f8..cb2ed58907 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -70,6 +70,16 @@ merge.stat:: Whether to print the diffstat between ORIG_HEAD and the merge result at the end of the merge. True by default. +merge.autoStash:: + When set to true, automatically create a temporary stash entry + before the operation begins, and apply it after the operation + ends. This means that you can run merge on a dirty worktree. + However, use with care: the final stash application after a + successful merge might result in non-trivial conflicts. + This option can be overridden by the `--no-autostash` and + `--autostash` options of linkgit:git-merge[1]. + Defaults to false. + merge.tool:: Controls which merge tool is used by linkgit:git-mergetool[1]. The list below shows the valid built-in values. diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index 1d66f0c992..837f1b1679 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -27,6 +27,13 @@ Note that changing the compression level will not automatically recompress all existing objects. You can force recompression by passing the -F option to linkgit:git-repack[1]. +pack.allowPackReuse:: + When true, and when reachability bitmaps are enabled, + pack-objects will try to send parts of the bitmapped packfile + verbatim. This can reduce memory and CPU usage to serve fetches, + but might result in sending a slightly larger pack. Defaults to + true. + pack.island:: An extended regular expression configuring a set of delta islands. See "DELTA ISLANDS" in linkgit:git-pack-objects[1] @@ -112,8 +119,8 @@ pack.useSparse:: objects. This can have significant performance benefits when computing a pack to send a small change. However, it is possible that extra objects are added to the pack-file if the included - commits contain certain types of direct renames. Default is `false` - unless `feature.experimental` is enabled. + commits contain certain types of direct renames. Default is + `true`. pack.writeBitmaps (deprecated):: This is a deprecated synonym for `repack.writeBitmaps`. diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index bfccc07491..0b40141613 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -45,11 +45,10 @@ The protocol names currently used by git are: -- 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. + If set, clients will attempt to communicate with a server + using the specified protocol version. If the server does + not support it, communication falls back to version 0. + If unset, the default is `0`. Supported versions: + -- diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.txt index b87cab31b3..5404830609 100644 --- a/Documentation/config/pull.txt +++ b/Documentation/config/pull.txt @@ -14,15 +14,16 @@ pull.rebase:: 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' +When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When `preserve` (deprecated in favor of `merges`), also pass +When `preserve` (or just 'p', deprecated in favor of `merges`), also pass `--preserve-merges` along to 'git rebase' so that locally committed merge commits will not be flattened by running 'git pull'. + -When the value is `interactive`, the rebase is run in interactive mode. +When the value is `interactive` (or just 'i'), the rebase is run in interactive +mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index 0a0e000569..f5e5b38c68 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -1,6 +1,7 @@ push.default:: Defines the action `git push` should take if no refspec is - explicitly given. Different values are well-suited for + given (whether from the command-line, config, or elsewhere). + Different values are well-suited for specific workflows; for instance, in a purely central workflow (i.e. the fetch source is equal to the push destination), `upstream` is probably what you want. Possible values are: @@ -8,7 +9,7 @@ push.default:: -- * `nothing` - do not push anything (error out) unless a refspec is - explicitly given. This is primarily meant for people who want to + 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 @@ -79,7 +80,7 @@ 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: @@ -96,7 +97,7 @@ repo/.git/config 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 @@ -111,3 +112,5 @@ push.recurseSubmodules:: is 'no' then default behavior of ignoring submodules when pushing is retained. You may override this configuration at time of push by specifying '--recurse-submodules=check|on-demand|no'. + If not set, 'no' is used by default, unless 'submodule.recurse' is + set (in which case a 'true' value means 'on-demand'). diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index d98e32d812..7f7a07d22f 100644 --- a/Documentation/config/rebase.txt +++ b/Documentation/config/rebase.txt @@ -5,6 +5,12 @@ rebase.useBuiltin:: is always used. Setting this will emit a warning, to alert any remaining users that setting this now does nothing. +rebase.backend:: + Default backend to use for rebasing. Possible choices are + 'apply' or 'merge'. In the future, if the merge backend gains + all remaining capabilities of the apply backend, this setting + may become unused. + rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt index abc7ef4a3a..00eb35434e 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -1,17 +1,9 @@ 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 as 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). + Unused configuration variable. Used in Git versions 2.22 to + 2.26 as an escape hatch to enable the legacy shellscript + implementation of stash. Now the built-in rewrite of it in C + is always used. Setting this will emit a warning, to alert any + remaining users that setting this now does nothing. stash.showPatch:: If this is set to true, the `git stash show` command without an diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..d7a63c8c12 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,9 +59,17 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. + When set to true, it can be deactivated via the + `--no-recurse-submodules` option. Note that some Git commands + lacking this option may call some of the above commands affected by + `submodule.recurse`; for instance `git remote update` will call + `git fetch` but does not have a `--no-recurse-submodules` option. + For these commands a workaround is to temporarily change the + configuration value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. diff --git a/Documentation/config/tag.txt b/Documentation/config/tag.txt index 6d9110d84c..5062a057ff 100644 --- a/Documentation/config/tag.txt +++ b/Documentation/config/tag.txt @@ -15,10 +15,3 @@ tag.gpgSign:: convenient to use an agent to avoid typing your gpg passphrase several times. Note that this option doesn't affect tag signing behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options. - -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/tar.txt b/Documentation/config/tar.txt new file mode 100644 index 0000000000..de8ff48ea9 --- /dev/null +++ b/Documentation/config/tar.txt @@ -0,0 +1,6 @@ +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) and + linkgit:git-archive[1]. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index 4ce0b9a6d1..01d3afd8a8 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -48,6 +48,15 @@ trace2.configParams:: May be overridden by the `GIT_TRACE2_CONFIG_PARAMS` environment variable. Unset by default. +trace2.envVars:: + A comma-separated list of "important" environment variables that should + be recorded in the trace2 output. For example, + `GIT_HTTP_USER_AGENT,GIT_CONFIG` would cause the trace2 output to + contain events listing the overrides for HTTP user agent and the + location of the Git configuration file (assuming any are set). May be + overriden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by + default. + trace2.destinationDebug:: Boolean. When true Git will print error messages when a trace target destination cannot be opened for writing. diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index 0557cbbceb..59aec7c3ae 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -13,7 +13,12 @@ committer.email:: 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. ++ +Note that the `name` forms of these variables conventionally refer to +some form of a personal name. See linkgit:git-commit[1] and the +environment variables section of linkgit:git[1] for more information on +these settings and the `credential.username` option if you're looking +for authentication credentials instead. user.useConfigOnly:: Instruct Git to avoid trying to guess defaults for `user.email` diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index 6926e0a4c8..7e7eaba643 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -20,7 +20,10 @@ RFC 2822:: ISO 8601:: Time and date specified by the ISO 8601 standard, for example `2005-04-07T22:13:13`. The parser accepts a space instead of the - `T` character as well. + `T` character as well. Fractional parts of a second will be ignored, + for example `2005-04-07T22:13:13.019` will be treated as + `2005-04-07T22:13:13` + + NOTE: In addition, the date part is accepted in the following formats: `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 09faee3b44..bb31f0c42b 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -567,13 +567,13 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and file: + ---- -+ return !regexec(regexp, two->ptr, 1, ®match, 0); ++ return frotz(nitfol, two->ptr, 1, 0); ... -- hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); +- hit = frotz(nitfol, mf2.ptr, 1, 0); ---- + -While `git log -G"regexec\(regexp"` will show this commit, `git log --S"regexec\(regexp" --pickaxe-regex` will not (because the number of +While `git log -G"frotz\(nitfol"` will show this commit, `git log +-S"frotz\(nitfol" --pickaxe-regex` will not (because the number of occurrences of that string did not change). + Unless `--text` is supplied patches of binary files without a textconv diff --git a/Documentation/doc-diff b/Documentation/doc-diff index 88a9b20168..1694300e50 100755 --- a/Documentation/doc-diff +++ b/Documentation/doc-diff @@ -127,7 +127,7 @@ generate_render_makefile () { while read src do dst=$2/${src#$1/} - printf 'all:: %s\n' "$dst" + printf 'all: %s\n' "$dst" printf '%s: %s\n' "$dst" "$src" printf '\t@echo >&2 " RENDER $(notdir $@)" && \\\n' printf '\tmkdir -p $(dir $@) && \\\n' diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index a2f78624a2..6e2a160a47 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -61,10 +61,8 @@ this option multiple times, one for each matching ref name. See also the `fetch.negotiationAlgorithm` configuration variable documented in linkgit:git-config[1]. -ifndef::git-pull[] --dry-run:: Show what would be done, without making any changes. -endif::git-pull[] -f:: --force:: @@ -95,6 +93,7 @@ ifndef::git-pull[] --[no-]write-commit-graph:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. +endif::git-pull[] -p:: --prune:: @@ -107,6 +106,7 @@ ifndef::git-pull[] was cloned with the --mirror option), then they are also subject to pruning. Supplying `--prune-tags` is a shorthand for providing the tag refspec. +ifndef::git-pull[] + See the PRUNING section below for more details. @@ -133,13 +133,15 @@ endif::git-pull[] behavior for a remote may be specified with the remote.<name>.tagOpt setting. See linkgit:git-config[1]. -ifndef::git-pull[] --refmap=<refspec>:: When fetching refs listed on the command line, use the specified refspec (can be given more than once) to map the refs to remote-tracking branches, instead of the values of `remote.*.fetch` configuration variables for the remote - repository. See section on "Configured Remote-tracking + repository. Providing an empty `<refspec>` to the + `--refmap` option causes Git to ignore the configured + refspecs and rely entirely on the refspecs supplied as + command-line arguments. See section on "Configured Remote-tracking Branches" for details. -t:: @@ -151,6 +153,7 @@ ifndef::git-pull[] is used (though tags may be pruned anyway if they are also the destination of an explicit refspec; see `--prune`). +ifndef::git-pull[] --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of populated submodules should be fetched too. It can be used as a @@ -160,7 +163,9 @@ ifndef::git-pull[] value. Use 'on-demand' to only recurse into a populated submodule when the superproject retrieves a commit that updates the submodule's reference to a commit that isn't already in the local submodule - clone. + clone. By default, 'on-demand' is used, unless + `fetch.recurseSubmodules` is set (see linkgit:git-config[1]). +endif::git-pull[] -j:: --jobs=<n>:: @@ -174,9 +179,11 @@ parallel. To control them independently, use the config settings Typically, parallel recursive and multi-remote fetches will be faster. By default fetches are performed sequentially, not in parallel. +ifndef::git-pull[] --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as using the `--recurse-submodules=no` option). +endif::git-pull[] --set-upstream:: If the remote is fetched successfully, pull and add upstream @@ -185,6 +192,7 @@ default fetches are performed sequentially, not in parallel. see `branch.<name>.merge` and `branch.<name>.remote` in linkgit:git-config[1]. +ifndef::git-pull[] --submodule-prefix=<path>:: Prepend <path> to paths printed in informative messages such as "Fetching submodule foo". This option is used @@ -197,7 +205,6 @@ default fetches are performed sequentially, not in parallel. recursion (such as settings in linkgit:gitmodules[5] and linkgit:git-config[1]) override this option, as does specifying --[no-]recurse-submodules directly. -endif::git-pull[] -u:: --update-head-ok:: @@ -207,6 +214,7 @@ endif::git-pull[] to communicate with 'git fetch', and unless you are implementing your own Porcelain you are not supposed to use it. +endif::git-pull[] --upload-pack <upload-pack>:: When given, and the repository to fetch from is handled diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 11ca61b00b..38c0852139 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -16,7 +16,7 @@ SYNOPSIS [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [(<mbox> | <Maildir>)...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch) +'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)]) DESCRIPTION ----------- @@ -148,9 +148,12 @@ default. You can use `--no-utf8` to override this. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. --continue:: -r:: @@ -176,9 +179,11 @@ default. You can use `--no-utf8` to override this. Abort the patching operation but keep HEAD and the index untouched. ---show-current-patch:: - Show the entire e-mail message "git am" has stopped at, because - of conflicts. +--show-current-patch[=(diff|raw)]:: + Show the message at which `git am` has stopped due to + conflicts. If `raw` is specified, show the raw contents of + the e-mail message; if `diff`, show the diff portion only. + Defaults to `raw`. DISCUSSION ---------- diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 8b2d49c79e..0c3924a63d 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -30,9 +30,15 @@ OPTIONS valid with a single pathname. -v, --verbose:: - Also output details about the matching pattern (if any) - for each given pathname. For precedence rules within and - between exclude sources, see linkgit:gitignore[5]. + Instead of printing the paths that are excluded, for each path + that matches an exclude pattern, print the exclude pattern + together with the path. (Matching an exclude pattern usually + means the path is excluded, but if the pattern begins with '!' + then it is a negated pattern and matching it means the path is + NOT excluded.) ++ +For precedence rules within and between exclude sources, see +linkgit:gitignore[5]. --stdin:: Read pathnames from the standard input, one per line, diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c8fb995fa7..5b697eee1b 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -292,11 +292,11 @@ Note that this option uses the no overlay mode by default (see also --recurse-submodules:: --no-recurse-submodules:: - Using `--recurse-submodules` will update the content of all initialized + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) - is used, the work trees of submodules will not be updated. + is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodule. diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 83ce51aedf..75feeef08a 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -109,9 +109,12 @@ effect to your index in a row. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. --ff:: If the current HEAD is the same as the parent of the diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index bf24f1813a..08d6045c4a 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -15,7 +15,8 @@ SYNOPSIS [--dissociate] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] [--no-tags] [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules] - [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--] <repository> + [--[no-]remote-submodules] [--jobs <n>] [--sparse] + [--filter=<filter>] [--] <repository> [<directory>] DESCRIPTION @@ -162,6 +163,16 @@ objects from the source repository into a pack in the cloned repository. of the repository. The sparse-checkout file can be modified to grow the working directory as needed. +--filter=<filter-spec>:: + Use the partial clone feature and request that the server sends + a subset of reachable objects according to a given object filter. + When using `--filter`, the supplied `<filter-spec>` is used for + the partial clone filter. For example, `--filter=blob:none` will + filter out all blobs (file contents) until needed by Git. Also, + `--filter=blob:limit=<size>` will filter out all blobs of size + at least `<size>`. For more details on filter specifications, see + the `--filter` option in linkgit:git-rev-list[1]. + --mirror:: Set up a mirror of the source repository. This implies `--bare`. Compared to `--bare`, `--mirror` not only maps local branches of the diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index bcd85c1976..53a650225a 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -26,7 +26,10 @@ OPTIONS 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 in the `<dir>/info` directory and - the packfiles are expected to be in `<dir>/pack`. + the packfiles are expected to be in `<dir>/pack`. If the directory + could not be made into an absolute path, or does not match any known + object directory, `git commit-graph ...` will exit with non-zero + status. --[no-]progress:: Turn progress on/off explicitly. If neither is specified, progress is @@ -54,11 +57,23 @@ or `--stdin-packs`.) With the `--append` option, include all commits that are present in the existing commit-graph file. + -With the `--split` option, write the commit-graph as a chain of multiple -commit-graph files stored in `<dir>/info/commit-graphs`. The new commits -not already in the commit-graph are added in a new "tip" file. This file -is merged with the existing file if the following merge conditions are -met: +With the `--changed-paths` option, compute and write information about the +paths changed between a commit and it's first parent. This operation can +take a while on large repositories. It provides significant performance gains +for getting history of a directory or a file with `git log -- <path>`. ++ +With the `--split[=<strategy>]` option, write the commit-graph as a +chain of multiple commit-graph files stored in +`<dir>/info/commit-graphs`. Commit-graph layers are merged based on the +strategy and other splitting options. The new commits not already in the +commit-graph are added in a new "tip" file. This file is merged with the +existing file if the following merge conditions are met: +* If `--split=no-merge` is specified, a merge is never performed, and +the remaining options are ignored. `--split=replace` overwrites the +existing chain with a new one. A bare `--split` defers to the remaining +options. (Note that merging a chain of commit graphs replaces the +existing chain with a length-1 chain where the first and only +incremental holds the entire graph). + * If `--size-multiple=<X>` is not specified, let `X` equal 2. If the new tip file would have `N` commits and the previous tip has `M` commits and diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 4b90b9c12a..2e2c581098 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -61,14 +61,11 @@ OPTIONS -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. - ---no-gpg-sign:: - Do not GPG-sign commit, to countermand a `--gpg-sign` option - given earlier on the command line. - + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand a `--gpg-sign` option given earlier on the command line. Commit Information ------------------ @@ -79,26 +76,6 @@ A commit encapsulates: - author name, email and date - committer name and email and the commit time. -While parent object ids are provided on the command line, author and -committer information is taken from the following environment variables, -if set: - - GIT_AUTHOR_NAME - GIT_AUTHOR_EMAIL - GIT_AUTHOR_DATE - GIT_COMMITTER_NAME - GIT_COMMITTER_EMAIL - GIT_COMMITTER_DATE - -(nb "<", ">" and "\n"s are stripped) - -In case (some of) these environment variables are not set, the information -is taken from the configuration items user.name and user.email, or, if not -present, the environment variable EMAIL, or, if that is not set, -system user name and the hostname used for outgoing mail (taken -from `/etc/mailname` and falling back to the fully qualified hostname when -that file does not exist). - A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, 'git commit-tree' will just wait for one to be entered and terminated with ^D. @@ -117,6 +94,7 @@ FILES SEE ALSO -------- linkgit:git-write-tree[1] +linkgit:git-commit[1] GIT --- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index ced5a9beab..a3baea32ae 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -348,13 +348,12 @@ changes to tracked files. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. - ---no-gpg-sign:: - Countermand `commit.gpgSign` configuration variable that is - set to force each and every commit to be signed. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. \--:: Do not interpret any more arguments as options. @@ -367,9 +366,6 @@ changes to tracked files. + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. -:git-commit: 1 -include::date-formats.txt[] - EXAMPLES -------- When recording your own work, the contents of modified files in @@ -463,6 +459,43 @@ alter the order the changes are committed, because the merge should be recorded as a single commit. In fact, the command refuses to run when given pathnames (but see `-i` option). +COMMIT INFORMATION +------------------ + +Author and committer information is taken from the following environment +variables, if set: + + GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL + GIT_AUTHOR_DATE + GIT_COMMITTER_NAME + GIT_COMMITTER_EMAIL + GIT_COMMITTER_DATE + +(nb "<", ">" and "\n"s are stripped) + +The author and committer names are by convention some form of a personal name +(that is, the name by which other humans refer to you), although Git does not +enforce or require any particular form. Arbitrary Unicode may be used, subject +to the constraints listed above. This name has no effect on authentication; for +that, see the `credential.username` variable in linkgit:git-config[1]. + +In case (some of) these environment variables are not set, the information +is taken from the configuration items `user.name` and `user.email`, or, if not +present, the environment variable EMAIL, or, if that is not set, +system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). + +The `author.name` and `committer.name` and their corresponding email options +override `user.name` and `user.email` if set and are overridden themselves by +the environment variables. + +The typical usage is to set just the `user.name` and `user.email` variables; +the other options are provided for more complex use cases. + +:git-commit: 1 +include::date-formats.txt[] DISCUSSION ---------- diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 693dd9d9d7..76b0798856 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -94,6 +94,10 @@ stored on its own line as a URL like: https://user:pass@example.com ------------------------------ +No other kinds of lines (e.g. empty lines or comment lines) are +allowed in the file, even though some may be silently ignored. Do +not view or edit the file with editors. + When Git needs authentication for a particular URL context, credential-store will consider that context a pattern to match against each entry in the credentials file. If the protocol, hostname, and diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 6f0c7ca80f..8d990e92fd 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -103,17 +103,20 @@ INPUT/OUTPUT FORMAT `git credential` reads and/or writes (depending on the action used) credential information in its standard input/output. This information can correspond either to keys for which `git credential` will obtain -the login/password information (e.g. host, protocol, path), or to the -actual credential data to be obtained (login/password). +the login information (e.g. host, protocol, path), or to the actual +credential data to be obtained (username/password). The credential is split into a set of named attributes, with one -attribute per line. Each attribute is -specified by a key-value pair, separated by an `=` (equals) sign, -followed by a newline. The key may contain any bytes except `=`, -newline, or NUL. The value may contain any bytes except newline or NUL. +attribute per line. Each attribute is specified by a key-value pair, +separated by an `=` (equals) sign, followed by a newline. + +The key may contain any bytes except `=`, newline, or NUL. The value may +contain any bytes except newline or NUL. + In both cases, all bytes are treated as-is (i.e., there is no quoting, and one cannot transmit a value with newline or NUL in it). The list of attributes is terminated by a blank line or end-of-file. + Git understands the following attributes: `protocol`:: @@ -123,7 +126,8 @@ Git understands the following attributes: `host`:: - The remote hostname for a network credential. + The remote hostname for a network credential. This includes + the port number if one was specified (e.g., "example.com:8088"). `path`:: @@ -134,7 +138,7 @@ Git understands the following attributes: `username`:: The credential's username, if we already have one (e.g., from a - URL, from the user, or from a previously run helper). + URL, the configuration, the user, or from a previously run helper). `password`:: @@ -146,8 +150,12 @@ Git understands the following attributes: value is parsed as a URL and treated as if its constituent parts were read (e.g., `url=https://example.com` would behave as if `protocol=https` and `host=example.com` had been provided). This - can help callers avoid parsing URLs themselves. Note that any - components which are missing from the URL (e.g., there is no - username in the example above) will be set to empty; if you want - to provide a URL and override some attributes, provide the URL - attribute first, followed by any overrides. + can help callers avoid parsing URLs themselves. + + Note that specifying a protocol is mandatory and if the URL + doesn't specify a hostname (e.g., "cert:///path/to/file") the + credential will contain a hostname attribute whose value is an + empty string. + + Components which are missing from the URL (e.g., there is no + username in the example above) will be left unset. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 7889f95940..77c6b3d001 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -122,6 +122,26 @@ Locations of Marks Files Relative and non-relative marks may be combined by interweaving --(no-)-relative-marks with the --(import|export)-marks= options. +Submodule Rewriting +~~~~~~~~~~~~~~~~~~~ + +--rewrite-submodules-from=<name>:<file>:: +--rewrite-submodules-to=<name>:<file>:: + Rewrite the object IDs for the submodule specified by <name> from the values + used in the from <file> to those used in the to <file>. The from marks should + have been created by `git fast-export`, and the to marks should have been + created by `git fast-import` when importing that same submodule. ++ +<name> may be any arbitrary string not containing a colon character, but the +same value must be used with both options when specifying corresponding marks. +Multiple submodules may be specified with different values for <name>. It is an +error not to use these options in corresponding pairs. ++ +These options are primarily useful when converting a repository from one hash +algorithm to another; without them, fast-import will fail if it encounters a +submodule because it has no way of writing the object ID into the new hash +algorithm. + Performance and Compression Tuning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index a530fef7e5..40ba4aa3e6 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -467,9 +467,9 @@ impossible for a backward-compatible implementation to ever be fast: * In editing files, git-filter-branch by design checks out each and every commit as it existed in the original repo. If your repo has - 10\^5 files and 10\^5 commits, but each commit only modifies 5 - files, then git-filter-branch will make you do 10\^10 modifications, - despite only having (at most) 5*10^5 unique blobs. + `10^5` files and `10^5` commits, but each commit only modifies five + files, then git-filter-branch will make you do `10^10` modifications, + despite only having (at most) `5*10^5` unique blobs. * If you try and cheat and try to make git-filter-branch only work on files modified in a commit, then two things happen diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 0d4f8951bb..0f81d0437b 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -24,6 +24,7 @@ SYNOPSIS [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] + [--[no-]encode-email-headers] [--no-notes | --notes[=<ref>]] [--interdiff=<previous>] [--range-diff=<previous> [--creation-factor=<percent>]] @@ -253,6 +254,13 @@ feeding the result to `git send-email`. containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--encode-email-headers:: +--no-encode-email-headers:: + Encode email headers that have non-ASCII characters with + "Q-encoding" (described in RFC 2047), instead of outputting the + headers verbatim. Defaults to the value of the + `format.encodeEmailHeaders` configuration variable. + --interdiff=<previous>:: As a reviewer aid, insert an interdiff into the cover letter, or as commentary of the lone patch of a 1-patch series, showing diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index c89fb569e3..a7f9bc99ea 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -59,8 +59,8 @@ grep.extendedRegexp:: other than 'default'. grep.threads:: - Number of grep worker threads to use. If unset (or set to 0), - 8 threads are used by default (for now). + Number of grep worker threads to use. If unset (or set to 0), Git will + use as many threads as the number of logical cores available. grep.fullName:: If set to true, enable `--full-name` option by default. @@ -93,10 +93,11 @@ OPTIONS with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + Recursively search in each submodule that is active and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of - the parent project's <tree> object. + the parent project's <tree> object. This option has no effect + if `--no-index` is given. -a:: --text:: @@ -205,8 +206,10 @@ providing this option will cause it to die. -z:: --null:: - Output \0 instead of the character that normally follows a - file name. + Use \0 as the delimiter for pathnames in the output, and print + them verbatim. Without this option, pathnames with "unusual" + characters are quoted as explained for the configuration + variable core.quotePath (see git-config(1)). -o:: --only-matching:: @@ -347,6 +350,17 @@ EXAMPLES `git grep solution -- :^Documentation`:: Looks for `solution`, excluding files in `Documentation`. +NOTES ON THREADS +---------------- + +The `--threads` option (and the grep.threads configuration) will be ignored when +`--open-files-in-pager` is used, forcing a single-threaded execution. + +When grepping the object store (with `--cached` or giving tree objects), running +with multiple threads might perform slower than single threaded if `--textconv` +is given and there're too many text conversions. So if you experience low +performance in this case, it might be desirable to use `--threads=1`. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 32880aafb0..adc6adfd38 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git init' [-q | --quiet] [--bare] [--template=<template_directory>] - [--separate-git-dir <git dir>] + [--separate-git-dir <git dir>] [--object-format=<format] [--shared[=<permissions>]] [directory] @@ -48,6 +48,11 @@ Only print error and warning messages; all other output will be suppressed. Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. +--object-format=<format>:: + +Specify the given object format (hash algorithm) for the repository. The valid +values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. + --template=<template_directory>:: Specify the directory from which templates will be used. (See the "TEMPLATE diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index bed09bb09e..20e6d21a74 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -43,12 +43,16 @@ OPTIONS If no `--decorate-refs` is given, pretend as if all refs were included. For each candidate, do not use it for decoration if it matches any patterns given to `--decorate-refs-exclude` or if it - doesn't match any of the patterns given to `--decorate-refs`. + doesn't match any of the patterns given to `--decorate-refs`. The + `log.excludeDecoration` config option allows excluding refs from + the decorations, but an explicit `--decorate-refs` pattern will + override a match in `log.excludeDecoration`. --source:: Print out the ref name given on the command line by which each commit was reached. +--[no-]mailmap:: --[no-]use-mailmap:: Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. See diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 8461c0e83e..3cb2ebb438 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -148,7 +148,7 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. + Recursively calls ls-files on each active submodule in the repository. Currently there is only support for the --cached mode. --abbrev[=<n>]:: diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index a2ea1fd687..0a5c8b7d49 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -28,7 +28,9 @@ OPTIONS Limit to only refs/heads and refs/tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. + displayed. Note that `git ls-remote -h` used without + anything else on the command line gives help, consistent + with other git subcommands. --refs:: Do not show peeled tags or pseudorefs like `HEAD` in the output. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 092529c619..3819fadac1 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -94,7 +94,8 @@ will be appended to the specified message. --abort:: Abort the current conflict resolution process, and - try to reconstruct the pre-merge state. + try to reconstruct the pre-merge state. If an autostash entry is + present, apply it to the worktree. + If there were uncommitted worktree changes present when the merge started, 'git merge --abort' will in some cases be unable to @@ -102,11 +103,15 @@ reconstruct these changes. It is therefore recommended to always commit or stash your changes before running 'git merge'. + 'git merge --abort' is equivalent to 'git reset --merge' when -`MERGE_HEAD` is present. +`MERGE_HEAD` is present unless `MERGE_AUTOSTASH` is also present in +which case 'git merge --abort' applies the stash entry to the worktree +whereas 'git reset --merge' will save the stashed changes in the stash +list. --quit:: Forget about the current merge in progress. Leave the index - and the working tree as-is. + and the working tree as-is. If `MERGE_AUTOSTASH` is present, the + stash entry will be saved to the stash list. --continue:: After a 'git merge' stops due to conflicts you can conclude the diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 3494a1db3e..dab9609013 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -374,14 +374,55 @@ These options can be used to modify 'git p4 submit' behavior. been submitted. Implies --disable-rebase. Can also be set with git-p4.disableP4Sync. Sync with origin/master still goes ahead if possible. -Hook for submit -~~~~~~~~~~~~~~~ +Hooks for submit +---------------- + +p4-pre-submit +~~~~~~~~~~~~~ + The `p4-pre-submit` hook is executed if it exists and is executable. The hook takes no parameters and nothing from standard input. Exiting with non-zero status from this script prevents `git-p4 submit` from launching. +It can be bypassed with the `--no-verify` command line option. One usage scenario is to run unit tests in the hook. +p4-prepare-changelist +~~~~~~~~~~~~~~~~~~~~~ + +The `p4-prepare-changelist` hook is executed right after preparing +the default changelist message and before the editor is started. +It takes one parameter, the name of the file that contains the +changelist text. Exiting with a non-zero status from the script +will abort the process. + +The purpose of the hook is to edit the message file in place, +and it is not supressed by the `--no-verify` option. This hook +is called even if `--prepare-p4-only` is set. + +p4-changelist +~~~~~~~~~~~~~ + +The `p4-changelist` hook is executed after the changelist +message has been edited by the user. It can be bypassed with the +`--no-verify` option. It takes a single parameter, the name +of the file that holds the proposed changelist text. Exiting +with a non-zero status causes the command to abort. + +The hook is allowed to edit the changelist file and can be used +to normalize the text into some project standard format. It can +also be used to refuse the Submit after inspect the message file. + +p4-post-changelist +~~~~~~~~~~~~~~~~~~ + +The `p4-post-changelist` hook is invoked after the submit has +successfully occured in P4. It takes no parameters and is meant +primarily for notification and cannot affect the outcome of the +git p4 submit action. + + + Rebase options ~~~~~~~~~~~~~~ These options can be used to modify 'git p4 rebase' behavior. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index fecdf2600c..eaa2f2a404 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -14,7 +14,7 @@ SYNOPSIS [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] [--sparse] < object-list + [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list DESCRIPTION @@ -196,14 +196,16 @@ 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 +--[no-]sparse:: + Toggle the "sparse" algorithm to determine which objects to include in the pack, when combined with the "--revs" option. This algorithm only walks trees that appear in paths that introduce new objects. This can have significant performance benefits when computing a pack to send a small change. However, it is possible that extra objects are added to the pack-file if the included commits contain - certain types of direct renames. + certain types of direct renames. If this option is not included, + it defaults to the value of `pack.useSparse`, which is true unless + otherwise specified. --thin:: Create a "thin" pack by omitting the common objects between a diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index dfb901f8b8..5c3fb67c01 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,8 +85,9 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[no-]recurse-submodules[=yes|on-demand|no]:: - This option controls if new commits of all populated submodules should - be fetched and updated, too (see linkgit:git-config[1] and + This option controls if new commits of populated submodules should + be fetched, and if the working trees of active submodules should be + updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]). + If the checkout is done via rebase, local submodule commits are rebased as well. @@ -133,15 +134,6 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: Override earlier --rebase. ---autostash:: ---no-autostash:: - Before starting rebase, stash local modifications away (see - linkgit:git-stash[1]) if needed, and apply the stash entry when - done. `--no-autostash` is useful to override the `rebase.autoStash` - configuration variable (see linkgit:git-config[1]). -+ -This option is only valid when "--rebase" is used. - Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -229,9 +221,9 @@ branch.<name>.merge options; see linkgit:git-config[1] for details. $ git pull origin next ------------------------------------------------ + -This leaves a copy of `next` temporarily in FETCH_HEAD, but -does not update any remote-tracking branches. Using remote-tracking -branches, the same can be done by invoking fetch and merge: +This leaves a copy of `next` temporarily in FETCH_HEAD, and +updates the remote-tracking branch `origin/next`. +The same can be done by invoking fetch and merge: + ------------------------------------------------ $ git fetch origin diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index da33f84f33..5fa8bab64c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -116,9 +116,9 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by - calling read-tree recursively, also setting the submodules HEAD to be + calling read-tree recursively, also setting the submodules' HEAD to be detached at that commit. --no-sparse-checkout:: diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 0c4f038dd6..4624cfd288 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -256,18 +256,79 @@ See also INCOMPATIBLE OPTIONS below. --quit:: Abort the rebase operation but HEAD is not reset back to the original branch. The index and working tree are also left - unchanged as a result. + unchanged as a result. If a temporary stash entry was created + using --autostash, it will be saved to the stash list. +--apply: + Use applying strategies to rebase (calling `git-am` + internally). This option may become a no-op in the future + once the merge backend handles everything the apply one does. ++ +See also INCOMPATIBLE OPTIONS below. + +--empty={drop,keep,ask}:: + How to handle commits that are not empty to start and are not + clean cherry-picks of any upstream commit, but which become + empty after rebasing (because they contain a subset of already + upstream changes). With drop (the default), commits that + become empty are dropped. With keep, such commits are kept. + With ask (implied by --interactive), the rebase will halt when + an empty commit is applied allowing you to choose whether to + drop it, edit files more, or just commit the empty changes. + Other options, like --exec, will use the default of drop unless + -i/--interactive is explicitly specified. ++ +Note that commits which start empty are kept (unless --no-keep-empty +is specified), and commits which are clean cherry-picks (as determined +by `git log --cherry-mark ...`) are detected and dropped as a +preliminary step (unless --reapply-cherry-picks is passed). ++ +See also INCOMPATIBLE OPTIONS below. + +--no-keep-empty:: --keep-empty:: - Keep the commits that do not change anything from its - parents in the result. + Do not keep commits that start empty before the rebase + (i.e. that do not change anything from its parent) in the + result. The default is to keep commits which start empty, + since creating such commits requires passing the --allow-empty + override flag to `git commit`, signifying that a user is very + intentionally creating such a commit and thus wants to keep + it. ++ +Usage of this flag will probably be rare, since you can get rid of +commits that start empty by just firing up an interactive rebase and +removing the lines corresponding to the commits you don't want. This +flag exists as a convenient shortcut, such as for cases where external +tools generate many empty commits and you want them all removed. ++ +For commits which do not start empty but become empty after rebasing, +see the --empty flag. ++ +See also INCOMPATIBLE OPTIONS below. + +--reapply-cherry-picks:: +--no-reapply-cherry-picks:: + Reapply all clean cherry-picks of any upstream commit instead + of preemptively dropping them. (If these commits then become + empty after rebasing, because they contain a subset of already + upstream changes, the behavior towards them is controlled by + the `--empty` flag.) ++ +By default (or if `--no-reapply-cherry-picks` is given), these commits +will be automatically dropped. Because this necessitates reading all +upstream commits, this can be expensive in repos with a large number +of upstream commits that need to be read. ++ +`--reapply-cherry-picks` allows rebase to forgo reading all upstream +commits, potentially improving performance. + See also INCOMPATIBLE OPTIONS below. --allow-empty-message:: - By default, rebasing commits with an empty message will fail. - This option overrides that behavior, allowing commits with empty - messages to be rebased. + No-op. Rebasing commits with an empty message used to fail + and this option would override that behavior, allowing commits + with empty messages to be rebased. Now commits with an empty + message do not cause rebasing to halt. + See also INCOMPATIBLE OPTIONS below. @@ -286,7 +347,7 @@ See also INCOMPATIBLE OPTIONS below. --merge:: Use merging strategies to rebase. When the recursive (default) merge strategy is used, this allows rebase to be aware of renames on the - upstream side. + upstream side. This is the default. + Note that a rebase merge works by replaying each commit from the working branch on top of the <upstream> branch. Because of this, when a merge @@ -325,9 +386,12 @@ See also INCOMPATIBLE OPTIONS below. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. -q:: --quiet:: @@ -356,7 +420,7 @@ See also INCOMPATIBLE OPTIONS below. Ensure at least <n> lines of surrounding context match before and after each change. When fewer lines of surrounding context exist they all must match. By default no context is - ever ignored. + ever ignored. Implies --apply. + See also INCOMPATIBLE OPTIONS below. @@ -385,17 +449,20 @@ When --fork-point is active, 'fork_point' will be used instead of <branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' ends up being empty, the <upstream> will be used as a fallback. + -If either <upstream> or --root is given on the command line, then the -default is `--no-fork-point`, otherwise the default is `--fork-point`. +If <upstream> is given on the command line, then the default is +`--no-fork-point`, otherwise the default is `--fork-point`. + If your branch was based on <upstream> but <upstream> was rewound and your branch contains commits which were dropped, this option can be used with `--keep-base` in order to drop those commits from your branch. ++ +See also INCOMPATIBLE OPTIONS below. --ignore-whitespace:: --whitespace=<option>:: - These flag are passed to the 'git apply' program + These flags are passed to the 'git apply' program (see linkgit:git-apply[1]) that applies the patch. + Implies --apply. + See also INCOMPATIBLE OPTIONS below. @@ -539,10 +606,11 @@ INCOMPATIBLE OPTIONS The following options: + * --apply * --committer-date-is-author-date * --ignore-date - * --whitespace * --ignore-whitespace + * --whitespace * -C are incompatible with the following options: @@ -556,7 +624,9 @@ are incompatible with the following options: * --preserve-merges * --interactive * --exec - * --keep-empty + * --no-keep-empty + * --empty= + * --reapply-cherry-picks * --edit-todo * --root when used in combination with --onto @@ -565,33 +635,149 @@ In addition, the following pairs of options are incompatible: * --preserve-merges and --interactive * --preserve-merges and --signoff * --preserve-merges and --rebase-merges + * --preserve-merges and --empty= * --keep-base and --onto * --keep-base and --root + * --fork-point and --root BEHAVIORAL DIFFERENCES ----------------------- -There are some subtle differences how the backends behave. +git rebase has two primary backends: apply and merge. (The apply +backend used to be known as the 'am' backend, but the name led to +confusion as it looks like a verb instead of a noun. Also, the merge +backend used to be known as the interactive backend, but it is now +used for non-interactive cases as well. Both were renamed based on +lower-level functionality that underpinned each.) There are some +subtle differences in how these two backends behave: 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 apply backend unfortunately drops intentionally empty commits, i.e. +commits that started empty, though these are rare in practice. It +also drops commits that become empty and has no option for controlling +this behavior. + +The merge backend keeps intentionally empty commits by default (though +with -i they are marked as empty in the todo list editor, or they can +be dropped automatically with --no-keep-empty). -The 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. +Similar to the apply backend, by default the merge backend drops +commits that become empty unless -i/--interactive is specified (in +which case it stops and asks the user what to do). The merge backend +also has an --empty={drop,keep,ask} option for changing the behavior +of handling commits that become empty. Directory rename detection ~~~~~~~~~~~~~~~~~~~~~~~~~~ -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. +Due to the lack of accurate tree information (arising from +constructing fake ancestors with the limited information available in +patches), directory rename detection is disabled in the apply backend. +Disabled directory rename detection means that if one side of history +renames a directory and the other adds new files to the old directory, +then the new files will be left behind in the old directory without +any warning at the time of rebasing that you may want to move these +files into the new directory. + +Directory rename detection works with the merge backend to provide you +warnings in such cases. + +Context +~~~~~~~ + +The apply backend works by creating a sequence of patches (by calling +`format-patch` internally), and then applying the patches in sequence +(calling `am` internally). Patches are composed of multiple hunks, +each with line numbers, a context region, and the actual changes. The +line numbers have to be taken with some fuzz, since the other side +will likely have inserted or deleted lines earlier in the file. The +context region is meant to help find how to adjust the line numbers in +order to apply the changes to the right lines. However, if multiple +areas of the code have the same surrounding lines of context, the +wrong one can be picked. There are real-world cases where this has +caused commits to be reapplied incorrectly with no conflicts reported. +Setting diff.context to a larger value may prevent such types of +problems, but increases the chance of spurious conflicts (since it +will require more lines of matching context to apply). + +The merge backend works with a full copy of each relevant file, +insulating it from these types of problems. + +Labelling of conflicts markers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When there are content conflicts, the merge machinery tries to +annotate each side's conflict markers with the commits where the +content came from. Since the apply backend drops the original +information about the rebased commits and their parents (and instead +generates new fake commits based off limited information in the +generated patches), those commits cannot be identified; instead it has +to fall back to a commit summary. Also, when merge.conflictStyle is +set to diff3, the apply backend will use "constructed merge base" to +label the content from the merge base, and thus provide no information +about the merge base commit whatsoever. + +The merge backend works with the full commits on both sides of history +and thus has no such limitations. + +Hooks +~~~~~ + +The apply backend has not traditionally called the post-commit hook, +while the merge backend has. Both have called the post-checkout hook, +though the merge backend has squelched its output. Further, both +backends only call the post-checkout hook with the starting point +commit of the rebase, not the intermediate commits nor the final +commit. In each case, the calling of these hooks was by accident of +implementation rather than by design (both backends were originally +implemented as shell scripts and happened to invoke other commands +like 'git checkout' or 'git commit' that would call the hooks). Both +backends should have the same behavior, though it is not entirely +clear which, if any, is correct. We will likely make rebase stop +calling either of these hooks in the future. + +Interruptability +~~~~~~~~~~~~~~~~ + +The apply backend has safety problems with an ill-timed interrupt; if +the user presses Ctrl-C at the wrong time to try to abort the rebase, +the rebase can enter a state where it cannot be aborted with a +subsequent `git rebase --abort`. The merge backend does not appear to +suffer from the same shortcoming. (See +https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for +details.) + +Commit Rewording +~~~~~~~~~~~~~~~~ + +When a conflict occurs while rebasing, rebase stops and asks the user +to resolve. Since the user may need to make notable changes while +resolving conflicts, after conflicts are resolved and the user has run +`git rebase --continue`, the rebase should open an editor and ask the +user to update the commit message. The merge backend does this, while +the apply backend blindly applies the original commit message. + +Miscellaneous differences +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few more behavioral differences that most folks would +probably consider inconsequential but which are mentioned for +completeness: + +* Reflog: The two backends will use different wording when describing + the changes made in the reflog, though both will make use of the + word "rebase". + +* Progress, informational, and error messages: The two backends + provide slightly different progress and informational messages. + Also, the apply backend writes error messages (such as "Your files + would be overwritten...") to stdout, while the merge backend writes + them to stderr. + +* State directories: The two backends keep their state in different + directories under .git/ include::merge-strategies.txt[] @@ -866,7 +1052,8 @@ Only works if the changes (patch IDs based on the diff contents) on 'subsystem' did. In that case, the fix is easy because 'git rebase' knows to skip -changes that are already present in the new upstream. So if you say +changes that are already present in the new upstream (unless +`--reapply-cherry-picks` is given). So if you say (assuming you're on 'topic') ------------ $ git rebase subsystem diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..252e2d4e47 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the working tree of all active submodules + according to the commit recorded in the superproject, also setting + the submodules' HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..84c6c40010 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -22,9 +22,8 @@ The command can also be used to restore the content in the index with `--staged`, or restore both the working tree and the index with `--staged --worktree`. -By default, the restore sources for working tree and the index are the -index and `HEAD` respectively. `--source` could be used to specify a -commit as the restore source. +By default, if `--staged` is given, the contents are restored from `HEAD`, +otherwise from the index. Use `--source` to restore from a different commit. See "Reset, restore and revert" in linkgit:git[1] for the differences between the three commands. @@ -39,10 +38,8 @@ OPTIONS tree. It is common to specify the source tree by naming a commit, branch or tag associated with it. + -If not specified, the default restore source for the working tree is -the index, and the default restore source for the index is -`HEAD`. When both `--staged` and `--worktree` are specified, -`--source` must also be specified. +If not specified, the contents are restored from `HEAD` if `--staged` is +given, otherwise from the index. -p:: --patch:: @@ -107,6 +104,17 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names an active submodule and the restore location + includes the working tree, the submodule will only be updated if + this option is given, in which case its working tree will be + restored to the commit recorded in the superproject, and any local + modifications overwritten. If nothing (or + `--no-recurse-submodules`) is used, submodules working trees will + not be updated. Just like linkgit:git-checkout[1], this will detach + `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 9d22270757..044276e9da 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -90,9 +90,12 @@ effect to your index in a row. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign commits. The `keyid` argument is optional and defaults to the committer identity; if specified, it must be - stuck to the option without a space. + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. -s:: --signoff:: diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index b5c46223c4..ab750367fd 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -8,16 +8,18 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- [verse] -'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... +'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] + [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...] DESCRIPTION ----------- -Remove files from the index, or from the working tree and the index. -`git rm` will not remove a file from just your working directory. -(There is no option to remove a file only from the working tree -and yet keep it in the index; use `/bin/rm` if you want to do that.) -The files being removed have to be identical to the tip of the branch, -and no updates to their contents can be staged in the index, +Remove files matching pathspec from the index, or from the working tree +and the index. `git rm` will not remove a file from just your working +directory. (There is no option to remove a file only from the working +tree and yet keep it in the index; use `/bin/rm` if you want to do +that.) The files being removed have to be identical to the tip of the +branch, and no updates to their contents can be staged in the index, though that default behavior can be overridden with the `-f` option. When `--cached` is given, the staged content has to match either the tip of the branch or the file on disk, @@ -26,15 +28,20 @@ allowing the file to be removed from just the index. OPTIONS ------- -<file>...:: - Files to remove. Fileglobs (e.g. `*.c`) can be given to - remove all matching files. If you want Git to expand - file glob characters, you may need to shell-escape them. - A leading directory name - (e.g. `dir` to remove `dir/file1` and `dir/file2`) can be - given to remove all files in the directory, and recursively - all sub-directories, - but this requires the `-r` option to be explicitly given. +<pathspec>...:: + Files to remove. A leading directory name (e.g. `dir` to remove + `dir/file1` and `dir/file2`) can be given to remove all files in + the directory, and recursively all sub-directories, but this + requires the `-r` option to be explicitly given. ++ +The command removes only the paths that are known to Git. ++ +File globbing matches across directory boundaries. Thus, given two +directories `d` and `d2`, there is a difference between using +`git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all +of directory `d2`. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. -f:: --force:: @@ -68,19 +75,19 @@ OPTIONS `git rm` normally outputs one line (in the form of an `rm` command) for each file removed. This option suppresses that output. +--pathspec-from-file=<file>:: + Pathspec is passed in `<file>` instead of commandline args. If + `<file>` is exactly `-` then standard input is used. Pathspec + elements are separated by LF or CR/LF. Pathspec elements can be + quoted as explained for the configuration variable `core.quotePath` + (see linkgit:git-config[1]). See also `--pathspec-file-nul` and + global `--literal-pathspecs`. -DISCUSSION ----------- - -The <file> list given to the command can be exact pathnames, -file glob patterns, or leading directory names. The command -removes only the paths that are known to Git. Giving the name of -a file that you have not told Git about does not remove that file. +--pathspec-file-nul:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with NUL character and all other characters are taken + literally (including newlines and quotes). -File globbing matches across directory boundaries. Thus, given -two directories `d` and `d2`, there is a difference between -using `git rm 'd*'` and `git rm 'd/*'`, as the former will -also remove all of directory `d2`. REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM -------------------------------------------------------- diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 974ade2238..1a3ace6082 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -41,6 +41,10 @@ COMMANDS To avoid interfering with other worktrees, it first enables the `extensions.worktreeConfig` setting and makes sure to set the `core.sparseCheckout` setting in the worktree-specific config file. ++ +When `--cone` is provided, the `core.sparseCheckoutCone` setting is +also set, allowing for better performance with a limited set of +patterns (see 'CONE PATTERN SET' below). 'set':: Write a set of patterns to the sparse-checkout file, as given as @@ -50,6 +54,31 @@ To avoid interfering with other worktrees, it first enables the + When the `--stdin` option is provided, the patterns are read from standard in as a newline-delimited list instead of from the arguments. ++ +When `core.sparseCheckoutCone` is enabled, the input list is considered a +list of directories instead of sparse-checkout patterns. The command writes +patterns to the sparse-checkout file to include all files contained in those +directories (recursively) as well as files that are siblings of ancestor +directories. The input format matches the output of `git ls-tree --name-only`. +This includes interpreting pathnames that begin with a double quote (") as +C-style quoted strings. + +'add':: + Update the sparse-checkout file to include additional patterns. + By default, these patterns are read from the command-line arguments, + but they can be read from stdin using the `--stdin` option. When + `core.sparseCheckoutCone` is enabled, the given patterns are interpreted + as directory names as in the 'set' subcommand. + +'reapply:: + Reapply the sparsity pattern rules to paths in the working tree. + Commands like merge or rebase can materialize paths to do their + work (e.g. in order to show you a conflict), and other + sparse-checkout commands might fail to sparsify an individual file + (e.g. because it has unstaged changes or conflicts). In such + cases, it can make sense to run `git sparse-checkout reapply` later + after cleaning up affected paths (e.g. resolving conflicts, undoing + or committing changes, etc.). 'disable':: Disable the `core.sparseCheckout` config setting, and restore the @@ -106,7 +135,7 @@ The full pattern set allows for arbitrary pattern matches and complicated inclusion/exclusion rules. These can result in O(N*M) pattern matches when updating the index, where N is the number of patterns and M is the number of paths in the index. To combat this performance issue, a more restricted -pattern set is allowed when `core.spareCheckoutCone` is enabled. +pattern set is allowed when `core.sparseCheckoutCone` is enabled. The accepted patterns in the cone pattern set are: @@ -128,9 +157,12 @@ the following patterns: ---------------- This says "include everything in root, but nothing two levels below root." -If we then add the folder `A/B/C` as a recursive pattern, the folders `A` and -`A/B` are added as parent patterns. The resulting sparse-checkout file is -now + +When in cone mode, the `git sparse-checkout set` subcommand takes a list of +directories instead of a list of sparse-checkout patterns. In this mode, +the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as +a recursive pattern, the directories `A` and `A/B` are added as parent +patterns. The resulting sparse-checkout file is now ---------------- /* diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 53e1a1205d..31f1beb65b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git stash' branch <branchname> [<stash>] 'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [-m|--message <message>] + [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]] 'git stash' clear 'git stash' create [<message>] @@ -43,10 +44,10 @@ created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}` is also possible). Stashes may also be referenced by specifying just the stash index (e.g. the integer `n` is equivalent to `stash@{n}`). -OPTIONS -------- +COMMANDS +-------- -push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--] [<pathspec>...]:: +push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: Save your local modifications to a new 'stash entry' and roll them back to HEAD (in the working tree and in the index). @@ -56,38 +57,13 @@ push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q For quickly making a snapshot, you can omit "push". In this mode, non-option arguments are not allowed to prevent a misspelled subcommand from making an unwanted stash entry. The two exceptions to this -are `stash -p` which acts as alias for `stash push -p` and pathspecs, +are `stash -p` which acts as alias for `stash push -p` and pathspec elements, which are allowed after a double hyphen `--` for disambiguation. -+ -When pathspec is given to 'git stash push', the new stash entry records the -modified states only for the files that match the pathspec. The index -entries and working tree files are then rolled back to the state in -HEAD only for these files, too, leaving files that do not match the -pathspec intact. -+ -If the `--keep-index` option is used, all changes already added to the -index are left intact. -+ -If the `--include-untracked` option is used, all untracked files are also -stashed and then cleaned up with `git clean`, leaving the working directory -in a very clean state. If the `--all` option is used instead then the -ignored files are stashed and cleaned in addition to the untracked files. -+ -With `--patch`, you can interactively select hunks from the diff -between HEAD and the working tree to be stashed. The stash entry is -constructed such that its index state is the same as the index state -of your repository, and its worktree contains only the changes you -selected interactively. The selected changes are then rolled back -from your worktree. See the ``Interactive Mode'' section of -linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -The `--patch` option implies `--keep-index`. You can use -`--no-keep-index` to override this. save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: This option is deprecated in favour of 'git stash push'. It - differs from "stash push" in that it cannot take pathspecs. + differs from "stash push" in that it cannot take pathspec. Instead, all non-option arguments are concatenated to form the stash message. @@ -111,7 +87,7 @@ show [<options>] [<stash>]:: Show the changes recorded in the stash entry as a diff between the stashed contents and the commit back when the stash entry was first - created. When no `<stash>` is given, it shows the latest one. + created. By default, the command shows the diffstat, but it will accept any format known to 'git diff' (e.g., `git stash show -p stash@{1}` to view the second most recent entry in patch form). @@ -128,14 +104,6 @@ pop [--index] [-q|--quiet] [<stash>]:: Applying the state can fail with conflicts; in this case, it is not removed from the stash list. You need to resolve the conflicts by hand and call `git stash drop` manually afterwards. -+ -If the `--index` option is used, then tries to reinstate not only the working -tree's changes, but also the index's ones. However, this can fail, when you -have conflicts (which are stored in the index, where you therefore can no -longer apply the changes as they were originally). -+ -When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must -be a reference of the form `stash@{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: @@ -149,8 +117,7 @@ branch <branchname> [<stash>]:: the commit at which the `<stash>` was originally created, applies the changes recorded in `<stash>` to the new working tree and index. If that succeeds, and `<stash>` is a reference of the form - `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>` - is given, applies the latest one. + `stash@{<revision>}`, it then drops the `<stash>`. + This is useful if the branch on which you ran `git stash push` has changed enough that `git stash apply` fails due to conflicts. Since @@ -166,9 +133,6 @@ clear:: drop [-q|--quiet] [<stash>]:: Remove a single stash entry from the list of stash entries. - When no `<stash>` is given, it removes the latest one. - i.e. `stash@{0}`, otherwise `<stash>` must be a valid stash - log reference of the form `stash@{<revision>}`. create:: @@ -185,6 +149,98 @@ store:: reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "push" above. +OPTIONS +------- +-a:: +--all:: + This option is only valid for `push` and `save` commands. ++ +All ignored and untracked files are also stashed and then cleaned +up with `git clean`. + +-u:: +--include-untracked:: + This option is only valid for `push` and `save` commands. ++ +All untracked files are also stashed and then cleaned up with +`git clean`. + +--index:: + This option is only valid for `pop` and `apply` commands. ++ +Tries to reinstate not only the working tree's changes, but also +the index's ones. However, this can fail, when you have conflicts +(which are stored in the index, where you therefore can no longer +apply the changes as they were originally). + +-k:: +--keep-index:: +--no-keep-index:: + This option is only valid for `push` and `save` commands. ++ +All changes already added to the index are left intact. + +-p:: +--patch:: + This option is only valid for `push` and `save` commands. ++ +Interactively select hunks from the diff between HEAD and the +working tree to be stashed. The stash entry is constructed such +that its index state is the same as the index state of your +repository, and its worktree contains only the changes you selected +interactively. The selected changes are then rolled back from your +worktree. See the ``Interactive Mode'' section of linkgit:git-add[1] +to learn how to operate the `--patch` mode. ++ +The `--patch` option implies `--keep-index`. You can use +`--no-keep-index` to override this. + +--pathspec-from-file=<file>:: + This option is only valid for `push` command. ++ +Pathspec is passed in `<file>` instead of commandline args. If +`<file>` is exactly `-` then standard input is used. Pathspec +elements are separated by LF or CR/LF. Pathspec elements can be +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). See also `--pathspec-file-nul` and +global `--literal-pathspecs`. + +--pathspec-file-nul:: + This option is only valid for `push` command. ++ +Only meaningful with `--pathspec-from-file`. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes). + +-q:: +--quiet:: + This option is only valid for `apply`, `drop`, `pop`, `push`, + `save`, `store` commands. ++ +Quiet, suppress feedback messages. + +\--:: + This option is only valid for `push` command. ++ +Separates pathspec from options for disambiguation purposes. + +<pathspec>...:: + This option is only valid for `push` command. ++ +The new stash entry records the modified states only for the files +that match the pathspec. The index entries and working tree files +are then rolled back to the state in HEAD only for these files, +too, leaving files that do not match the pathspec intact. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. + +<stash>:: + This option is only valid for `apply`, `branch`, `drop`, `pop`, + `show` commands. ++ +A reference of the form `stash@{<revision>}`. When no `<stash>` is +given, the latest stash is assumed (that is, `stash@{0}`). + DISCUSSION ---------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 5232407f68..c9ed2bf3d5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -133,7 +133,7 @@ If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal options. -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]:: +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject @@ -229,7 +229,7 @@ As an example, the command below will show the path and currently checked out commit for each submodule: + -------------- -git submodule foreach 'echo $path `git rev-parse HEAD`' +git submodule foreach 'echo $sm_path `git rev-parse HEAD`' -------------- sync [--recursive] [--] [<path>...]:: @@ -430,6 +430,10 @@ options carefully. Clone new submodules in parallel with as many jobs. Defaults to the `submodule.fetchJobs` option. +--[no-]single-branch:: + This option is only valid for the update command. + Clone only one branch during update: HEAD or one specified by --branch. + <path>...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 197900363b..3759c3a265 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -181,9 +181,9 @@ name, the guessing is aborted. You can explicitly give a name with --recurse-submodules:: --no-recurse-submodules:: Using `--recurse-submodules` will update the content of all - initialized submodules according to the commit recorded in the + active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is - used, the work trees of submodules will not be updated. Just + used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodules. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index c7a6271daf..1489cb09a0 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -549,6 +549,22 @@ The untracked cache extension can be enabled by the `core.untrackedCache` configuration variable (see linkgit:git-config[1]). +NOTES +----- + +Users often try to use the assume-unchanged and skip-worktree bits +to tell Git to ignore changes to files that are tracked. This does not +work as expected, since Git may still check working tree files against +the index when performing certain operations. In general, Git does not +provide a way to ignore changes to tracked files, so alternate solutions +are recommended. + +For example, if the file you want to change is some sort of config file, +the repository can include a sample config file that can then be copied +into the ignored name and modified. The repository can even include a +script to treat the sample file as a template, modifying and copying it +automatically. + SEE ALSO -------- linkgit:git-config[1], diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 9671423117..3e737c2360 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -66,6 +66,10 @@ performs all modifications together. Specify commands of the form: delete SP <ref> [SP <oldvalue>] LF verify SP <ref> [SP <oldvalue>] LF option SP <opt> LF + start LF + prepare LF + commit LF + abort LF With `--create-reflog`, update-ref will create a reflog for each ref even if one would not ordinarily be created. @@ -83,6 +87,10 @@ quoting: delete SP <ref> NUL [<oldvalue>] NUL verify SP <ref> NUL [<oldvalue>] NUL option SP <opt> NUL + start NUL + prepare NUL + commit NUL + abort NUL In this format, use 40 "0" to specify a zero value, and use the empty string to specify a missing value. @@ -107,13 +115,31 @@ delete:: verify:: Verify <ref> against <oldvalue> but do not change it. If - <oldvalue> zero or missing, the ref must not exist. + <oldvalue> is zero or missing, the ref must not exist. option:: Modify behavior of the next command naming a <ref>. The only valid option is `no-deref` to avoid dereferencing a symbolic ref. +start:: + Start a transaction. In contrast to a non-transactional session, a + transaction will automatically abort if the session ends without an + explicit commit. + +prepare:: + Prepare to commit the transaction. This will create lock files for all + queued reference updates. If one reference could not be locked, the + transaction will be aborted. + +commit:: + Commit all reference updates queued for the transaction, ending the + transaction. + +abort:: + Abort the transaction, releasing all locks if the transaction is in + prepared state. + If all <ref>s can be locked with matching <oldvalue>s simultaneously, all modifications are performed. Otherwise, no modifications are performed. Note that while each individual diff --git a/Documentation/git.txt b/Documentation/git.txt index b1597ac002..9d6769e95a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config Do not pipe Git output into a pager. --git-dir=<path>:: - Set the path to the repository. This can also be controlled by - setting the `GIT_DIR` environment variable. It can be an absolute - path or relative path to current working directory. + Set the path to the repository (".git" directory). This can also be + controlled by setting the `GIT_DIR` environment variable. It can be + an absolute path or relative path to current working directory. ++ +Specifying the location of the ".git" directory using this +option (or `GIT_DIR` environment variable) turns off the +repository discovery that tries to find a directory with +".git" subdirectory (which is how the repository and the +top-level of the working tree are discovered), and tells Git +that you are at the top level of the working tree. If you +are not at the top-level directory of the working tree, you +should tell Git where the top-level of the working tree is, +with the `--work-tree=<path>` option (or `GIT_WORK_TREE` +environment variable) ++ +If you just want to run git as if it was started in `<path>` then use +`git -C <path>`. --work-tree=<path>:: Set the path to the working tree. It can be an absolute path @@ -479,16 +493,45 @@ double-quotes and respecting backslash escapes. E.g., the value details. This variable has lower precedence than other path variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... +`GIT_DEFAULT_HASH_ALGORITHM`:: + If this variable is set, the default hash algorithm for new + repositories will be set to this value. This value is currently + ignored when cloning; the setting of the remote repository + is used instead. The default is "sha1". + Git Commits ~~~~~~~~~~~ `GIT_AUTHOR_NAME`:: + The human-readable name used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.name` and + `author.name` configuration settings. + `GIT_AUTHOR_EMAIL`:: + The email address used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.email` and + `author.email` configuration settings. + `GIT_AUTHOR_DATE`:: + The date used for the author identity when creating commit or tag objects, or + when writing reflogs. See linkgit:git-commit[1] for valid formats. + `GIT_COMMITTER_NAME`:: + The human-readable name used in the committer identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.name` and + `committer.name` configuration settings. + `GIT_COMMITTER_EMAIL`:: + The email address used in the author identity when creating commit or + tag objects, or when writing reflogs. Overrides the `user.email` and + `committer.email` configuration settings. + `GIT_COMMITTER_DATE`:: -'EMAIL':: - see linkgit:git-commit-tree[1] + The date used for the committer identity when creating commit or tag objects, or + when writing reflogs. See linkgit:git-commit[1] for valid formats. + +`EMAIL`:: + The email address used in the author and committer identities if no other + relevant environment variable or configuration setting has been set. Git Diffs ~~~~~~~~~ diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 508fe713c4..2d0a03715b 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -824,6 +824,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `markdown` suitable for Markdown documents. + - `matlab` suitable for source code in the MATLAB and Octave languages. - `objc` suitable for source code in the Objective-C language. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 373cfa2264..92e4ba6a2f 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -126,6 +126,11 @@ usage: git describe [<options>] <commit-ish>* --long always use long format --abbrev[=<n>] use <n> digits to display SHA-1s --------------------------------------------- ++ +Note that some subcommand (e.g. `git grep`) may behave differently +when there are things on the command line other than `-h`, but `git +subcmd -h` without anything else on the command line is meant to +consistently give the usage. --help-all:: Some Git commands take options that are only used for plumbing or that diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f880d21dfb..c0b95256cc 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -751,7 +751,7 @@ to it. ================================================ If you make the decision to start your new branch at some other point in the history than the current `HEAD`, you can do so by -just telling 'git checkout' what the base of the checkout would be. +just telling 'git switch' what the base of the checkout would be. In other words, if you have an earlier tag or branch, you'd just do ------------ diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index ea759fdee5..9e481aec85 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -131,7 +131,9 @@ context would not match: because the hostnames differ. Nor would it match `foo.example.com`; Git compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for `http://example.com` would not -match: Git compares the protocols exactly. +match: Git compares the protocols exactly. However, you may use wildcards in +the domain name and other pattern matching techniques as with the `http.<url>.*` +options. If the "pattern" URL does include a path component, then this too must match exactly: the context `https://example.com/bar/baz.git` will match a config @@ -186,7 +188,110 @@ CUSTOM HELPERS -------------- You can write your own custom helpers to interface with any system in -which you keep credentials. See credential.h for details. +which you keep credentials. + +Credential helpers are programs executed by Git to fetch or save +credentials from and to long-term storage (where "long-term" is simply +longer than a single Git process; e.g., credentials may be stored +in-memory for a few minutes, or indefinitely on disk). + +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by Git into a command to be executed using +these rules: + + 1. If the helper string begins with "!", it is considered a shell + snippet, and everything after the "!" becomes the command. + + 2. Otherwise, if the helper string begins with an absolute path, the + verbatim helper string becomes the command. + + 3. Otherwise, the string "git credential-" is prepended to the helper + string, and the result becomes the command. + +The resulting command then has an "operation" argument appended to it +(see below for details), and the result is executed by the shell. + +Here are some example specifications: + +---------------------------------------------------- +# run "git credential-foo" +[credential] + helper = foo + +# same as above, but pass an argument to the helper +[credential] + helper = "foo --bar=baz" + +# the arguments are parsed by the shell, so use shell +# quoting if necessary +[credential] + helper = "foo --bar='whitespace arg'" + +# you can also use an absolute path, which will not use the git wrapper +[credential] + helper = "/path/to/my/helper --with-arguments" + +# or you can specify your own shell snippet +[credential "https://example.com"] + username = your_user + helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f" +---------------------------------------------------- + +Generally speaking, rule (3) above is the simplest for users to specify. +Authors of credential helpers should make an effort to assist their +users by naming their program "git-credential-$NAME", and putting it in +the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a +user to enable it with `git config credential.helper $NAME`. + +When a helper is executed, it will have one "operation" argument +appended to its command line, which is one of: + +`get`:: + + Return a matching credential, if any exists. + +`store`:: + + Store the credential, if applicable to the helper. + +`erase`:: + + Remove a matching credential, if any, from the helper's storage. + +The details of the credential will be provided on the helper's stdin +stream. The exact format is the same as the input/output format of the +`git credential` plumbing command (see the section `INPUT/OUTPUT +FORMAT` in linkgit:git-credential[1] for a detailed specification). + +For a `get` operation, the helper should produce a list of attributes on +stdout in the same format (see linkgit:git-credential[1] for common +attributes). A helper is free to produce a subset, or even no values at +all if it has nothing useful to provide. Any provided attributes will +overwrite those already known about by Git's credential subsystem. + +While it is possible to override all attributes, well behaving helpers +should refrain from doing so for any attribute other than username and +password. + +If a helper outputs a `quit` attribute with a value of `true` or `1`, +no further helpers will be consulted, nor will the user be prompted +(if no credential has been provided, the operation will then fail). + +Similarly, no more helpers will be consulted once both username and +password had been provided. + +For a `store` or `erase` operation, the helper's output is ignored. + +If a helper fails to perform the requested operation or needs to notify +the user of a potential issue, it may write to stderr. + +If it does not support the requested operation (e.g., a read-only store), +it should silently ignore the request. + +If a helper receives any other operation, it should silently ignore the +request. This leaves room for future operations to be added (older +helpers will just ignore the new requests). GIT --- diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt new file mode 100644 index 0000000000..370d62dae4 --- /dev/null +++ b/Documentation/gitfaq.txt @@ -0,0 +1,355 @@ +gitfaq(7) +========= + +NAME +---- +gitfaq - Frequently asked questions about using Git + +SYNOPSIS +-------- +gitfaq + +DESCRIPTION +----------- + +The examples in this FAQ assume a standard POSIX shell, like `bash` or `dash`, +and a user, A U Thor, who has the account `author` on the hosting provider +`git.example.org`. + +Configuration +------------- + +[[user-name]] +What should I put in `user.name`?:: + You should put your personal name, generally a form using a given name + and family name. For example, the current maintainer of Git uses "Junio + C Hamano". This will be the name portion that is stored in every commit + you make. ++ +This configuration doesn't have any effect on authenticating to remote services; +for that, see `credential.username` in linkgit:git-config[1]. + +[[http-postbuffer]] +What does `http.postBuffer` really do?:: + This option changes the size of the buffer that Git uses when pushing + data to a remote over HTTP or HTTPS. If the data is larger than this + size, libcurl, which handles the HTTP support for Git, will use chunked + transfer encoding since it isn't known ahead of time what the size of + the pushed data will be. ++ +Leaving this value at the default size is fine unless you know that either the +remote server or a proxy in the middle doesn't support HTTP/1.1 (which +introduced the chunked transfer encoding) or is known to be broken with chunked +data. This is often (erroneously) suggested as a solution for generic push +problems, but since almost every server and proxy supports at least HTTP/1.1, +raising this value usually doesn't solve most push problems. A server or proxy +that didn't correctly support HTTP/1.1 and chunked transfer encoding wouldn't be +that useful on the Internet today, since it would break lots of traffic. ++ +Note that increasing this value will increase the memory used on every relevant +push that Git does over HTTP or HTTPS, since the entire buffer is allocated +regardless of whether or not it is all used. Thus, it's best to leave it at the +default unless you are sure you need a different value. + +[[configure-editor]] +How do I configure a different editor?:: + If you haven't specified an editor specifically for Git, it will by default + use the editor you've configured using the `VISUAL` or `EDITOR` environment + variables, or if neither is specified, the system default (which is usually + `vi`). Since some people find `vi` difficult to use or prefer a different + editor, it may be desirable to change the editor used. ++ +If you want to configure a general editor for most programs which need one, you +can edit your shell configuration (e.g., `~/.bashrc` or `~/.zshenv`) to contain +a line setting the `EDITOR` or `VISUAL` environment variable to an appropriate +value. For example, if you prefer the editor `nano`, then you could write the +following: ++ +---- +export VISUAL=nano +---- ++ +If you want to configure an editor specifically for Git, you can either set the +`core.editor` configuration value or the `GIT_EDITOR` environment variable. You +can see linkgit:git-var[1] for details on the order in which these options are +consulted. ++ +Note that in all cases, the editor value will be passed to the shell, so any +arguments containing spaces should be appropriately quoted. Additionally, if +your editor normally detaches from the terminal when invoked, you should specify +it with an argument that makes it not do that, or else Git will not see any +changes. An example of a configuration addressing both of these issues on +Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`, +which quotes the filename with spaces and specifies the `--nofork` option to +avoid backgrounding the process. + +Credentials +----------- + +[[http-credentials]] +How do I specify my credentials when pushing over HTTP?:: + The easiest way to do this is to use a credential helper via the + `credential.helper` configuration. Most systems provide a standard + choice to integrate with the system credential manager. For example, + Git for Windows provides the `wincred` credential manager, macOS has the + `osxkeychain` credential manager, and Unix systems with a standard + desktop environment can use the `libsecret` credential manager. All of + these store credentials in an encrypted store to keep your passwords or + tokens secure. ++ +In addition, you can use the `store` credential manager which stores in a file +in your home directory, or the `cache` credential manager, which does not +permanently store your credentials, but does prevent you from being prompted for +them for a certain period of time. ++ +You can also just enter your password when prompted. While it is possible to +place the password (which must be percent-encoded) in the URL, this is not +particularly secure and can lead to accidental exposure of credentials, so it is +not recommended. + +[[http-credentials-environment]] +How do I read a password or token from an environment variable?:: + The `credential.helper` configuration option can also take an arbitrary + shell command that produces the credential protocol on standard output. + This is useful when passing credentials into a container, for example. ++ +Such a shell command can be specified by starting the option value with an +exclamation point. If your password or token were stored in the `GIT_TOKEN`, +you could run the following command to set your credential helper: ++ +---- +$ git config credential.helper \ + '!f() { echo username=author; echo "password=$GIT_TOKEN"; };f' +---- + +[[http-reset-credentials]] +How do I change the password or token I've saved in my credential manager?:: + Usually, if the password or token is invalid, Git will erase it and + prompt for a new one. However, there are times when this doesn't always + happen. To change the password or token, you can erase the existing + credentials and then Git will prompt for new ones. To erase + credentials, use a syntax like the following (substituting your username + and the hostname): ++ +---- +$ echo url=https://author@git.example.org | git credential reject +---- + +[[multiple-accounts-http]] +How do I use multiple accounts with the same hosting provider using HTTP?:: + Usually the easiest way to distinguish between these accounts is to use + the username in the URL. For example, if you have the accounts `author` + and `committer` on `git.example.org`, you can use the URLs + https://author@git.example.org/org1/project1.git and + https://committer@git.example.org/org2/project2.git. This way, when you + use a credential helper, it will automatically try to look up the + correct credentials for your account. If you already have a remote set + up, you can change the URL with something like `git remote set-url + origin https://author@git.example.org/org1/project1.git` (see + linkgit:git-remote[1] for details). + +[[multiple-accounts-ssh]] +How do I use multiple accounts with the same hosting provider using SSH?:: + With most hosting providers that support SSH, a single key pair uniquely + identifies a user. Therefore, to use multiple accounts, it's necessary + to create a key pair for each account. If you're using a reasonably + modern OpenSSH version, you can create a new key pair with something + like `ssh-keygen -t ed25519 -f ~/.ssh/id_committer`. You can then + register the public key (in this case, `~/.ssh/id_committer.pub`; note + the `.pub`) with the hosting provider. ++ +Most hosting providers use a single SSH account for pushing; that is, all users +push to the `git` account (e.g., `git@git.example.org`). If that's the case for +your provider, you can set up multiple aliases in SSH to make it clear which key +pair to use. For example, you could write something like the following in +`~/.ssh/config`, substituting the proper private key file: ++ +---- +# This is the account for author on git.example.org. +Host example_author + HostName git.example.org + User git + # This is the key pair registered for author with git.example.org. + IdentityFile ~/.ssh/id_author + IdentitiesOnly yes +# This is the account for committer on git.example.org. +Host example_committer + HostName git.example.org + User git + # This is the key pair registered for committer with git.example.org. + IdentityFile ~/.ssh/id_committer + IdentitiesOnly yes +---- ++ +Then, you can adjust your push URL to use `git@example_author` or +`git@example_committer` instead of `git@example.org` (e.g., `git remote set-url +git@example_author:org1/project1.git`). + +Common Issues +------------- + +[[last-commit-amend]] +I've made a mistake in the last commit. How do I change it?:: + You can make the appropriate change to your working tree, run `git add + <file>` or `git rm <file>`, as appropriate, to stage it, and then `git + commit --amend`. Your change will be included in the commit, and you'll + be prompted to edit the commit message again; if you wish to use the + original message verbatim, you can use the `--no-edit` option to `git + commit` in addition, or just save and quit when your editor opens. + +[[undo-previous-change]] +I've made a change with a bug and it's been included in the main branch. How should I undo it?:: + The usual way to deal with this is to use `git revert`. This preserves + the history that the original change was made and was a valuable + contribution, but also introduces a new commit that undoes those changes + because the original had a problem. The commit message of the revert + indicates the commit which was reverted and is usually edited to include + an explanation as to why the revert was made. + +[[ignore-tracked-files]] +How do I ignore changes to a tracked file?:: + Git doesn't provide a way to do this. The reason is that if Git needs + to overwrite this file, such as during a checkout, it doesn't know + whether the changes to the file are precious and should be kept, or + whether they are irrelevant and can safely be destroyed. Therefore, it + has to take the safe route and always preserve them. ++ +It's tempting to try to use certain features of `git update-index`, namely the +assume-unchanged and skip-worktree bits, but these don't work properly for this +purpose and shouldn't be used this way. ++ +If your goal is to modify a configuration file, it can often be helpful to have +a file checked into the repository which is a template or set of defaults which +can then be copied alongside and modified as appropriate. This second, modified +file is usually ignored to prevent accidentally committing it. + +[[files-in-.gitignore-are-tracked]] +I asked Git to ignore various files, yet they are still tracked:: + A `gitignore` file ensures that certain file(s) which are not + tracked by Git remain untracked. However, sometimes particular + file(s) may have been tracked before adding them into the + `.gitignore`, hence they still remain tracked. To untrack and + ignore files/patterns, use `git rm --cached <file/pattern>` + and add a pattern to `.gitignore` that matches the <file>. + See linkgit:gitignore[5] for details. + +[[fetching-and-pulling]] +How do I know if I want to do a fetch or a pull?:: + A fetch stores a copy of the latest changes from the remote + repository, without modifying the working tree or current branch. + You can then at your leisure inspect, merge, rebase on top of, or + ignore the upstream changes. A pull consists of a fetch followed + immediately by either a merge or rebase. See linkgit:git-pull[1]. + +Hooks +----- + +[[restrict-with-hooks]] +How do I use hooks to prevent users from making certain changes?:: + The only safe place to make these changes is on the remote repository + (i.e., the Git server), usually in the `pre-receive` hook or in a + continuous integration (CI) system. These are the locations in which + policy can be enforced effectively. ++ +It's common to try to use `pre-commit` hooks (or, for commit messages, +`commit-msg` hooks) to check these things, which is great if you're working as a +solo developer and want the tooling to help you. However, using hooks on a +developer machine is not effective as a policy control because a user can bypass +these hooks with `--no-verify` without being noticed (among various other ways). +Git assumes that the user is in control of their local repositories and doesn't +try to prevent this or tattle on the user. ++ +In addition, some advanced users find `pre-commit` hooks to be an impediment to +workflows that use temporary commits to stage work in progress or that create +fixup commits, so it's better to push these kinds of checks to the server +anyway. + +Cross-Platform Issues +--------------------- + +[[windows-text-binary]] +I'm on Windows and my text files are detected as binary.:: + Git works best when you store text files as UTF-8. Many programs on + Windows support UTF-8, but some do not and only use the little-endian + UTF-16 format, which Git detects as binary. If you can't use UTF-8 with + your programs, you can specify a working tree encoding that indicates + which encoding your files should be checked out with, while still + storing these files as UTF-8 in the repository. This allows tools like + linkgit:git-diff[1] to work as expected, while still allowing your tools + to work. ++ +To do so, you can specify a linkgit:gitattributes[5] pattern with the +`working-tree-encoding` attribute. For example, the following pattern sets all +C files to use UTF-16LE-BOM, which is a common encoding on Windows: ++ +---- +*.c working-tree-encoding=UTF-16LE-BOM +---- ++ +You will need to run `git add --renormalize` to have this take effect. Note +that if you are making these changes on a project that is used across platforms, +you'll probably want to make it in a per-user configuration file or in the one +in `$GIT_DIR/info/attributes`, since making it in a `.gitattributes` file in the +repository will apply to all users of the repository. ++ +See the following entry for information about normalizing line endings as well, +and see linkgit:gitattributes[5] for more information about attribute files. + +[[windows-diff-control-m]] +I'm on Windows and git diff shows my files as having a `^M` at the end.:: + By default, Git expects files to be stored with Unix line endings. As such, + the carriage return (`^M`) that is part of a Windows line ending is shown + because it is considered to be trailing whitespace. Git defaults to showing + trailing whitespace only on new lines, not existing ones. ++ +You can store the files in the repository with Unix line endings and convert +them automatically to your platform's line endings. To do that, set the +configuration option `core.eol` to `native` and see the following entry for +information about how to configure files as text or binary. ++ +You can also control this behavior with the `core.whitespace` setting if you +don't wish to remove the carriage returns from your line endings. + +[[recommended-storage-settings]] +What's the recommended way to store files in Git?:: + While Git can store and handle any file of any type, there are some + settings that work better than others. In general, we recommend that + text files be stored in UTF-8 without a byte-order mark (BOM) with LF + (Unix-style) endings. We also recommend the use of UTF-8 (again, + without BOM) in commit messages. These are the settings that work best + across platforms and with tools such as `git diff` and `git merge`. ++ +Additionally, if you have a choice between storage formats that are text based +or non-text based, we recommend storing files in the text format and, if +necessary, transforming them into the other format. For example, a text-based +SQL dump with one record per line will work much better for diffing and merging +than an actual database file. Similarly, text-based formats such as Markdown +and AsciiDoc will work better than binary formats such as Microsoft Word and +PDF. ++ +Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or +build products in the repository is generally not recommended. Dependencies and +build products are best stored on an artifact or package server with only +references, URLs, and hashes stored in the repository. ++ +We also recommend setting a linkgit:gitattributes[5] file to explicitly mark +which files are text and which are binary. If you want Git to guess, you can +set the attribute `text=auto`. For example, the following might be appropriate +in some projects: ++ +---- +# By default, guess. +* text=auto +# Mark all C files as text. +*.c text +# Mark all JPEG files as binary. +*.jpg binary +---- ++ +These settings help tools pick the right format for output such as patches and +result in files being checked out in the appropriate line ending for the +platform. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 50365f2914..81f2a87e88 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -490,9 +490,16 @@ fsmonitor-watchman ~~~~~~~~~~~~~~~~~~ This hook is invoked when the configuration option `core.fsmonitor` is -set to `.git/hooks/fsmonitor-watchman`. It takes two arguments, a version -(currently 1) and the time in elapsed nanoseconds since midnight, -January 1, 1970. +set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2` +depending on the version of the hook to use. + +Version 1 takes two arguments, a version (1) and the time in elapsed +nanoseconds since midnight, January 1, 1970. + +Version 2 takes two arguments, a version (2) and a token that is used +for identifying changes since the token. For watchman this would be +a clock id. This version must output to stdout the new token followed +by a NUL before the list of files. The hook should output to stdout the list of all files in the working directory that may have changed since the requested time. The logic @@ -515,12 +522,61 @@ The exit status determines whether git will use the data from the hook to limit its search. On error, it will fall back to verifying all files and folders. +p4-changelist +~~~~~~~~~~~~~ + +This hook is invoked by `git-p4 submit`. + +The `p4-changelist` hook is executed after the changelist +message has been edited by the user. It can be bypassed with the +`--no-verify` option. It takes a single parameter, the name +of the file that holds the proposed changelist text. Exiting +with a non-zero status causes the command to abort. + +The hook is allowed to edit the changelist file and can be used +to normalize the text into some project standard format. It can +also be used to refuse the Submit after inspect the message file. + +Run `git-p4 submit --help` for details. + +p4-prepare-changelist +~~~~~~~~~~~~~~~~~~~~~ + +This hook is invoked by `git-p4 submit`. + +The `p4-prepare-changelist` hook is executed right after preparing +the default changelist message and before the editor is started. +It takes one parameter, the name of the file that contains the +changelist text. Exiting with a non-zero status from the script +will abort the process. + +The purpose of the hook is to edit the message file in place, +and it is not supressed by the `--no-verify` option. This hook +is called even if `--prepare-p4-only` is set. + +Run `git-p4 submit --help` for details. + +p4-post-changelist +~~~~~~~~~~~~~~~~~~ + +This hook is invoked by `git-p4 submit`. + +The `p4-post-changelist` hook is invoked after the submit has +successfully occured in P4. It takes no parameters and is meant +primarily for notification and cannot affect the outcome of the +git p4 submit action. + +Run `git-p4 submit --help` for details. + p4-pre-submit ~~~~~~~~~~~~~ This hook is invoked by `git-p4 submit`. It takes no parameters and nothing from standard input. Exiting with non-zero status from this script prevent -`git-p4 submit` from launching. Run `git-p4 submit --help` for details. +`git-p4 submit` from launching. It can be bypassed with the `--no-verify` +command line option. Run `git-p4 submit --help` for details. + + post-index-change ~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index c476f891b5..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse into submodules. The 'init' and 'update' subcommands of 'git submodule' will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index ca4378740c..73be8b49f8 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -154,15 +154,17 @@ by doing the following: - Anything unobvious that is applicable to 'master' (in other words, does not depend on anything that is still in 'next' and not in 'master') is applied to a new topic branch that - is forked from the tip of 'master'. This includes both + is forked from the tip of 'master' (or the last feature release, + which is a bit older than 'master'). This includes both enhancements and unobvious fixes to 'master'. A topic branch is named as ai/topic where "ai" is two-letter string named after author's initial and "topic" is a descriptive name of the topic (in other words, "what's the series is about"). - An unobvious fix meant for 'maint' is applied to a new - topic branch that is forked from the tip of 'maint'. The - topic is named as ai/maint-topic. + topic branch that is forked from the tip of 'maint' (or the + oldest and still relevant maintenance branch). The + topic may be named as ai/maint-topic. - Changes that pertain to an existing topic are applied to the branch, but: @@ -174,24 +176,40 @@ by doing the following: - Replacement patches to an existing topic are accepted only for commits not in 'next'. - The above except the "replacement" are all done with: + The initial round is done with: $ git checkout ai/topic ;# or "git checkout -b ai/topic master" $ git am -sc3 mailbox - while patch replacement is often done by: + and replacing an existing topic with subsequent round is done with: - $ git format-patch ai/topic~$n..ai/topic ;# export existing + $ git checkout master...ai/topic ;# try to reapply to the same base + $ git am -sc3 mailbox + + to prepare the new round on a detached HEAD, and then + + $ git range-diff @{-1}... + $ git diff @{-1} - then replace some parts with the new patch, and reapplying: + to double check what changed since the last round, and finally - $ git checkout ai/topic - $ git reset --hard ai/topic~$n - $ git am -sc3 -s 000*.txt + $ git checkout -B @{-1} + + to conclude (the last step is why a topic already in 'next' is + not replaced but updated incrementally). + + Whether it is the initial round or a subsequent round, the topic + may not build even in isolation, or may break the build when + merged to integration branches due to bugs. There may already + be obvious and trivial improvements suggested on the list. The + maintainer often adds an extra commit, with "SQUASH???" in its + title, to fix things up, before publishing the integration + branches to make it usable by other developers for testing. + These changes are what the maintainer is not 100% committed to + (trivial typofixes etc. are often squashed directly into the + patches that need fixing, without being applied as a separate + "SQUASH???" commit), so that they can be removed easily as needed. - The full test suite is always run for 'maint' and 'master' - after patch application; for topic branches the tests are run - as time permits. - Merge maint to master as needed: @@ -371,6 +389,14 @@ Some observations to be made. be included in the next feature release. Being in the 'master' branch typically is. + * Due to the nature of "SQUASH???" fix-ups, if the original author + agrees with the suggested changes, it is OK to squash them to + appropriate patches in the next round (when the suggested change + is small enough, the author should not even bother with + "Helped-by"). It is also OK to drop them from the next round + when the original author does not agree with the suggestion, but + the author is expected to say why somewhere in the discussion. + Appendix -------- diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl deleted file mode 100644 index b4d315cb8c..0000000000 --- a/Documentation/manpage-1.72.xsl +++ /dev/null @@ -1,14 +0,0 @@ -<!-- manpage-1.72.xsl: - special settings for manpages rendered from asciidoc+docbook - handles peculiarities in docbook-xsl 1.72.0 --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<xsl:import href="manpage-base.xsl"/> - -<!-- these are the special values for the roff control characters - needed for docbook-xsl 1.72.0 --> -<xsl:param name="git.docbook.backslash">▓</xsl:param> -<xsl:param name="git.docbook.dot" >⌂</xsl:param> - -</xsl:stylesheet> diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl deleted file mode 100644 index a264fa6160..0000000000 --- a/Documentation/manpage-base.xsl +++ /dev/null @@ -1,35 +0,0 @@ -<!-- manpage-base.xsl: - special formatting for manpages rendered from asciidoc+docbook --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- these params silence some output from xmlto --> -<xsl:param name="man.output.quietly" select="1"/> -<xsl:param name="refentry.meta.get.quietly" select="1"/> - -<!-- convert asciidoc callouts to man page format; - git.docbook.backslash and git.docbook.dot params - must be supplied by another XSL file or other means --> -<xsl:template match="co"> - <xsl:value-of select="concat( - $git.docbook.backslash,'fB(', - substring-after(@id,'-'),')', - $git.docbook.backslash,'fR')"/> -</xsl:template> -<xsl:template match="calloutlist"> - <xsl:value-of select="$git.docbook.dot"/> - <xsl:text>sp </xsl:text> - <xsl:apply-templates/> - <xsl:text> </xsl:text> -</xsl:template> -<xsl:template match="callout"> - <xsl:value-of select="concat( - $git.docbook.backslash,'fB', - substring-after(@arearefs,'-'), - '. ',$git.docbook.backslash,'fR')"/> - <xsl:apply-templates/> - <xsl:value-of select="$git.docbook.dot"/> - <xsl:text>br </xsl:text> -</xsl:template> - -</xsl:stylesheet> diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl index 94d6c1b545..e13db85693 100644 --- a/Documentation/manpage-bold-literal.xsl +++ b/Documentation/manpage-bold-literal.xsl @@ -8,11 +8,9 @@ this makes literal text easier to distinguish in manpages viewed on a tty --> <xsl:template match="literal|d:literal"> - <xsl:value-of select="$git.docbook.backslash"/> - <xsl:text>fB</xsl:text> + <xsl:text>\fB</xsl:text> <xsl:apply-templates/> - <xsl:value-of select="$git.docbook.backslash"/> - <xsl:text>fR</xsl:text> + <xsl:text>\fR</xsl:text> </xsl:template> </xsl:stylesheet> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl index a48f5b11f3..a9c7ec69f4 100644 --- a/Documentation/manpage-normal.xsl +++ b/Documentation/manpage-normal.xsl @@ -1,13 +1,26 @@ <!-- manpage-normal.xsl: - special settings for manpages rendered from asciidoc+docbook - handles anything we want to keep away from docbook-xsl 1.72.0 --> + special settings for manpages rendered from asciidoc+docbook --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> -<xsl:import href="manpage-base.xsl"/> -<!-- these are the normal values for the roff control characters --> -<xsl:param name="git.docbook.backslash">\</xsl:param> -<xsl:param name="git.docbook.dot" >.</xsl:param> +<!-- these params silence some output from xmlto --> +<xsl:param name="man.output.quietly" select="1"/> +<xsl:param name="refentry.meta.get.quietly" select="1"/> + +<!-- convert asciidoc callouts to man page format --> +<xsl:template match="co"> + <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:text>.sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/> + <xsl:apply-templates/> + <xsl:text>.br </xsl:text> +</xsl:template> </xsl:stylesheet> diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl deleted file mode 100644 index a63c7632a8..0000000000 --- a/Documentation/manpage-suppress-sp.xsl +++ /dev/null @@ -1,21 +0,0 @@ -<!-- manpage-suppress-sp.xsl: - special settings for manpages rendered from asciidoc+docbook - handles erroneous, inline .sp in manpage output of some - versions of docbook-xsl --> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- attempt to work around spurious .sp at the tail of the line - that some versions of docbook stylesheets seem to add --> -<xsl:template match="simpara"> - <xsl:variable name="content"> - <xsl:apply-templates/> - </xsl:variable> - <xsl:value-of select="normalize-space($content)"/> - <xsl:if test="not(ancestor::authorblurb) and - not(ancestor::personblurb)"> - <xsl:text> </xsl:text> - </xsl:if> -</xsl:template> - -</xsl:stylesheet> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 40dc4f5e8c..80d4831662 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -61,9 +61,12 @@ When not possible, refuse to merge and exit with a non-zero status. -S[<keyid>]:: --gpg-sign[=<keyid>]:: +--no-gpg-sign:: GPG-sign the resulting merge commit. The `keyid` argument is optional and defaults to the committer identity; if specified, - it must be stuck to the option without a space. + it must be stuck to the option without a space. `--no-gpg-sign` + is useful to countermand both `commit.gpgSign` configuration variable, + and earlier `--gpg-sign`. --log[=<n>]:: --no-log:: @@ -157,6 +160,14 @@ ifndef::git-pull[] endif::git-pull[] +--autostash:: +--no-autostash:: + Automatically create a temporary stash entry before the operation + begins, and apply it after the operation ends. This means + that you can run the operation on a dirty worktree. However, use + with care: the final stash application after a successful + merge might result in non-trivial conflicts. + --allow-unrelated-histories:: By default, `git merge` command refuses to merge histories that do not share a common ancestor. This option can be diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 1a7212ce5a..547a552463 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like <full commit message> +* 'mboxrd' ++ +Like 'email', but lines in the commit message starting with "From " +(preceded by zero or more ">") are quoted with ">" so they aren't +confused as starting a new commit. + * 'raw' + The 'raw' format shows the entire commit exactly as @@ -226,6 +232,7 @@ endif::git-rev-list[] '%GF':: show the fingerprint of the key used to sign a signed commit '%GP':: show the fingerprint of the primary key whose subkey was used to sign a signed commit +'%GT':: show the trust level for the key used to sign a signed commit '%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2 minutes ago}`; the format follows the rules described for the `-g` option. The portion before the `@` is the refname as diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 7d3a60f5b9..95ea849902 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -19,7 +19,8 @@ ifndef::git-pull[] (see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below). endif::git-pull[] ifdef::git-pull[] - (see linkgit:git-fetch[1]). + (see the section "CONFIGURED REMOTE-TRACKING BRANCHES" + in linkgit:git-fetch[1]). endif::git-pull[] + The format of a <refspec> parameter is an optional plus diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index bfd02ade99..04ad7dd36e 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -342,6 +342,12 @@ Default mode:: branches if the end result is the same (i.e. merging branches with the same content) +--show-pulls:: + Include all commits from the default mode, but also any merge + commits that are not TREESAME to the first parent but are + TREESAME to a later parent. This mode is helpful for showing + the merge commits that "first introduced" a change to a branch. + --full-history:: Same as the default mode, but does not prune some history. @@ -534,7 +540,7 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`: parent and is TREESAME. -- -Finally, there is a fifth simplification mode available: +There is another simplification mode available: --ancestry-path:: Limit the displayed commits to those directly on the ancestry @@ -573,6 +579,132 @@ option does. Applied to the 'D..M' range, it results in: L--M ----------------------------------------------------------------------- +Before discussing another option, `--show-pulls`, we need to +create a new example history. ++ +A common problem users face when looking at simplified history is that a +commit they know changed a file somehow does not appear in the file's +simplified history. Let's demonstrate a new example and show how options +such as `--full-history` and `--simplify-merges` works in that case: ++ +----------------------------------------------------------------------- + .-A---M-----C--N---O---P + / / \ \ \/ / / + I B \ R-'`-Z' / + \ / \/ / + \ / /\ / + `---X--' `---Y--' +----------------------------------------------------------------------- ++ +For this example, suppose `I` created `file.txt` which was modified by +`A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`, +and `Y` do not change `file.txt`. The merge commit `M` was created by +resolving the merge conflict to include both changes from `A` and `B` +and hence is not TREESAME to either. The merge commit `R`, however, was +created by ignoring the contents of `file.txt` at `M` and taking only +the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not +`M`. Finally, the natural merge resolution to create `N` is to take the +contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`. +The merge commits `O` and `P` are TREESAME to their first parents, but +not to their second parents, `Z` and `Y` respectively. ++ +When using the default mode, `N` and `R` both have a TREESAME parent, so +those edges are walked and the others are ignored. The resulting history +graph is: ++ +----------------------------------------------------------------------- + I---X +----------------------------------------------------------------------- ++ +When using `--full-history`, Git walks every edge. This will discover +the commits `A` and `B` and the merge `M`, but also will reveal the +merge commits `O` and `P`. With parent rewriting, the resulting graph is: ++ +----------------------------------------------------------------------- + .-A---M--------N---O---P + / / \ \ \/ / / + I B \ R-'`--' / + \ / \/ / + \ / /\ / + `---X--' `------' +----------------------------------------------------------------------- ++ +Here, the merge commits `O` and `P` contribute extra noise, as they did +not actually contribute a change to `file.txt`. They only merged a topic +that was based on an older version of `file.txt`. This is a common +issue in repositories using a workflow where many contributors work in +parallel and merge their topic branches along a single trunk: manu +unrelated merges appear in the `--full-history` results. ++ +When using the `--simplify-merges` option, the commits `O` and `P` +disappear from the results. This is because the rewritten second parents +of `O` and `P` are reachable from their first parents. Those edges are +removed and then the commits look like single-parent commits that are +TREESAME to their parent. This also happens to the commit `N`, resulting +in a history view as follows: ++ +----------------------------------------------------------------------- + .-A---M--. + / / \ + I B R + \ / / + \ / / + `---X--' +----------------------------------------------------------------------- ++ +In this view, we see all of the important single-parent changes from +`A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the +not-so-carefully-resolved merge `R`. This is usually enough information +to determine why the commits `A` and `B` "disappeared" from history in +the default view. However, there are a few issues with this approach. ++ +The first issue is performance. Unlike any previous option, the +`--simplify-merges` option requires walking the entire commit history +before returning a single result. This can make the option difficult to +use for very large repositories. ++ +The second issue is one of auditing. When many contributors are working +on the same repository, it is important which merge commits introduced +a change into an important branch. The problematic merge `R` above is +not likely to be the merge commit that was used to merge into an +important branch. Instead, the merge `N` was used to merge `R` and `X` +into the important branch. This commit may have information about why +the change `X` came to override the changes from `A` and `B` in its +commit message. ++ +The `--show-pulls` option helps with both of these issues by adding more +merge commits to the history results. If a merge is not TREESAME to its +first parent but is TREESAME to a later parent, then that merge is +treated as if it "pulled" the change from another branch. When using +`--show-pulls` on this example (and no other options) the resulting +graph is: ++ +----------------------------------------------------------------------- + I---X---R---N +----------------------------------------------------------------------- ++ +Here, the merge commits `R` and `N` are included because they pulled +the commits `X` and `R` into the base branch, respectively. These +merges are the reason the commits `A` and `B` do not appear in the +default history. ++ +When `--show-pulls` is paired with `--simplify-merges`, the +graph includes all of the necessary information: ++ +----------------------------------------------------------------------- + .-A---M--. N + / / \ / + I B R + \ / / + \ / / + `---X--' +----------------------------------------------------------------------- ++ +Notice that since `M` is reachable from `R`, the edge from `N` to `M` +was simplified away. However, `N` still appears in the history as an +important commit because it "pulled" the change `R` into the main +branch. + The `--simplify-by-decoration` option allows you to view only the big picture of the topology of the history, by omitting commits that are not referenced by tags. Commits are marked as !TREESAME diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 97f995e5a9..1ad95065c1 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -233,7 +233,7 @@ G H I J A = = A^0 B = A^ = A^1 = A~1 - C = A^2 = A^2 + C = = A^2 D = A^^ = A^1^1 = A~2 E = B^2 = A^^2 F = B^3 = A^^3 diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 4f07ceadcb..6b6085585d 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -656,7 +656,8 @@ The "exec_id" field is a command-unique id and is only useful if the ------------ `"def_param"`:: - This event is generated to log a global parameter. + This event is generated to log a global parameter, such as a config + setting, command-line flag, or environment variable. + ------------ { diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt new file mode 100644 index 0000000000..0e828151a5 --- /dev/null +++ b/Documentation/technical/bundle-format.txt @@ -0,0 +1,48 @@ += Git bundle v2 format + +The Git bundle format is a format that represents both refs and Git objects. + +== Format + +We will use ABNF notation to define the Git bundle format. See +protocol-common.txt for the details. + +---- +bundle = signature *prerequisite *reference LF pack +signature = "# v2 git bundle" LF + +prerequisite = "-" obj-id SP comment LF +comment = *CHAR +reference = obj-id SP refname LF + +pack = ... ; packfile +---- + +== Semantics + +A Git bundle consists of three parts. + +* "Prerequisites" lists the objects that are NOT included in the bundle and the + reader of the bundle MUST already have, in order to use the data in the + bundle. The objects stored in the bundle may refer to prerequisite objects and + anything reachable from them (e.g. a tree object in the bundle can reference + a blob that is reachable from a prerequisite) and/or expressed as a delta + against prerequisite objects. + +* "References" record the tips of the history graph, iow, what the reader of the + bundle CAN "git fetch" from it. + +* "Pack" is the pack data stream "git fetch" would send, if you fetch from a + repository that has the references recorded in the "References" above into a + repository that has references pointing at the objects listed in + "Prerequisites" above. + +In the bundle format, there can be a comment following a prerequisite obj-id. +This is a comment and it has no specific meaning. The writer of the bundle MAY +put any string here. The reader of the bundle MUST ignore the comment. + +=== Note on the shallow clone and a Git bundle + +Note that the prerequisites does not represent a shallow-clone boundary. The +semantics of the prerequisites and the shallow-clone boundaries are different, +and the Git bundle v2 format cannot represent a shallow clone repository. diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index a4f17441ae..de56f9f1ef 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -17,6 +17,9 @@ metadata, including: - The parents of the commit, stored using positional references within the graph file. +- The Bloom filter of the commit carrying the paths that were changed between + the commit and its first parent, if requested. + These positional references are stored as unsigned 32-bit integers corresponding to the array position within the list of commit OIDs. Due to some special constants we use to track parents, we can store at most @@ -93,6 +96,33 @@ CHUNK DATA: positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent. + Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] + * The ith entry, BIDX[i], stores the number of 8-byte word blocks in all + Bloom filters from commit 0 to commit i (inclusive) in lexicographic + order. The Bloom filter for the i-th commit spans from BIDX[i-1] to + BIDX[i] (plus header length), where BIDX[-1] is 0. + * The BIDX chunk is ignored if the BDAT chunk is not present. + + Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] + * It starts with header consisting of three unsigned 32-bit integers: + - Version of the hash algorithm being used. We currently only support + value 1 which corresponds to the 32-bit version of the murmur3 hash + implemented exactly as described in + https://en.wikipedia.org/wiki/MurmurHash#Algorithm and the double + hashing technique using seed values 0x293ae76f and 0x7e646e2 as + described in https://doi.org/10.1007/978-3-540-30494-4_26 "Bloom Filters + in Probabilistic Verification" + - The number of times a path is hashed and hence the number of bit positions + that cumulatively determine whether a file is present in the commit. + - The minimum number of bits 'b' per entry in the Bloom filter. If the filter + contains 'n' entries, then the filter size is the minimum number of 64-bit + words that contain n*b bits. + * The rest of the chunk is the concatenation of all the computed Bloom + filters for the commits in lexicographic order. + * Note: Commits with no changes or more than 512 changes have Bloom filters + of length zero. + * The BDAT chunk is present if and only if BIDX is present. + Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] This list of H-byte hashes describe a set of B commit-graph files that form a commit-graph chain. The graph position for the ith commit in this diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index cab5bdd2ff..d3a142c652 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -315,10 +315,11 @@ CHUNK DATA: Stores two 4-byte values for every object. 1: The pack-int-id for the pack storing this object. 2: The offset within the pack. - If all offsets are less than 2^31, then the large offset chunk + If all offsets are less than 2^32, then the large offset chunk will not exist and offsets are stored as in IDX v1. If there is at least one offset value larger than 2^32-1, then - the large offset chunk must exist. If the large offset chunk + the large offset chunk must exist, and offsets larger than + 2^31-1 must be stored in it instead. If the large offset chunk exists and the 31st bit is on, then removing that bit reveals the row in the large offsets containing the 8-byte offset of this object. diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index d87294de2f..0148f126dc 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -9,13 +9,3 @@ tilde=~ [linkgit-inlinemacro] <ulink url="{target}.html">{target}{0?({0})}</ulink> - -ifdef::backend-docbook[] -# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. -[listingblock] -<example><title>{title}</title> -<literallayout class="monospaced"> -| -</literallayout> -{title#}</example> -endif::backend-docbook[] |