summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Makefile1
-rw-r--r--Documentation/RelNotes/2.31.0.txt161
-rw-r--r--Documentation/SubmittingPatches2
-rw-r--r--Documentation/config/core.txt2
-rw-r--r--Documentation/config/diff.txt2
-rw-r--r--Documentation/config/http.txt4
-rw-r--r--Documentation/config/trace2.txt2
-rw-r--r--Documentation/diff-generate-patch.txt6
-rw-r--r--Documentation/diff-options.txt51
-rw-r--r--Documentation/fetch-options.txt4
-rw-r--r--Documentation/git-blame.txt2
-rw-r--r--Documentation/git-check-mailmap.txt9
-rw-r--r--Documentation/git-clone.txt4
-rw-r--r--Documentation/git-config.txt16
-rw-r--r--Documentation/git-fsck.txt8
-rw-r--r--Documentation/git-log.txt46
-rw-r--r--Documentation/git-ls-files.txt13
-rw-r--r--Documentation/git-maintenance.txt118
-rw-r--r--Documentation/git-mktag.txt39
-rw-r--r--Documentation/git-p4.txt2
-rw-r--r--Documentation/git-rev-parse.txt74
-rw-r--r--Documentation/git-send-email.txt6
-rw-r--r--Documentation/git-shortlog.txt6
-rw-r--r--Documentation/git-show.txt7
-rw-r--r--Documentation/git-status.txt28
-rw-r--r--Documentation/git-update-index.txt5
-rw-r--r--Documentation/git-worktree.txt5
-rw-r--r--Documentation/git.txt24
-rw-r--r--Documentation/githooks.txt2
-rw-r--r--Documentation/gitmailmap.txt123
-rw-r--r--Documentation/gitmodules.txt30
-rw-r--r--Documentation/mailmap.txt75
-rw-r--r--Documentation/pretty-formats.txt34
-rw-r--r--Documentation/rev-list-options.txt5
-rw-r--r--Documentation/technical/index-format.txt42
-rw-r--r--Documentation/technical/pack-format.txt17
-rw-r--r--Documentation/technical/packfile-uri.txt7
-rw-r--r--Documentation/technical/reftable.txt2
38 files changed, 748 insertions, 236 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile
index b980407059..81d1bf7a04 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,6 +21,7 @@ MAN1_TXT += gitweb.txt
MAN5_TXT += gitattributes.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
+MAN5_TXT += gitmailmap.txt
MAN5_TXT += gitmodules.txt
MAN5_TXT += gitrepository-layout.txt
MAN5_TXT += gitweb.conf.txt
diff --git a/Documentation/RelNotes/2.31.0.txt b/Documentation/RelNotes/2.31.0.txt
new file mode 100644
index 0000000000..2a722e1e0f
--- /dev/null
+++ b/Documentation/RelNotes/2.31.0.txt
@@ -0,0 +1,161 @@
+Git 2.31 Release Notes
+======================
+
+Updates since v2.30
+-------------------
+
+Backward incompatible and other important changes
+
+ * The "pack-redundant" command, which has been left stale with almost
+ unusable performance issues, now warns loudly when it gets used, as
+ we no longer want to recommend its use (instead just "repack -d"
+ instead).
+
+ * The development community has adopted Contributor Covenant v2.0 to
+ update from v1.4 that we have been using.
+
+
+UI, Workflows & Features
+
+ * The "--format=%(trailers)" mechanism gets enhanced to make it
+ easier to design output for machine consumption.
+
+ * When a user does not tell "git pull" to use rebase or merge, the
+ command gives a loud message telling a user to choose between
+ rebase or merge but creates a merge anyway, forcing users who would
+ want to rebase to redo the operation. Fix an early part of this
+ problem by tightening the condition to give the message---there is
+ no reason to stop or force the user to choose between rebase or
+ merge if the history fast-forwards.
+
+ * The configuration variable 'core.abbrev' can be set to 'no' to
+ force no abbreviation regardless of the hash algorithm.
+
+ * "git rev-parse" can be explicitly told to give output as absolute
+ or relative path with the `--path-format=(absolute|relative)` option.
+
+ * Bash completion (in contrib/) update to make it easier for
+ end-users to add completion for their custom "git" subcommands.
+
+ * "git maintenance" learned to drive scheduled maintenance on
+ platforms whose native scheduling methods are not 'cron'.
+
+ * After expiring a reflog and making a single commit, the reflog for
+ the branch would record a single entry that knows both @{0} and
+ @{1}, but we failed to answer "what commit were we on?", i.e. @{1}
+
+ * "git bundle" learns "--stdin" option to read its refs from the
+ standard input. Also, it now does not lose refs whey they point
+ at the same object.
+
+Performance, Internal Implementation, Development Support etc.
+
+ * A 3-year old test that was not testing anything useful has been
+ corrected.
+
+ * Retire more names with "sha1" in it.
+
+ * The topological walk codepath is covered by new trace2 stats.
+
+ * Update the Code-of-conduct to version 2.0 from the upstream (we've
+ been using version 1.4).
+
+ * "git mktag" validates its input using its own rules before writing
+ a tag object---it has been updated to share the logic with "git
+ fsck".
+
+ * Two new ways to feed configuration variable-value pairs via
+ environment variables have been introduced, and the way
+ GIT_CONFIG_PARAMETERS encodes variable/value pairs has been tweaked
+ to make it more robust.
+
+ * Tests have been updated so that they do not to get affected by the
+ name of the default branch "git init" creates.
+
+ * "git fetch" learns to treat ref updates atomically in all-or-none
+ fashion, just like "git push" does, with the new "--atomic" option.
+
+ * The peel_ref() API has been replaced with peel_iterated_oid().
+
+ * The .use_shell flag in struct child_process that is passed to
+ run_command() API has been clarified with a bit more documentation.
+
+
+Fixes since v2.30
+-----------------
+
+ * Diagnose command line error of "git rebase" early.
+ (merge ca5120c339 rs/rebase-commit-validation later to maint).
+
+ * Clean up option descriptions in "git cmd --help".
+ (merge e73fe3dd02 zh/arg-help-format later to maint).
+
+ * "git stash" did not work well in a sparsely checked out working
+ tree.
+ (merge ba359fd507 en/stash-apply-sparse-checkout later to maint).
+
+ * Some tests expect that "ls -l" output has either '-' or 'x' for
+ group executable bit, but setgid bit can be inherited from parent
+ directory and make these fields 'S' or 's' instead, causing test
+ failures.
+ (merge ea8bbf2a4e mt/t4129-with-setgid-dir later to maint).
+
+ * "git for-each-repo --config=<var> <cmd>" should not run <cmd> for
+ any repository when the configuration variable <var> is not defined
+ even once.
+ (merge 6c62f01552 ds/for-each-repo-noopfix later to maint).
+
+ * Fix 2.29 regression where "git mergetool --tool-help" fails to list
+ all the available tools.
+ (merge 80f5a16798 pb/mergetool-tool-help-fix later to maint).
+
+ * Fix for procedure to building CI test environment for mac.
+ (merge 3831132ace jc/macos-install-dependencies-fix later to maint).
+
+ * The implementation of "git branch --sort" wrt the detached HEAD
+ display has always been hacky, which has been cleaned up.
+ (merge 4045f659bd ab/branch-sort later to maint).
+
+ * Newline characters in the host and path part of git:// URL are
+ now forbidden.
+ (merge 6aed56736b jk/forbid-lf-in-git-url later to maint).
+
+ * "git diff" showed a submodule working tree with untracked cruft as
+ "Submodule commit <objectname>-dirty", but a natural expectation is
+ that the "-dirty" indicator would align with "git describe --dirty",
+ which does not consider having untracked files in the working tree
+ as source of dirtiness. The inconsistency has been fixed.
+
+ * When more than one commit with the same patch ID appears on one
+ side, "git log --cherry-pick A...B" did not exclude them all when a
+ commit with the same patch ID appears on the other side. Now it
+ does.
+ (merge c9e3a4e76d jk/log-cherry-pick-duplicate-patches later to maint).
+
+ * Documentation for "git fsck" lost stale bits that has become
+ incorrect.
+ (merge 28cc00a13d ab/fsck-doc-fix later to maint).
+
+ * Doc fix for packfile URI feature.
+ (merge bfc2a36ff2 jt/packfile-as-uri-doc later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge 505a276596 pk/subsub-fetch-fix-take-2 later to maint).
+ (merge 33fc56253b fc/t6030-bisect-reset-removes-auxiliary-files later to maint).
+ (merge 7efc378205 ta/doc-typofix later to maint).
+ (merge 1f4e9319c7 pb/doc-modules-git-work-tree-typofix later to maint).
+ (merge 04f6b0a192 ma/t1300-cleanup later to maint).
+ (merge 7b77f5a13e ma/doc-pack-format-varint-for-sizes later to maint).
+ (merge cc2d43be2b nk/perf-fsmonitor-cleanup later to maint).
+ (merge c8302c6c00 ar/t6016-modernise later to maint).
+ (merge 0454986e78 jc/sign-off later to maint).
+ (merge 155067ab4f vv/send-email-with-less-secure-apps-access later to maint).
+ (merge acaabcf391 jk/t5516-deflake later to maint).
+ (merge a1e03535db ad/t4129-setfacl-target-fix later to maint).
+ (merge b356d23638 ug/doc-lose-dircache later to maint).
+ (merge 9371c0e9dd ab/gettext-charset-comment-fix later to maint).
+ (merge 52fc4f195c dl/p4-encode-after-kw-expansion later to maint).
+ (merge 4eb56b56e7 bc/doc-status-short later to maint).
+ (merge a4a1ca22ef tb/local-clone-race-doc later to maint).
+ (merge 6a8c89d053 ma/more-opaque-lock-file later to maint).
+ (merge 4a5ec7d166 js/skip-dashed-built-ins-from-config-mak later to maint).
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d12094bac5..0452db2e67 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -307,7 +307,7 @@ wrote the patch or have the right to pass it on under the same license
as ours, by "signing off" your patch. Without sign-off, we cannot
accept your patches.
-If you can certify the below D-C-O:
+If (and only if) you certify the below D-C-O:
[[dco]]
.Developer's Certificate of Origin 1.1
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index 160aacad84..c04f62a54a 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -625,4 +625,6 @@ core.abbrev::
computed based on the approximate number of packed objects
in your repository, which hopefully is enough for
abbreviated object names to stay unique for some time.
+ If set to "no", no abbreviation is made and the object names
+ are shown in their full length.
The minimum length is 4.
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index c3ae136eba..2d3331f55c 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -85,6 +85,8 @@ diff.ignoreSubmodules::
and 'git status' when `status.submoduleSummary` is set unless it is
overridden by using the --ignore-submodules command-line option.
The 'git submodule' commands are not affected by this setting.
+ By default this is set to untracked so that any untracked
+ submodules are ignored.
diff.mnemonicPrefix::
If set, 'git diff' uses a prefix pair that is different from the
diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index 3968fbb697..7003661c0d 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -42,12 +42,12 @@ http.proxySSLKey::
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`
+ is encrypted. Can be overridden 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
+ verify the proxy with when using an HTTPS proxy. Can be overridden by the
`GIT_PROXY_SSL_CAINFO` environment variable.
http.emptyAuth::
diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt
index 01d3afd8a8..fe1642f0d4 100644
--- a/Documentation/config/trace2.txt
+++ b/Documentation/config/trace2.txt
@@ -54,7 +54,7 @@ trace2.envVars::
`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
+ overridden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by
default.
trace2.destinationDebug::
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index b10ff4caa6..2db8eacc3e 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -81,9 +81,9 @@ Combined diff format
Any diff-generating command can take the `-c` or `--cc` option to
produce a 'combined diff' when showing a merge. This is the default
format when showing merges with linkgit:git-diff[1] or
-linkgit:git-show[1]. Note also that you can give the `-m` option to any
-of these commands to force generation of diffs with individual parents
-of a merge.
+linkgit:git-show[1]. Note also that you can give suitable
+`--diff-merges` option to any of these commands to force generation of
+diffs in specific format.
A "combined diff" format looks like this:
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 746b144c76..e5733ccb2d 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -33,6 +33,57 @@ endif::git-diff[]
show the patch by default, or to cancel the effect of `--patch`.
endif::git-format-patch[]
+ifdef::git-log[]
+--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc)::
+--no-diff-merges::
+ Specify diff format to be used for merge commits. Default is
+ {diff-merges-default} unless `--first-parent` is in use, in which case
+ `first-parent` is the default.
++
+--diff-merges=(off|none):::
+--no-diff-merges:::
+ Disable output of diffs for merge commits. Useful to override
+ implied value.
++
+--diff-merges=first-parent:::
+--diff-merges=1:::
+ This option makes merge commits show the full diff with
+ respect to the first parent only.
++
+--diff-merges=separate:::
+--diff-merges=m:::
+-m:::
+ This makes merge commits show the full diff with respect to
+ each of the parents. Separate log entry and diff is generated
+ for each parent. `-m` doesn't produce any output without `-p`.
++
+--diff-merges=combined:::
+--diff-merges=c:::
+-c:::
+ With this option, diff output for a merge commit shows the
+ differences from each of the parents to the merge result
+ simultaneously instead of showing pairwise diff between a
+ parent and the result one at a time. Furthermore, it lists
+ only files which were modified from all parents. `-c` implies
+ `-p`.
++
+--diff-merges=dense-combined:::
+--diff-merges=cc:::
+--cc:::
+ With this option the output produced by
+ `--diff-merges=combined` is further compressed by omitting
+ uninteresting hunks whose contents in the parents have only
+ two variants and the merge result picks one of them without
+ modification. `--cc` implies `-p`.
+
+--combined-all-paths::
+ This flag causes combined diffs (used for merge commits) to
+ list the name of the file from all parents. It thus only has
+ effect when `--diff-merges=[dense-]combined` is in use, and
+ is likely only useful if filename changes are detected (i.e.
+ when either rename or copy detection have been requested).
+endif::git-log[]
+
-U<n>::
--unified=<n>::
Generate diffs with <n> lines of context instead of
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 2bf77b46fd..07783deee3 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -7,6 +7,10 @@
existing contents of `.git/FETCH_HEAD`. Without this
option old data in `.git/FETCH_HEAD` will be overwritten.
+--atomic::
+ Use an atomic transaction to update local refs. Either all refs are
+ updated, or on error, no refs are updated.
+
--depth=<depth>::
Limit fetching to the specified number of commits from the tip of
each remote branch history. If fetching to a 'shallow' repository
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 34b496d485..3bf5d5d8b4 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -226,7 +226,7 @@ commit commentary), a blame viewer will not care.
MAPPING AUTHORS
---------------
-include::mailmap.txt[]
+See linkgit:gitmailmap[5].
SEE ALSO
diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt
index aa2055dbeb..02f4418323 100644
--- a/Documentation/git-check-mailmap.txt
+++ b/Documentation/git-check-mailmap.txt
@@ -36,10 +36,17 @@ name is provided or known to the 'mailmap', ``Name $$<user@host>$$'' is
printed; otherwise only ``$$<user@host>$$'' is printed.
+CONFIGURATION
+-------------
+
+See `mailmap.file` and `mailmap.blob` in linkgit:git-config[1] for how
+to specify a custom `.mailmap` target file or object.
+
+
MAPPING AUTHORS
---------------
-include::mailmap.txt[]
+See linkgit:gitmailmap[5].
GIT
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 876aedcd47..02d9c19cec 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -57,6 +57,10 @@ repository is specified as a URL, then this flag is ignored (and we
never use the local optimizations). Specifying `--no-local` will
override the default when `/path/to/repo` is given, using the regular
Git transport instead.
++
+*NOTE*: this operation can race with concurrent modification to the
+source repository, similar to running `cp -r src dst` while modifying
+`src`.
--no-hardlinks::
Force the cloning process from a repository on a local
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 0e9351d3cb..4b4cc5c5e8 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -346,6 +346,22 @@ GIT_CONFIG_NOSYSTEM::
See also <<FILES>>.
+GIT_CONFIG_COUNT::
+GIT_CONFIG_KEY_<n>::
+GIT_CONFIG_VALUE_<n>::
+ If GIT_CONFIG_COUNT is set to a positive number, all environment pairs
+ GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be
+ added to the process's runtime configuration. The config pairs are
+ zero-indexed. Any missing key or value is treated as an error. An empty
+ GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no
+ pairs are processed. These environment variables will override values
+ in configuration files, but will be overridden by any explicit options
+ passed via `git -c`.
++
+This is useful for cases where you want to spawn multiple git commands
+with a common configuration but cannot depend on a configuration file,
+for example when writing scripts.
+
[[EXAMPLES]]
EXAMPLES
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index d72d15be5b..bd596619c0 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -129,14 +129,6 @@ using 'git commit-graph verify'. See linkgit:git-commit-graph[1].
Extracted Diagnostics
---------------------
-expect dangling commits - potential heads - due to lack of head information::
- You haven't specified any nodes as heads so it won't be
- possible to differentiate between un-parented commits and
- root nodes.
-
-missing sha1 directory '<dir>'::
- The directory holding the sha1 objects is missing.
-
unreachable <type> <object>::
The <type> object <object>, isn't actually referred to directly
or indirectly in any of the trees or commits seen. This can
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index dd189a353a..1bbf865a1b 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -107,47 +107,15 @@ DIFF FORMATTING
By default, `git log` does not generate any diff output. The options
below can be used to show the changes made by each commit.
-Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits
-will never show a diff, even if a diff format like `--patch` is
-selected, nor will they match search options like `-S`. The exception is
-when `--first-parent` is in use, in which merges are treated like normal
-single-parent commits (this can be overridden by providing a
-combined-diff option or with `--no-diff-merges`).
-
--c::
- With this option, diff output for a merge commit
- shows the differences from each of the parents to the merge result
- simultaneously instead of showing pairwise diff between a parent
- and the result one at a time. Furthermore, it lists only files
- which were modified from all parents.
-
---cc::
- This flag implies the `-c` option and further compresses the
- patch output by omitting uninteresting hunks whose contents in
- the parents have only two variants and the merge result picks
- one of them without modification.
-
---combined-all-paths::
- This flag causes combined diffs (used for merge commits) to
- list the name of the file from all parents. It thus only has
- effect when -c or --cc are specified, and is likely only
- useful if filename changes are detected (i.e. when either
- rename or copy detection have been requested).
-
--m::
- This flag makes the merge commits show the full diff like
- regular commits; for each merge parent, a separate log entry
- and diff is generated. An exception is that only diff against
- the first parent is shown when `--first-parent` option is given;
- in that case, the output represents the changes the merge
- brought _into_ the then-current branch.
-
---diff-merges=off::
---no-diff-merges::
- Disable output of diffs for merge commits (default). Useful to
- override `-m`, `-c`, or `--cc`.
+Note that unless one of `--diff-merges` variants (including short
+`-m`, `-c`, and `--cc` options) is explicitly given, merge commits
+will not show a diff, even if a diff format like `--patch` is
+selected, nor will they match search options like `-S`. The exception
+is when `--first-parent` is in use, in which case `first-parent` is
+the default format.
:git-log: 1
+:diff-merges-default: `off`
include::diff-options.txt[]
include::diff-generate-patch.txt[]
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index cbcf5263dd..6d11ab506b 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -13,6 +13,7 @@ SYNOPSIS
(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
(-[c|d|o|i|s|u|k|m])*
[--eol]
+ [--deduplicate]
[-x <pattern>|--exclude=<pattern>]
[-X <file>|--exclude-from=<file>]
[--exclude-per-directory=<file>]
@@ -23,9 +24,8 @@ SYNOPSIS
DESCRIPTION
-----------
-This merges the file listing in the directory cache index with the
-actual working directory list, and shows different combinations of the
-two.
+This merges the file listing in the index with the actual working
+directory list, and shows different combinations of the two.
One or more of the options below may be used to determine the files
shown:
@@ -81,6 +81,13 @@ OPTIONS
\0 line termination on output and do not quote filenames.
See OUTPUT below for more information.
+--deduplicate::
+ When only filenames are shown, suppress duplicates that may
+ come from having multiple stages during a merge, or giving
+ `--deleted` and `--modified` option at the same time.
+ When any of the `-t`, `--unmerged`, or `--stage` option is
+ in use, this option has no effect.
+
-x <pattern>::
--exclude=<pattern>::
Skip untracked files matching pattern.
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index d1f9b5172d..3b432171d6 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -38,7 +38,7 @@ register::
for running in the background without disrupting foreground
processes.
+
-The `register` subcomand will also set the `maintenance.strategy` config
+The `register` subcommand will also set the `maintenance.strategy` config
value to `incremental`, if this value is not previously set. The
`incremental` strategy uses the following schedule for each maintenance
task:
@@ -218,6 +218,122 @@ Further, the `git gc` command should not be combined with
but does not take the lock in the same way as `git maintenance run`. If
possible, use `git maintenance run --task=gc` instead of `git gc`.
+The following sections describe the mechanisms put in place to run
+background maintenance by `git maintenance start` and how to customize
+them.
+
+BACKGROUND MAINTENANCE ON POSIX SYSTEMS
+---------------------------------------
+
+The standard mechanism for scheduling background tasks on POSIX systems
+is cron(8). This tool executes commands based on a given schedule. The
+current list of user-scheduled tasks can be found by running `crontab -l`.
+The schedule written by `git maintenance start` is similar to this:
+
+-----------------------------------------------------------------------
+# BEGIN GIT MAINTENANCE SCHEDULE
+# The following schedule was created by Git
+# Any edits made in this region might be
+# replaced in the future by a Git command.
+
+0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly
+0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily
+0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly
+
+# END GIT MAINTENANCE SCHEDULE
+-----------------------------------------------------------------------
+
+The comments are used as a region to mark the schedule as written by Git.
+Any modifications within this region will be completely deleted by
+`git maintenance stop` or overwritten by `git maintenance start`.
+
+The `crontab` entry specifies the full path of the `git` executable to
+ensure that the executed `git` command is the same one with which
+`git maintenance start` was issued independent of `PATH`. If the same user
+runs `git maintenance start` with multiple Git executables, then only the
+latest executable is used.
+
+These commands use `git for-each-repo --config=maintenance.repo` to run
+`git maintenance run --schedule=<frequency>` on each repository listed in
+the multi-valued `maintenance.repo` config option. These are typically
+loaded from the user-specific global config. The `git maintenance` process
+then determines which maintenance tasks are configured to run on each
+repository with each `<frequency>` using the `maintenance.<task>.schedule`
+config options. These values are loaded from the global or repository
+config values.
+
+If the config values are insufficient to achieve your desired background
+maintenance schedule, then you can create your own schedule. If you run
+`crontab -e`, then an editor will load with your user-specific `cron`
+schedule. In that editor, you can add your own schedule lines. You could
+start by adapting the default schedule listed earlier, or you could read
+the crontab(5) documentation for advanced scheduling techniques. Please
+do use the full path and `--exec-path` techniques from the default
+schedule to ensure you are executing the correct binaries in your
+schedule.
+
+
+BACKGROUND MAINTENANCE ON MACOS SYSTEMS
+---------------------------------------
+
+While macOS technically supports `cron`, using `crontab -e` requires
+elevated privileges and the executed process does not have a full user
+context. Without a full user context, Git and its credential helpers
+cannot access stored credentials, so some maintenance tasks are not
+functional.
+
+Instead, `git maintenance start` interacts with the `launchctl` tool,
+which is the recommended way to schedule timed jobs in macOS. Scheduling
+maintenance through `git maintenance (start|stop)` requires some
+`launchctl` features available only in macOS 10.11 or later.
+
+Your user-specific scheduled tasks are stored as XML-formatted `.plist`
+files in `~/Library/LaunchAgents/`. You can see the currently-registered
+tasks using the following command:
+
+-----------------------------------------------------------------------
+$ ls ~/Library/LaunchAgents/org.git-scm.git*
+org.git-scm.git.daily.plist
+org.git-scm.git.hourly.plist
+org.git-scm.git.weekly.plist
+-----------------------------------------------------------------------
+
+One task is registered for each `--schedule=<frequency>` option. To
+inspect how the XML format describes each schedule, open one of these
+`.plist` files in an editor and inspect the `<array>` element following
+the `<key>StartCalendarInterval</key>` element.
+
+`git maintenance start` will overwrite these files and register the
+tasks again with `launchctl`, so any customizations should be done by
+creating your own `.plist` files with distinct names. Similarly, the
+`git maintenance stop` command will unregister the tasks with `launchctl`
+and delete the `.plist` files.
+
+To create more advanced customizations to your background tasks, see
+launchctl.plist(5) for more information.
+
+
+BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS
+-----------------------------------------
+
+Windows does not support `cron` and instead has its own system for
+scheduling background tasks. The `git maintenance start` command uses
+the `schtasks` command to submit tasks to this system. You can inspect
+all background tasks using the Task Scheduler application. The tasks
+added by Git have names of the form `Git Maintenance (<frequency>)`.
+The Task Scheduler GUI has ways to inspect these tasks, but you can also
+export the tasks to XML files and view the details there.
+
+Note that since Git is a console application, these background tasks
+create a console window visible to the current user. This can be changed
+manually by selecting the "Run whether user is logged in or not" option
+in Task Scheduler. This change requires a password input, which is why
+`git maintenance start` does not select it by default.
+
+If you want to customize the background tasks, please rename the tasks
+so future calls to `git maintenance (start|stop)` do not overwrite your
+custom tasks.
+
GIT
---
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
index fa6a756123..17a2603a60 100644
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.txt
@@ -3,7 +3,7 @@ git-mktag(1)
NAME
----
-git-mktag - Creates a tag object
+git-mktag - Creates a tag object with extra validation
SYNOPSIS
@@ -11,25 +11,52 @@ SYNOPSIS
[verse]
'git mktag'
+OPTIONS
+-------
+
+--strict::
+ By default mktag turns on the equivalent of
+ linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to
+ disable it.
+
DESCRIPTION
-----------
-Reads a tag contents on standard input and creates a tag object
-that can also be used to sign other objects.
-The output is the new tag's <object> identifier.
+Reads a tag contents on standard input and creates a tag object. The
+output is the new tag's <object> identifier.
+
+This command is mostly equivalent to linkgit:git-hash-object[1]
+invoked with `-t tag -w --stdin`. I.e. both of these will create and
+write a tag found in `my-tag`:
+
+ git mktag <my-tag
+ git hash-object -t tag -w --stdin <my-tag
+
+The difference is that mktag will die before writing the tag if the
+tag doesn't pass a linkgit:git-fsck[1] check.
+
+The "fsck" check done mktag is stricter than what linkgit:git-fsck[1]
+would run by default in that all `fsck.<msg-id>` messages are promoted
+from warnings to errors (so e.g. a missing "tagger" line is an error).
+
+Extra headers in the object are also an error under mktag, but ignored
+by linkgit:git-fsck[1]. This extra check can be turned off by setting
+the appropriate `fsck.<msg-id>` varible:
+
+ git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers
Tag Format
----------
A tag signature file, to be fed to this command's standard input,
has a very simple fixed format: four lines of
- object <sha1>
+ object <hash>
type <typename>
tag <tagname>
tagger <tagger>
followed by some 'optional' free-form message (some tags created
-by older Git may not have `tagger` line). The message, when
+by older Git may not have `tagger` line). The message, when it
exists, is separated by a blank line from the header. The
message part may contain a signature that Git itself doesn't
care about, but that can be verified with gpg.
diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt
index ec233ac0c1..f89e68b424 100644
--- a/Documentation/git-p4.txt
+++ b/Documentation/git-p4.txt
@@ -397,7 +397,7 @@ 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
+and it is not suppressed by the `--no-verify` option. This hook
is called even if `--prepare-p4-only` is set.
p4-changelist
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 5013daa6ef..6b8ca085aa 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -212,6 +212,18 @@ Options for Files
Only the names of the variables are listed, not their value,
even if they are set.
+--path-format=(absolute|relative)::
+ Controls the behavior of certain other options. If specified as absolute, the
+ paths printed by those options will be absolute and canonical. If specified as
+ relative, the paths will be relative to the current working directory if that
+ is possible. The default is option specific.
++
+This option may be specified multiple times and affects only the arguments that
+follow it on the command line, either to the end of the command line or the next
+instance of this option.
+
+The following options are modified by `--path-format`:
+
--git-dir::
Show `$GIT_DIR` if defined. Otherwise show the path to
the .git directory. The path shown, when relative, is
@@ -221,27 +233,9 @@ If `$GIT_DIR` is not defined and the current directory
is not detected to lie in a Git repository or work tree
print a message to stderr and exit with nonzero status.
---absolute-git-dir::
- Like `--git-dir`, but its output is always the canonicalized
- absolute path.
-
--git-common-dir::
Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`.
---is-inside-git-dir::
- When the current working directory is below the repository
- directory print "true", otherwise "false".
-
---is-inside-work-tree::
- When the current working directory is inside the work tree of the
- repository print "true", otherwise "false".
-
---is-bare-repository::
- When the repository is bare print "true", otherwise "false".
-
---is-shallow-repository::
- When the repository is shallow print "true", otherwise "false".
-
--resolve-git-dir <path>::
Check if <path> is a valid repository or a gitfile that
points at a valid repository, and print the location of the
@@ -255,19 +249,9 @@ print a message to stderr and exit with nonzero status.
$GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse
--git-path objects/abc" returns /foo/bar/abc.
---show-cdup::
- When the command is invoked from a subdirectory, show the
- path of the top-level directory relative to the current
- directory (typically a sequence of "../", or an empty string).
-
---show-prefix::
- When the command is invoked from a subdirectory, show the
- path of the current directory relative to the top-level
- directory.
-
--show-toplevel::
- Show the absolute path of the top-level directory of the working
- tree. If there is no working tree, report an error.
+ Show the (by default, absolute) path of the top-level directory
+ of the working tree. If there is no working tree, report an error.
--show-superproject-working-tree::
Show the absolute path of the root of the superproject's
@@ -279,6 +263,36 @@ print a message to stderr and exit with nonzero status.
Show the path to the shared index file in split index mode, or
empty if not in split-index mode.
+The following options are unaffected by `--path-format`:
+
+--absolute-git-dir::
+ Like `--git-dir`, but its output is always the canonicalized
+ absolute path.
+
+--is-inside-git-dir::
+ When the current working directory is below the repository
+ directory print "true", otherwise "false".
+
+--is-inside-work-tree::
+ When the current working directory is inside the work tree of the
+ repository print "true", otherwise "false".
+
+--is-bare-repository::
+ When the repository is bare print "true", otherwise "false".
+
+--is-shallow-repository::
+ When the repository is shallow print "true", otherwise "false".
+
+--show-cdup::
+ When the command is invoked from a subdirectory, show the
+ path of the top-level directory relative to the current
+ directory (typically a sequence of "../", or an empty string).
+
+--show-prefix::
+ When the command is invoked from a subdirectory, show the
+ path of the current directory relative to the top-level
+ directory.
+
--show-object-format[=(storage|input|output)]::
Show the object format (hash algorithm) used for the repository
for storage inside the `.git` directory, input, or output. For
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index b7bbbeadef..93708aefea 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -494,10 +494,14 @@ edit ~/.gitconfig to specify your account settings:
smtpServerPort = 587
----
-If you have multifactor authentication setup on your gmail account, you will
+If you have multi-factor authentication set up on your Gmail account, you will
need to generate an app-specific password for use with 'git send-email'. Visit
https://security.google.com/settings/security/apppasswords to create it.
+If you do not have multi-factor authentication set up on your Gmail account,
+you will need to allow less secure app access. Visit
+https://myaccount.google.com/lesssecureapps to enable it.
+
Once your commits are ready to be sent to the mailing list, run the
following commands:
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index fd93cd41e9..c16cc3b608 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -111,11 +111,7 @@ include::rev-list-options.txt[]
MAPPING AUTHORS
---------------
-The `.mailmap` feature is used to coalesce together commits by the same
-person in the shortlog, where their name and/or email address was
-spelled differently.
-
-include::mailmap.txt[]
+See linkgit:gitmailmap[5].
GIT
---
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index fcf528c1b3..2b1bc7288d 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -45,10 +45,13 @@ include::pretty-options.txt[]
include::pretty-formats.txt[]
-COMMON DIFF OPTIONS
--------------------
+DIFF FORMATTING
+---------------
+The options below can be used to change the way `git show` generates
+diff output.
:git-log: 1
+:diff-merges-default: `dense-combined`
include::diff-options.txt[]
include::diff-generate-patch.txt[]
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 7731b45f07..c0764e850a 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -184,11 +184,26 @@ characters, that field will be quoted in the manner of a C string
literal: surrounded by ASCII double quote (34) characters, and with
interior special characters backslash-escaped.
-For paths with merge conflicts, `X` and `Y` show the modification
-states of each side of the merge. For paths that do not have merge
-conflicts, `X` shows the status of the index, and `Y` shows the status
-of the work tree. For untracked paths, `XY` are `??`. Other status
-codes can be interpreted as follows:
+There are three different types of states that are shown using this format, and
+each one uses the `XY` syntax differently:
+
+* When a merge is occurring and the merge was successful, or outside of a merge
+ situation, `X` shows the status of the index and `Y` shows the status of the
+ working tree.
+* When a merge conflict has occurred and has not yet been resolved, `X` and `Y`
+ show the state introduced by each head of the merge, relative to the common
+ ancestor. These paths are said to be _unmerged_.
+* When a path is untracked, `X` and `Y` are always the same, since they are
+ unknown to the index. `??` is used for untracked paths. Ignored files are
+ not listed unless `--ignored` is used; if it is, ignored files are indicated
+ by `!!`.
+
+Note that the term _merge_ here also includes rebases using the default
+`--merge` strategy, cherry-picks, and anything else using the merge machinery.
+
+In the following table, these three classes are shown in separate sections, and
+these characters are used for `X` and `Y` fields for the first two sections that
+show tracked paths:
* ' ' = unmodified
* 'M' = modified
@@ -198,9 +213,6 @@ codes can be interpreted as follows:
* 'C' = copied
* 'U' = updated but unmerged
-Ignored files are not listed, unless `--ignored` option is in effect,
-in which case `XY` are `!!`.
-
....
X Y Meaning
-------------------------------------------------
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 1489cb09a0..2853f168d9 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -30,9 +30,8 @@ SYNOPSIS
DESCRIPTION
-----------
-Modifies the index or directory cache. Each file mentioned is updated
-into the index and any 'unmerged' or 'needs updating' state is
-cleared.
+Modifies the index. Each file mentioned is updated into the index and
+any 'unmerged' or 'needs updating' state is cleared.
See also linkgit:git-add[1] for a more user-friendly way to do some of
the most common operations on the index.
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index af06128cc9..02a706c4c0 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -143,6 +143,11 @@ locate it. Running `repair` within the recently-moved working tree will
reestablish the connection. If multiple linked working trees are moved,
running `repair` from any working tree with each tree's new `<path>` as
an argument, will reestablish the connection to all the specified paths.
++
+If both the main working tree and linked working trees have been moved
+manually, then running `repair` in the main working tree and specifying the
+new `<path>` of each linked working tree will reestablish all connections
+in both directions.
unlock::
diff --git a/Documentation/git.txt b/Documentation/git.txt
index a6d4ad0818..d36e6fd482 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -13,7 +13,7 @@ SYNOPSIS
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
[-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
- [--super-prefix=<path>]
+ [--super-prefix=<path>] [--config-env <name>=<envvar>]
<command> [<args>]
DESCRIPTION
@@ -80,6 +80,28 @@ config file). Including the equals but with an empty value (like `git -c
foo.bar= ...`) sets `foo.bar` to the empty string which `git config
--type=bool` will convert to `false`.
+--config-env=<name>=<envvar>::
+ Like `-c <name>=<value>`, give configuration variable
+ '<name>' a value, where <envvar> is the name of an
+ environment variable from which to retrieve the value. Unlike
+ `-c` there is no shortcut for directly setting the value to an
+ empty string, instead the environment variable itself must be
+ set to the empty string. It is an error if the `<envvar>` does not exist
+ in the environment. `<envvar>` may not contain an equals sign
+ to avoid ambiguity with `<name>`s which contain one.
++
+This is useful for cases where you want to pass transitory
+configuration options to git, but are doing so on OS's where
+other processes might be able to read your cmdline
+(e.g. `/proc/self/cmdline`), but not your environ
+(e.g. `/proc/self/environ`). That behavior is the default on
+Linux, but may not be on your system.
++
+Note that this might add security for variables such as
+`http.extraHeader` where the sensitive information is part of
+the value, but not e.g. `url.<base>.insteadOf` where the
+sensitive information can be part of the key.
+
--exec-path[=<path>]::
Path to wherever your core Git programs are installed.
This can also be controlled by setting the GIT_EXEC_PATH
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index ffccfc7760..1f3b57d04d 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -644,7 +644,7 @@ 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
+and it is not suppressed by the `--no-verify` option. This hook
is called even if `--prepare-p4-only` is set.
Run `git-p4 submit --help` for details.
diff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.txt
new file mode 100644
index 0000000000..052209b33b
--- /dev/null
+++ b/Documentation/gitmailmap.txt
@@ -0,0 +1,123 @@
+gitmailmap(5)
+=============
+
+NAME
+----
+gitmailmap - Map author/committer names and/or E-Mail addresses
+
+SYNOPSIS
+--------
+$GIT_WORK_TREE/.mailmap
+
+
+DESCRIPTION
+-----------
+
+If the file `.mailmap` exists at the toplevel of the repository, or at
+the location pointed to by the `mailmap.file` or `mailmap.blob`
+configuration options (see linkgit:git-config[1]), it
+is used to map author and committer names and email addresses to
+canonical real names and email addresses.
+
+
+SYNTAX
+------
+
+The '#' character begins a comment to the end of line, blank lines
+are ignored.
+
+In the simple form, each line in the file consists of the canonical
+real name of an author, whitespace, and an email address used in the
+commit (enclosed by '<' and '>') to map to the name. For example:
+--
+ Proper Name <commit@email.xx>
+--
+
+The more complex forms are:
+--
+ <proper@email.xx> <commit@email.xx>
+--
+which allows mailmap to replace only the email part of a commit, and:
+--
+ Proper Name <proper@email.xx> <commit@email.xx>
+--
+which allows mailmap to replace both the name and the email of a
+commit matching the specified commit email address, and:
+--
+ Proper Name <proper@email.xx> Commit Name <commit@email.xx>
+--
+which allows mailmap to replace both the name and the email of a
+commit matching both the specified commit name and email address.
+
+Both E-Mails and names are matched case-insensitively. For example
+this would also match the 'Commit Name <commit@email.xx>' above:
+--
+Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
+--
+
+EXAMPLES
+--------
+
+Your history contains commits by two authors, Jane
+and Joe, whose names appear in the repository under several forms:
+
+------------
+Joe Developer <joe@example.com>
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com>
+Jane Doe <jane@laptop.(none)>
+Jane D. <jane@desktop.(none)>
+------------
+
+Now suppose that Joe wants his middle name initial used, and Jane
+prefers her family name fully spelled out. A `.mailmap` file to
+correct the names would look like:
+
+------------
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com>
+Jane Doe <jane@desktop.(none)>
+------------
+
+Note that there's no need to map the name for 'jane@laptop.(none)' to
+only correct the names. However, leaving the obviously broken
+`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
+usually not what you want. A `.mailmap` file which also corrects those
+is:
+
+------------
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com> <jane@laptop.(none)>
+Jane Doe <jane@example.com> <jane@desktop.(none)>
+------------
+
+Finally, let's say that Joe and Jane shared an E-Mail address, but not
+a name, e.g. by having these two commits in the history generated by a
+bug reporting system. I.e. names appearing in history as:
+
+------------
+Joe <bugs@example.com>
+Jane <bugs@example.com>
+------------
+
+A full `.mailmap` file which also handles those cases (an addition of
+two lines to the above example) would be:
+
+------------
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com> <jane@laptop.(none)>
+Jane Doe <jane@example.com> <jane@desktop.(none)>
+Joe R. Developer <joe@example.com> Joe <bugs@example.com>
+Jane Doe <jane@example.com> Jane <bugs@example.com>
+------------
+
+
+
+SEE ALSO
+--------
+linkgit:git-check-mailmap[1]
+
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 539b4e1997..8e333dde1b 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -7,7 +7,7 @@ gitmodules - Defining submodule properties
SYNOPSIS
--------
-$GIT_WORK_DIR/.gitmodules
+$GIT_WORK_TREE/.gitmodules
DESCRIPTION
@@ -27,19 +27,19 @@ submodule.<name>.path::
Defines the path, relative to the top-level directory of the Git
working tree, where the submodule is expected to be checked out.
The path name must not end with a `/`. All submodule paths must
- be unique within the .gitmodules file.
+ be unique within the `.gitmodules` file.
submodule.<name>.url::
Defines a URL from which the submodule repository can be cloned.
This may be either an absolute URL ready to be passed to
- linkgit:git-clone[1] or (if it begins with ./ or ../) a location
+ linkgit:git-clone[1] or (if it begins with `./` or `../`) a location
relative to the superproject's origin repository.
In addition, there are a number of optional keys:
submodule.<name>.update::
Defines the default update procedure for the named submodule,
- i.e. how the submodule is updated by "git submodule update"
+ i.e. how the submodule is updated by the `git submodule update`
command in the superproject. This is only used by `git
submodule init` to initialize the configuration variable of
the same name. Allowed values here are 'checkout', 'rebase',
@@ -49,7 +49,7 @@ submodule.<name>.update::
submodule.<name>.branch::
A remote branch name for tracking updates in the upstream submodule.
- If the option is not specified, it defaults to the remote 'HEAD'.
+ If the option is not specified, it defaults to the remote `HEAD`.
A special value of `.` is used to indicate that the name of the branch
in the submodule should be the same name as the current branch in the
current repository. See the `--remote` documentation in
@@ -57,14 +57,14 @@ submodule.<name>.branch::
submodule.<name>.fetchRecurseSubmodules::
This option can be used to control recursive fetching of this
- submodule. If this option is also present in the submodules entry in
- .git/config of the superproject, the setting there will override the
- one found in .gitmodules.
+ submodule. If this option is also present in the submodule's entry in
+ `.git/config` of the superproject, the setting there will override the
+ one found in `.gitmodules`.
Both settings can be overridden on the command line by using the
- "--[no-]recurse-submodules" option to "git fetch" and "git pull".
+ `--[no-]recurse-submodules` option to `git fetch` and `git pull`.
submodule.<name>.ignore::
- Defines under what circumstances "git status" and the diff family show
+ Defines under what circumstances `git status` and the diff family show
a submodule as modified. The following values are supported:
+
--
@@ -73,7 +73,7 @@ submodule.<name>.ignore::
been staged).
dirty;; All changes to the submodule's work tree will be ignored, only
- committed differences between the HEAD of the submodule and its
+ committed differences between the `HEAD` of the submodule and its
recorded state in the superproject are taken into account.
untracked;; Only untracked files in submodules will be ignored.
@@ -84,12 +84,12 @@ submodule.<name>.ignore::
differences, and modifications to tracked and untracked files are
shown. This is the default option.
-If this option is also present in the submodules entry in .git/config
+If this option is also present in the submodule's entry in `.git/config`
of the superproject, the setting there will override the one found in
-.gitmodules.
+`.gitmodules`.
Both settings can be overridden on the command line by using the
-"--ignore-submodules" option. The 'git submodule' commands are not
+`--ignore-submodules` option. The `git submodule` commands are not
affected by this setting.
--
@@ -102,7 +102,7 @@ submodule.<name>.shallow::
EXAMPLES
--------
-Consider the following .gitmodules file:
+Consider the following `.gitmodules` file:
----
[submodule "libfoo"]
diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt
deleted file mode 100644
index 4a8c276529..0000000000
--- a/Documentation/mailmap.txt
+++ /dev/null
@@ -1,75 +0,0 @@
-If the file `.mailmap` exists at the toplevel of the repository, or at
-the location pointed to by the mailmap.file or mailmap.blob
-configuration options, it
-is used to map author and committer names and email addresses to
-canonical real names and email addresses.
-
-In the simple form, each line in the file consists of the canonical
-real name of an author, whitespace, and an email address used in the
-commit (enclosed by '<' and '>') to map to the name. For example:
---
- Proper Name <commit@email.xx>
---
-
-The more complex forms are:
---
- <proper@email.xx> <commit@email.xx>
---
-which allows mailmap to replace only the email part of a commit, and:
---
- Proper Name <proper@email.xx> <commit@email.xx>
---
-which allows mailmap to replace both the name and the email of a
-commit matching the specified commit email address, and:
---
- Proper Name <proper@email.xx> Commit Name <commit@email.xx>
---
-which allows mailmap to replace both the name and the email of a
-commit matching both the specified commit name and email address.
-
-Example 1: Your history contains commits by two authors, Jane
-and Joe, whose names appear in the repository under several forms:
-
-------------
-Joe Developer <joe@example.com>
-Joe R. Developer <joe@example.com>
-Jane Doe <jane@example.com>
-Jane Doe <jane@laptop.(none)>
-Jane D. <jane@desktop.(none)>
-------------
-
-Now suppose that Joe wants his middle name initial used, and Jane
-prefers her family name fully spelled out. A proper `.mailmap` file
-would look like:
-
-------------
-Jane Doe <jane@desktop.(none)>
-Joe R. Developer <joe@example.com>
-------------
-
-Note how there is no need for an entry for `<jane@laptop.(none)>`, because the
-real name of that author is already correct.
-
-Example 2: Your repository contains commits from the following
-authors:
-
-------------
-nick1 <bugs@company.xx>
-nick2 <bugs@company.xx>
-nick2 <nick2@company.xx>
-santa <me@company.xx>
-claus <me@company.xx>
-CTO <cto@coompany.xx>
-------------
-
-Then you might want a `.mailmap` file that looks like:
-------------
-<cto@company.xx> <cto@coompany.xx>
-Some Dude <some@dude.xx> nick1 <bugs@company.xx>
-Other Author <other@author.xx> nick2 <bugs@company.xx>
-Other Author <other@author.xx> <nick2@company.xx>
-Santa Claus <santa.claus@northpole.xx> <me@company.xx>
-------------
-
-Use hash '#' for comments that are either on their own line, or after
-the email address.
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 84bbc7439a..6b59e28d44 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -252,7 +252,15 @@ endif::git-rev-list[]
interpreted by
linkgit:git-interpret-trailers[1]. The
`trailers` string may be followed by a colon
- and zero or more comma-separated options:
+ and zero or more comma-separated options.
+ If any option is provided multiple times the
+ last occurance wins.
++
+The boolean options accept an optional value `[=<BOOL>]`. The values
+`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
+sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
+option is given with no value, it's enabled.
++
** 'key=<K>': only show trailers with specified key. Matching is done
case-insensitively and trailing colon is optional. If option is
given multiple times trailer lines matching any of the keys are
@@ -261,27 +269,25 @@ endif::git-rev-list[]
desired it can be disabled with `only=false`. E.g.,
`%(trailers:key=Reviewed-by)` shows trailer lines with key
`Reviewed-by`.
-** 'only[=val]': select whether non-trailer lines from the trailer
- block should be included. The `only` keyword may optionally be
- followed by an equal sign and one of `true`, `on`, `yes` to omit or
- `false`, `off`, `no` to show the non-trailer lines. If option is
- given without value it is enabled. If given multiple times the last
- value is used.
+** 'only[=<BOOL>]': select whether non-trailer lines from the trailer
+ block should be included.
** 'separator=<SEP>': specify a separator inserted between trailer
lines. When this option is not given each trailer line is
terminated with a line feed character. The string SEP may contain
the literal formatting codes described above. To use comma as
separator one must use `%x2C` as it would otherwise be parsed as
- next option. If separator option is given multiple times only the
- last one is used. E.g., `%(trailers:key=Ticket,separator=%x2C )`
+ next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
shows all trailer lines whose key is "Ticket" separated by a comma
and a space.
-** 'unfold[=val]': make it behave as if interpret-trailer's `--unfold`
- option was given. In same way as to for `only` it can be followed
- by an equal sign and explicit value. E.g.,
+** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`
+ option was given. E.g.,
`%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
-** 'valueonly[=val]': skip over the key part of the trailer line and only
- show the value part. Also this optionally allows explicit value.
+** 'keyonly[=<BOOL>]': only show the key part of the trailer.
+** 'valueonly[=<BOOL>]': only show the value part of the trailer.
+** 'key_value_separator=<SEP>': specify a separator inserted between
+ trailer lines. When this option is not given each trailer key-value
+ pair is separated by ": ". Otherwise it shares the same semantics
+ as 'separator=<SEP>' above.
NOTE: Some placeholders may depend on other options given to the
revision traversal engine. For example, the `%g*` reflog options will
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 002379056a..96cc89d157 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -130,6 +130,11 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).
this option allows you to ignore the individual commits
brought in to your history by such a merge.
+ifdef::git-log[]
+ This option also changes default diff format for merge commits
+ to `first-parent`, see `--diff-merges=first-parent` for details.
+endif::git-log[]
+
--not::
Reverses the meaning of the '{caret}' prefix (or lack thereof)
for all following revision specifiers, up to the next `--not`.
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 69edf46c03..b633482b1b 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -26,7 +26,7 @@ Git index format
Extensions are identified by signature. Optional extensions can
be ignored if Git does not understand them.
- Git currently supports cached tree and resolve undo extensions.
+ Git currently supports cache tree and resolve undo extensions.
4-byte extension signature. If the first byte is 'A'..'Z' the
extension is optional and can be ignored.
@@ -136,14 +136,35 @@ Git index format
== Extensions
-=== Cached tree
-
- Cached tree extension contains pre-computed hashes for trees that can
- be derived from the index. It helps speed up tree object generation
- from index for a new commit.
-
- When a path is updated in index, the path must be invalidated and
- removed from tree cache.
+=== Cache tree
+
+ Since the index does not record entries for directories, the cache
+ entries cannot describe tree objects that already exist in the object
+ database for regions of the index that are unchanged from an existing
+ commit. The cache tree extension stores a recursive tree structure that
+ describes the trees that already exist and completely match sections of
+ the cache entries. This speeds up tree object generation from the index
+ for a new commit by only computing the trees that are "new" to that
+ commit. It also assists when comparing the index to another tree, such
+ as `HEAD^{tree}`, since sections of the index can be skipped when a tree
+ comparison demonstrates equality.
+
+ The recursive tree structure uses nodes that store a number of cache
+ entries, a list of subnodes, and an object ID (OID). The OID references
+ the existing tree for that node, if it is known to exist. The subnodes
+ correspond to subdirectories that themselves have cache tree nodes. The
+ number of cache entries corresponds to the number of cache entries in
+ the index that describe paths within that tree's directory.
+
+ The extension tracks the full directory structure in the cache tree
+ extension, but this is generally smaller than the full cache entry list.
+
+ When a path is updated in index, Git invalidates all nodes of the
+ recursive cache tree corresponding to the parent directories of that
+ path. We store these tree nodes as being "invalid" by using "-1" as the
+ number of cache entries. Invalid nodes still store a span of index
+ entries, allowing Git to focus its efforts when reconstructing a full
+ cache tree.
The signature for this extension is { 'T', 'R', 'E', 'E' }.
@@ -174,7 +195,8 @@ Git index format
first entry represents the root level of the repository, followed by the
first subtree--let's call this A--of the root level (with its name
relative to the root level), followed by the first subtree of A (with
- its name relative to A), ...
+ its name relative to A), and so on. The specified number of subtrees
+ indicates when the current level of the recursive stack is complete.
=== Resolve undo
diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt
index f96b2e605f..96d2fc589f 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/technical/pack-format.txt
@@ -55,6 +55,18 @@ Valid object types are:
Type 5 is reserved for future expansion. Type 0 is invalid.
+=== Size encoding
+
+This document uses the following "size encoding" of non-negative
+integers: From each byte, the seven least significant bits are
+used to form the resulting integer. As long as the most significant
+bit is 1, this process continues; the byte with MSB 0 provides the
+last seven bits. The seven-bit chunks are concatenated. Later
+values are more significant.
+
+This size encoding should not be confused with the "offset encoding",
+which is also used in this document.
+
=== Deltified representation
Conceptually there are only four object types: commit, tree, tag and
@@ -73,7 +85,10 @@ Ref-delta can also refer to an object outside the pack (i.e. the
so-called "thin pack"). When stored on disk however, the pack should
be self contained to avoid cyclic dependency.
-The delta data is a sequence of instructions to reconstruct an object
+The delta data starts with the size of the base object and the
+size of the object to be reconstructed. These sizes are
+encoded using the size encoding from above. The remainder of
+the delta data is a sequence of instructions to reconstruct the object
from the base object. If the base object is deltified, it must be
converted to canonical form first. Each instruction appends more and
more data to the target object until it's complete. There are two
diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt
index 318713abc3..f7eabc6c76 100644
--- a/Documentation/technical/packfile-uri.txt
+++ b/Documentation/technical/packfile-uri.txt
@@ -37,8 +37,11 @@ at least so that we can test the client.
This is the implementation: a feature, marked experimental, that allows the
server to be configured by one or more `uploadpack.blobPackfileUri=<sha1>
<uri>` entries. Whenever the list of objects to be sent is assembled, all such
-blobs are excluded, replaced with URIs. The client will download those URIs,
-expecting them to each point to packfiles containing single blobs.
+blobs are excluded, replaced with URIs. As noted in "Future work" below, the
+server can evolve in the future to support excluding other objects (or other
+implementations of servers could be made that support excluding other objects)
+without needing a protocol change, so clients should not expect that packfiles
+downloaded in this way only contain single blobs.
Client design
-------------
diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt
index 2951840e9c..8095ab2590 100644
--- a/Documentation/technical/reftable.txt
+++ b/Documentation/technical/reftable.txt
@@ -446,7 +446,7 @@ especially if readers will not use the object name to ref mapping.
Object blocks use unique, abbreviated 2-32 object name keys, mapping to
ref blocks containing references pointing to that object directly, or as
the peeled value of an annotated tag. Like ref blocks, object blocks use
-the file's standard block size. The abbrevation length is available in
+the file's standard block size. The abbreviation length is available in
the footer as `obj_id_len`.
To save space in small files, object blocks may be omitted if the ref