summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/MyFirstContribution.txt36
-rw-r--r--Documentation/RelNotes/2.25.1.txt55
-rw-r--r--Documentation/RelNotes/2.26.0.txt277
-rw-r--r--Documentation/config.txt4
-rw-r--r--Documentation/config/advice.txt6
-rw-r--r--Documentation/config/branch.txt7
-rw-r--r--Documentation/config/core.txt11
-rw-r--r--Documentation/config/gpg.txt15
-rw-r--r--Documentation/config/http.txt12
-rw-r--r--Documentation/config/pack.txt7
-rw-r--r--Documentation/config/protocol.txt9
-rw-r--r--Documentation/config/pull.txt7
-rw-r--r--Documentation/config/push.txt9
-rw-r--r--Documentation/config/rebase.txt6
-rw-r--r--Documentation/config/user.txt7
-rw-r--r--Documentation/diff-options.txt8
-rwxr-xr-xDocumentation/doc-diff2
-rw-r--r--Documentation/fetch-options.txt5
-rw-r--r--Documentation/git-check-ignore.txt12
-rw-r--r--Documentation/git-commit-graph.txt5
-rw-r--r--Documentation/git-commit-tree.txt22
-rw-r--r--Documentation/git-commit.txt40
-rw-r--r--Documentation/git-config.txt15
-rw-r--r--Documentation/git-filter-branch.txt6
-rw-r--r--Documentation/git-grep.txt18
-rw-r--r--Documentation/git-rebase.txt170
-rw-r--r--Documentation/git-sparse-checkout.txt30
-rw-r--r--Documentation/git-submodule.txt2
-rw-r--r--Documentation/git-update-index.txt16
-rw-r--r--Documentation/git.txt47
-rw-r--r--Documentation/gitcore-tutorial.txt2
-rw-r--r--Documentation/gitcredentials.txt93
-rw-r--r--Documentation/githooks.txt13
-rw-r--r--Documentation/pretty-formats.txt1
-rw-r--r--Documentation/technical/bundle-format.txt48
-rw-r--r--Documentation/technical/pack-format.txt5
36 files changed, 924 insertions, 104 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 35b9130..427274d 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/RelNotes/2.25.1.txt b/Documentation/RelNotes/2.25.1.txt
new file mode 100644
index 0000000..cd869b0
--- /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.26.0.txt b/Documentation/RelNotes/2.26.0.txt
new file mode 100644
index 0000000..30ef134
--- /dev/null
+++ b/Documentation/RelNotes/2.26.0.txt
@@ -0,0 +1,277 @@
+Git 2.26 Release Notes
+======================
+
+Updates since v2.25
+-------------------
+
+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").
+
+
+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_funciton", 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.
+
+
+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.
+ (merge 849e43cc18 js/builtin-add-i-cmds later to maint).
+
+ * "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.
+ (merge a9472afb63 pb/recurse-submodule-in-worktree-fix later to maint).
+
+ * 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.
+ (merge 7edee32985 dt/submodule-rm-with-stale-cache later to maint).
+
+ * C pedantry ;-) fix.
+ (merge cf82bff73f jk/clang-sanitizer-fixes later to maint).
+
+ * "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 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.
+ (merge 26027625dd js/rebase-i-with-colliding-hash later to maint).
+
+ * 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.
+ (merge dbc27477ff jh/notes-fanout-fix later to maint).
+
+ * 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.
+ (merge a21781011f jk/index-pack-dupfix later to maint).
+
+ * 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.
+ (merge 2607d39da3 jk/doc-diff-parallel later to maint).
+
+ * Doc markup fix.
+ (merge 0aa6ce3094 jk/push-option-doc-markup-fix later to maint).
+
+ * "git check-ignore" did not work when the given path is explicitly
+ marked as not ignored with a negative entry in the .gitignore file.
+ (merge 7ec8125fba en/check-ignore later to maint).
+
+ * 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.
+ (merge fb1c18fc46 en/t3433-rebase-stat-dirty-failure later to maint).
+
+ * Fix for a bug revealed by a recent change to make the protocol v2
+ the default.
+ (merge 3e96c66805 ds/partial-clone-fixes later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge 26f924d50e en/simplify-check-updates-in-unpack-trees later to maint).
+ (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 076ee3e8a2 js/test-write-junit-xml-fix later to maint).
+ (merge de26f02db1 js/test-avoid-pipe later to maint).
+ (merge bfe2bbb47f js/test-unc-fetch later to maint).
+ (merge 08809c09aa js/mingw-open-in-gdb later to maint).
+ (merge cc4f2eb828 jk/doc-credential-helper later to maint).
+ (merge e0020b2f82 es/outside-repo-errmsg-hints later to maint).
+ (merge a2dc43414c es/doc-mentoring later to maint).
+ (merge 539052f42f jk/run-command-formatfix 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).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 83e7bba..08b13ba 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -263,7 +263,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
diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index 4be93f8..bdd37c3 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 a592d52..cc5f324 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 9e440b1..74619a9 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/gpg.txt b/Documentation/config/gpg.txt
index cce2c89..d94025c 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 5a32f5b..e806033 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -71,7 +71,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 +84,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 +199,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/pack.txt b/Documentation/config/pack.txt
index 1d66f0c..0dac580 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]
diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt
index bfccc07..756591d 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 `2`.
Supported versions:
+
--
diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.txt
index b87cab3..5404830 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 0a0e000..0a7aa32 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
diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt
index d98e32d..7f7a07d 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/user.txt b/Documentation/config/user.txt
index 0557cbb..59aec7c 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/diff-options.txt b/Documentation/diff-options.txt
index 09faee3..bb31f0c 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, &regmatch, 0);
++ return frotz(nitfol, two->ptr, 1, 0);
...
-- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 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 88a9b20..1694300 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 a2f7862..a115a1a 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -139,7 +139,10 @@ ifndef::git-pull[]
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::
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index 8b2d49c..0c3924a 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-commit-graph.txt b/Documentation/git-commit-graph.txt
index bcd85c1..28d1fee 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
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 4b90b9c..ec15ee8 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -69,7 +69,6 @@ OPTIONS
Do not GPG-sign commit, to countermand a `--gpg-sign` option
given earlier on the command line.
-
Commit Information
------------------
@@ -79,26 +78,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 +96,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 ced5a9b..13f6539 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -367,9 +367,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 +460,43 @@ alter the order the changes are committed, because the merge
should be recorded as a single commit. In fact, the command
refuses to run when given pathnames (but see `-i` option).
+COMMIT INFORMATION
+------------------
+
+Author and committer information is taken from the following environment
+variables, if set:
+
+ GIT_AUTHOR_NAME
+ GIT_AUTHOR_EMAIL
+ GIT_AUTHOR_DATE
+ GIT_COMMITTER_NAME
+ GIT_COMMITTER_EMAIL
+ GIT_COMMITTER_DATE
+
+(nb "<", ">" and "\n"s are stripped)
+
+The author and committer names are by convention some form of a personal name
+(that is, the name by which other humans refer to you), although Git does not
+enforce or require any particular form. Arbitrary Unicode may be used, subject
+to the constraints listed above. This name has no effect on authentication; for
+that, see the `credential.username` variable in linkgit:git-config[1].
+
+In case (some of) these environment variables are not set, the information
+is taken from the configuration items `user.name` and `user.email`, or, if not
+present, the environment variable EMAIL, or, if that is not set,
+system user name and the hostname used for outgoing mail (taken
+from `/etc/mailname` and falling back to the fully qualified hostname when
+that file does not exist).
+
+The `author.name` and `committer.name` and their corresponding email options
+override `user.name` and `user.email` if set and are overridden themselves by
+the environment variables.
+
+The typical usage is to set just the `user.name` and `user.email` variables;
+the other options are provided for more complex use cases.
+
+:git-commit: 1
+include::date-formats.txt[]
DISCUSSION
----------
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 899e92a..7573160 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -9,18 +9,18 @@ git-config - Get and set repository or global options
SYNOPSIS
--------
[verse]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] name [value [value_regex]]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]]
'git config' [<file-option>] [--type=<type>] --add name value
'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get name [value_regex]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get-all name [value_regex]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex]
'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL
'git config' [<file-option>] --unset name [value_regex]
'git config' [<file-option>] --unset-all name [value_regex]
'git config' [<file-option>] --rename-section old_name new_name
'git config' [<file-option>] --remove-section name
-'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list
+'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list
'git config' [<file-option>] --get-color name [default]
'git config' [<file-option>] --get-colorbool name [stdout-is-tty]
'git config' [<file-option>] -e | --edit
@@ -222,6 +222,11 @@ Valid `<type>`'s include:
the actual origin (config file path, ref, or blob id if
applicable).
+--show-scope::
+ Similar to `--show-origin` in that it augments the output of
+ all queried config options with the scope of that value
+ (local, global, system, command).
+
--get-colorbool name [stdout-is-tty]::
Find the color setting for `name` (e.g. `color.diff`) and output
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index a530fef..40ba4aa 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-grep.txt b/Documentation/git-grep.txt
index c89fb56..ddb6acc 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.
@@ -96,7 +96,8 @@ OPTIONS
Recursively search in each submodule that has been initialized 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::
@@ -347,6 +348,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-rebase.txt b/Documentation/git-rebase.txt
index 0c4f038..8c1f4b8 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -258,16 +258,45 @@ See also INCOMPATIBLE OPTIONS below.
original branch. The index and working tree are also left
unchanged as a result.
---keep-empty::
- Keep the commits that do not change anything from its
- parents in the result.
+--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, and commits which are
+clean cherry-picks (as determined by `git log --cherry-mark ...`) are
+always dropped.
+
See also INCOMPATIBLE OPTIONS below.
+--keep-empty::
+ No-op. Rebasing commits that started empty (had no change
+ relative to their parent) used to fail and this option would
+ override that behavior, allowing commits with empty changes to
+ be rebased. Now commits with no changes do not cause rebasing
+ to halt.
++
+See also BEHAVIORAL DIFFERENCES and 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 +315,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
@@ -356,7 +385,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.
@@ -394,8 +423,9 @@ with `--keep-base` in order to drop those commits from your branch.
--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 +569,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:
@@ -557,6 +588,7 @@ are incompatible with the following options:
* --interactive
* --exec
* --keep-empty
+ * --empty=
* --edit-todo
* --root when used in combination with --onto
@@ -565,33 +597,127 @@ 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
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 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 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.
+The merge backend keeps intentionally empty commits. 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. However, this was by accident of
+implementation rather than by design. Both backends should have the
+same behavior, though it is not clear which one is correct.
+
+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.)
+
+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[]
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 974ade2..c0342e5 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,21 @@ 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.
'disable'::
Disable the `core.sparseCheckout` config setting, and restore the
@@ -106,7 +125,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 +147,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-submodule.txt b/Documentation/git-submodule.txt
index cbe60b1..c9ed2bf 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -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>...]::
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index c7a6271..1489cb0 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.txt b/Documentation/git.txt
index b1597ac..b0672bd 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
@@ -482,13 +496,36 @@ double-quotes and respecting backslash escapes. E.g., the value
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/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index f880d21..c0b9525 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 ea759fd..1814d2d 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,94 @@ 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"
+foo
+
+# same as above, but pass an argument to the helper
+foo --bar=baz
+
+# the arguments are parsed by the shell, so use shell
+# quoting if necessary
+foo --bar="whitespace arg"
+
+# you can also use an absolute path, which will not use the git wrapper
+/path/to/my/helper --with-arguments
+
+# or you can specify your own shell snippet
+!f() { echo "password=`cat $HOME/.secret`"; }; f
+----------------------------------------------------
+
+Generally speaking, rule (3) above is the simplest for users to specify.
+Authors of credential helpers should make an effort to assist their
+users by naming their program "git-credential-$NAME", and putting it in
+the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a
+user to enable it with `git config credential.helper $NAME`.
+
+When a helper is executed, it will have one "operation" argument
+appended to its command line, which is one of:
+
+`get`::
+
+ Return a matching credential, if any exists.
+
+`store`::
+
+ Store the credential, if applicable to the helper.
+
+`erase`::
+
+ Remove a matching credential, if any, from the helper's storage.
+
+The details of the credential will be provided on the helper's stdin
+stream. The exact format is the same as the input/output format of the
+`git credential` plumbing command (see the section `INPUT/OUTPUT
+FORMAT` in linkgit:git-credential[1] for a detailed specification).
+
+For a `get` operation, the helper should produce a list of attributes on
+stdout in the same format (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. If a helper outputs a
+`quit` attribute with a value of `true` or `1`, no further helpers will
+be consulted, nor will the user be prompted (if no credential has been
+provided, the operation will then fail).
+
+For a `store` or `erase` operation, the helper's output is ignored.
+If it fails to perform the requested operation, it may complain to
+stderr to inform the user. If it does not support the requested
+operation (e.g., a read-only store), it should silently ignore the
+request.
+
+If a helper receives any other operation, it should silently ignore the
+request. This leaves room for future operations to be added (older
+helpers will just ignore the new requests).
GIT
---
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 50365f2..3dccab5 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
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 1a7212c..a4b6f49 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -226,6 +226,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/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt
new file mode 100644
index 0000000..0e82815
--- /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/pack-format.txt b/Documentation/technical/pack-format.txt
index cab5bdd..d3a142c 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.