summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Makefile1
-rw-r--r--Documentation/RelNotes/2.17.0.txt187
-rw-r--r--Documentation/config.txt4
-rw-r--r--Documentation/diff-options.txt10
-rw-r--r--Documentation/git-commit.txt2
-rw-r--r--Documentation/git-pack-objects.txt11
-rw-r--r--Documentation/git-show.txt4
-rw-r--r--Documentation/git-status.txt23
-rw-r--r--Documentation/git-submodule.txt16
-rw-r--r--Documentation/git.txt10
-rw-r--r--Documentation/gitattributes.txt54
-rw-r--r--Documentation/gitignore.txt11
-rw-r--r--Documentation/gitremote-helpers.txt7
-rw-r--r--Documentation/gitsubmodules.txt100
-rw-r--r--Documentation/rev-list-options.txt11
-rw-r--r--Documentation/technical/api-object-access.txt2
-rw-r--r--Documentation/technical/long-running-process-protocol.txt50
-rw-r--r--Documentation/technical/pack-protocol.txt8
-rw-r--r--Documentation/technical/protocol-capabilities.txt8
-rw-r--r--Documentation/technical/repository-version.txt12
20 files changed, 437 insertions, 94 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4ae9ba5c86..6232143cb9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -72,6 +72,7 @@ TECH_DOCS += SubmittingPatches
TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/http-protocol
TECH_DOCS += technical/index-format
+TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/pack-protocol
diff --git a/Documentation/RelNotes/2.17.0.txt b/Documentation/RelNotes/2.17.0.txt
new file mode 100644
index 0000000000..1fe7b61a67
--- /dev/null
+++ b/Documentation/RelNotes/2.17.0.txt
@@ -0,0 +1,187 @@
+Git 2.17 Release Notes
+======================
+
+Updates since v2.16
+-------------------
+
+UI, Workflows & Features
+
+ * "diff" family of commands learned "--find-object=<object-id>" option
+ to limit the findings to changes that involve the named object.
+ (merge 4d8c51aa19 sb/diff-blobfind-pickaxe later to maint).
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * More perf tests for threaded grep
+ (merge 7b31b55db1 ab/perf-grep-threads later to maint).
+
+ * "perf" test output can be sent to codespeed server.
+ (merge 19cf57a92e cc/codespeed later to maint).
+
+ * The build procedure for perl/ part has been greatly simplified by
+ weaning ourselves off of MakeMaker.
+
+ * In preparation for implementing narrow/partial clone, the machinery
+ for checking object connectivity used by gc and fsck has been
+ taught that a missing object is OK when it is referenced by a
+ packfile specially marked as coming from trusted repository that
+ promises to make them available on-demand and lazily.
+
+ * The machinery to clone & fetch, which in turn involves packing and
+ unpacking objects, has been told how to omit certain objects using
+ the filtering mechanism introduced by another topic. It now knows
+ to mark the resulting pack as a promisor pack to tolerate missing
+ objects, laying foundation for "narrow" clones.
+
+ * The first step to getting rid of mru API and using the
+ doubly-linked list API directly instead.
+
+ * Retire mru API as it does not give enough abstraction over
+ underlying list API to be worth it.
+
+ * Rewrite two more "git submodule" subcommands in C.
+
+ * The tracing machinery learned to report tweaking of environment
+ variables as well.
+ (merge 090a09272a nd/trace-with-env later to maint).
+
+ * Update Coccinelle rules to catch and optimize strbuf_addf(&buf, "%s", str)
+ (merge cd9a4b6d93 rs/strbuf-cocci-workaround later to maint).
+
+ * Prevent "clang-format" from breaking line after function return type.
+ (merge a3715d43e8 po/clang-format-functype-weight later to maint).
+
+ * The sequencer infrastructure is shared across "git cherry-pick",
+ "git rebase -i", etc., and has always spawned "git commit" when it
+ needs to create a commit. It has been taught to do so internally,
+ when able, by reusing the codepath "git commit" itself uses, which
+ gives performance boost for a few tens of percents in some sample
+ scenarios.
+
+ * Push the submodule version of collision-detecting SHA-1 hash
+ implementation a bit harder on builders.
+
+ * Avoid mmapping small files while using packed refs (especially ones
+ with zero size, which would cause later munmap() to fail).
+ (merge ba41a8b600 kg/packed-ref-cache-fix later to maint).
+
+ * Conversion from uchar[20] to struct object_id continues.
+
+ * More tests for wildmatch functions.
+
+Also contains various documentation updates and code clean-ups.
+
+
+Fixes since v2.16
+-----------------
+
+ * An old regression in "git describe --all $annotated_tag^0" has been
+ fixed.
+ (merge 1bba00130a dk/describe-all-output-fix later to maint).
+
+ * "git status" after moving a path in the working tree (hence making
+ it appear "removed") and then adding with the -N option (hence
+ making that appear "added") detected it as a rename, but did not
+ report the old and new pathnames correctly.
+ (merge 176ea74793 nd/ita-wt-renames-in-status later to maint).
+
+ * "git svn dcommit" did not take into account the fact that a
+ svn+ssh:// URL with a username@ (typically used for pushing) refers
+ to the same SVN repository without the username@ and failed when
+ svn.pushmergeinfo option is set.
+ (merge 8aaed892fd jm/svn-pushmergeinfo-fix later to maint).
+
+ * API clean-up around revision traversal.
+ (merge 6fcec2f9ae rs/lose-leak-pending later to maint).
+
+ * "git merge -Xours/-Xtheirs" learned to use our/their version when
+ resolving a conflicting updates to a symbolic link.
+ (merge fd48b46474 jc/merge-symlink-ours-theirs later to maint).
+
+ * "git clone $there $here" is allowed even when here directory exists
+ as long as it is an empty directory, but the command incorrectly
+ removed it upon a failure of the operation.
+ (merge d45420c1c8 jk/abort-clone-with-existing-dest later to maint).
+
+ * "git commit --fixup" did not allow "-m<message>" option to be used
+ at the same time; allow it to annotate resulting commit with more
+ text.
+ (merge 30884c9afc ab/commit-m-with-fixup later to maint).
+
+ * When resetting the working tree files recursively, the working tree
+ of submodules are now also reset to match.
+ (merge 7dcc1f4df8 sb/submodule-update-reset-fix later to maint).
+
+ * "git stash -- <pathspec>" incorrectly blew away untracked files in
+ the directory that matched the pathspec, which has been corrected.
+ (merge bba067d2fa tg/stash-with-pathspec-fix later to maint).
+
+ * Instead of maintaining home-grown email address parsing code, ship
+ a copy of reasonably recent Mail::Address to be used as a fallback
+ in 'git send-email' when the platform lacks it.
+ (merge d60be8acab mm/send-email-fallback-to-local-mail-address later to maint).
+
+ * "git add -p" was taught to ignore local changes to submodules as
+ they do not interfere with the partial addition of regular changes
+ anyway.
+ (merge 12434efc1d nd/add-i-ignore-submodules later to maint).
+
+ * Avoid showing a warning message in the middle of a line of "git
+ diff" output.
+ (merge 4e056c989f nd/diff-flush-before-warning later to maint).
+
+ * The http tracing code, often used to debug connection issues,
+ learned to redact potentially sensitive information from its output
+ so that it can be more safely sharable.
+ (merge 8ba18e6fa4 jt/http-redact-cookies later to maint).
+
+ * Crash fix for a corner case where an error codepath tried to unlock
+ what it did not acquire lock on.
+ (merge 81fcb698e0 mr/packed-ref-store-fix later to maint).
+
+ * The split-index mode had a few corner case bugs fixed.
+ (merge ae59a4e44f tg/split-index-fixes later to maint).
+
+ * Assorted fixes to "git daemon".
+ (merge ed15e58efe jk/daemon-fixes later to maint).
+
+ * Completion of "git merge -s<strategy>" (in contrib/) did not work
+ well in non-C locale.
+ (merge 7cc763aaa3 nd/list-merge-strategy later to maint).
+
+ * Workaround for segfault with more recent versions of SVN.
+ (merge 7f6f75e97a ew/svn-branch-segfault-fix later to maint).
+
+ * Plug recently introduced leaks in fsck.
+ (merge ba3a08ca0e jt/fsck-code-cleanup later to maint).
+
+ * "git pull --rebase" did not pass verbosity setting down when
+ recursing into a submodule.
+ (merge a56771a668 sb/pull-rebase-submodule later to maint).
+
+ * The way "git reset --hard" reports the commit the updated HEAD
+ points at is made consistent with the way how the commit title is
+ generated by the other parts of the system. This matters when the
+ title is spread across physically multiple lines.
+ (merge 1cf823fb68 tg/reset-hard-show-head-with-pretty later to maint).
+
+ * Other minor doc, test and build updates and code cleanups.
+ (merge e2a5a028c7 bw/oidmap-autoinit later to maint).
+ (merge f0a6068a9f ys/bisect-object-id-missing-conversion-fix later to maint).
+ (merge 30221a3389 as/read-tree-prefix-doc-fix later to maint).
+ (merge 9bd2ce5432 ab/doc-cat-file-e-still-shows-errors later to maint).
+ (merge ec3b4b06f8 cl/t9001-cleanup later to maint).
+ (merge e1b3f3dd38 ks/submodule-doc-updates later to maint).
+ (merge fbac558a9b rs/describe-unique-abbrev later to maint).
+ (merge 8462ff43e4 tb/crlf-conv-flags later to maint).
+ (merge 7d68bb0766 rb/hashmap-h-compilation-fix later to maint).
+ (merge 3449847168 cc/sha1-file-name later to maint).
+ (merge ad622a256f ds/use-get-be64 later to maint).
+ (merge f919ffebed sg/cocci-move-array later to maint).
+ (merge 4e801463c7 jc/mailinfo-cleanup-fix later to maint).
+ (merge ef5b3a6c5e nd/shared-index-fix later to maint).
+ (merge 9f5258cbb8 tz/doc-show-defaults-to-head later to maint).
+ (merge b780e4407d jc/worktree-add-short-help later to maint).
+ (merge ae239fc8e5 rs/cocci-strbuf-addf-to-addstr later to maint).
+ (merge 2e22a85e5c nd/ignore-glob-doc-update later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 0e25b2c92b..f57e9cf10c 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -3343,6 +3343,10 @@ uploadpack.packObjectsHook::
was run. I.e., `upload-pack` will feed input intended for
`pack-objects` to the hook, and expects a completed packfile on
stdout.
+
+uploadpack.allowFilter::
+ If this option is set, `upload-pack` will advertise partial
+ clone and partial fetch object filtering.
+
Note that this configuration variable is ignored if it is seen in the
repository-level config (this is a safety measure against fetching from
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 743af97b06..c330c01ff0 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -508,6 +508,15 @@ occurrences of that string did not change).
See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more
information.
+--find-object=<object-id>::
+ Look for differences that change the number of occurrences of
+ the specified object. Similar to `-S`, just the argument is different
+ in that it doesn't search for a specific string but for a specific
+ object id.
++
+The object can be a blob or a submodule commit. It implies the `-t` option in
+`git-log` to also find trees.
+
--pickaxe-all::
When `-S` or `-G` finds a change, show all the changes in that
changeset, not just the files that contain the change
@@ -516,6 +525,7 @@ information.
--pickaxe-regex::
Treat the <string> given to `-S` as an extended POSIX regular
expression to match.
+
endif::git-format-patch[]
-O<orderfile>::
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 8c74a2ca03..f970a43422 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -144,6 +144,8 @@ OPTIONS
Use the given <msg> as the commit message.
If multiple `-m` options are given, their values are
concatenated as separate paragraphs.
++
+The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`.
-t <file>::
--template=<file>::
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index aa403d02f3..81bc490ac5 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -255,6 +255,17 @@ a missing object is encountered. This is the default action.
The form '--missing=allow-any' will allow object traversal to continue
if a missing object is encountered. Missing objects will silently be
omitted from the results.
++
+The form '--missing=allow-promisor' is like 'allow-any', but will only
+allow object traversal to continue for EXPECTED promisor missing objects.
+Unexpected missing object will raise an error.
+
+--exclude-promisor-objects::
+ Omit objects that are known to be in the promisor remote. (This
+ option has the purpose of operating only on locally created objects,
+ so that when we repack, we still maintain a distinction between
+ locally created objects [without .promisor] and objects from the
+ promisor remote [with .promisor].) This is used with partial clone.
SEE ALSO
--------
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index 82a4125a2d..e73ef54017 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -9,7 +9,7 @@ git-show - Show various types of objects
SYNOPSIS
--------
[verse]
-'git show' [options] <object>...
+'git show' [options] [<object>...]
DESCRIPTION
-----------
@@ -35,7 +35,7 @@ This manual page describes only the most frequently used options.
OPTIONS
-------
<object>...::
- The names of objects to show.
+ The names of objects to show (defaults to 'HEAD').
For a more complete list of ways to spell object names, see
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 81cab9aefb..72bfb87f66 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -149,14 +149,15 @@ the status.relativePaths config option below.
Short Format
~~~~~~~~~~~~
-In the short-format, the status of each path is shown as
+In the short-format, the status of each path is shown as one of these
+forms
- XY PATH1 -> PATH2
+ XY PATH
+ XY ORIG_PATH -> PATH
-where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is
-shown only when `PATH1` corresponds to a different path in the
-index/worktree (i.e. the file is renamed). The `XY` is a two-letter
-status code.
+where `ORIG_PATH` is where the renamed/copied contents came
+from. `ORIG_PATH` is only shown when the entry is renamed or
+copied. The `XY` is a two-letter status code.
The fields (including the `->`) are separated from each other by a
single space. If a filename contains whitespace or other nonprintable
@@ -192,6 +193,8 @@ in which case `XY` are `!!`.
[MARC] index and work tree matches
[ MARC] M work tree changed since index
[ MARC] D deleted in work tree
+ [ D] R renamed in work tree
+ [ D] C copied in work tree
-------------------------------------------------
D D unmerged, both deleted
A U unmerged, added by us
@@ -309,13 +312,13 @@ Renamed or copied entries have the following format:
of similarity between the source and target of the
move or copy). For example "R100" or "C75".
<path> The pathname. In a renamed/copied entry, this
- is the path in the index and in the working tree.
+ is the target path.
<sep> When the `-z` option is used, the 2 pathnames are separated
with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
byte separates them.
- <origPath> The pathname in the commit at HEAD. This is only
- present in a renamed/copied entry, and tells
- where the renamed/copied contents came from.
+ <origPath> The pathname in the commit at HEAD or in the index.
+ This is only present in a renamed/copied entry, and
+ tells where the renamed/copied contents came from.
--------------------------------------------------------
Unmerged entries have the following format; the first character is
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index ff612001d2..71c5618e82 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -70,8 +70,8 @@ status [--cached] [--recursive] [--] [<path>...]::
Show the status of the submodules. This will print the SHA-1 of the
currently checked out commit for each submodule, along with the
submodule path and the output of 'git describe' for the
- SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
- initialized, `+` if the currently checked out submodule commit
+ SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is
+ not initialized, `+` if the currently checked out submodule commit
does not match the SHA-1 found in the index of the containing
repository and `U` if the submodule has merge conflicts.
+
@@ -132,15 +132,15 @@ expects by cloning missing submodules and updating the working tree of
the submodules. The "updating" can be done in several ways depending
on command line options and the value of `submodule.<name>.update`
configuration variable. The command line option takes precedence over
-the configuration variable. if neither is given, a checkout is performed.
-update procedures supported both from the command line as well as setting
-`submodule.<name>.update`:
+the configuration variable. If neither is given, a 'checkout' is performed.
+The 'update' procedures supported both from the command line as well as
+through the `submodule.<name>.update` configuration are:
checkout;; the commit recorded in the superproject will be
checked out in the submodule on a detached HEAD.
+
If `--force` is specified, the submodule will be checked out (using
-`git checkout --force` if appropriate), even if the commit specified
+`git checkout --force`), even if the commit specified
in the index of the containing repository already matches the commit
checked out in the submodule.
@@ -150,8 +150,8 @@ checked out in the submodule.
merge;; the commit recorded in the superproject will be merged
into the current branch in the submodule.
-The following procedures are only available via the `submodule.<name>.update`
-configuration variable:
+The following 'update' procedures are only available via the
+`submodule.<name>.update` configuration variable:
custom command;; arbitrary shell command that takes a single
argument (the sha1 of the commit recorded in the
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 3f4161a799..8163b5796b 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -646,6 +646,16 @@ of clones and fetches.
variable.
See `GIT_TRACE` for available trace output options.
+`GIT_TRACE_CURL_NO_DATA`::
+ When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump
+ data (that is, only dump info lines and headers).
+
+`GIT_REDACT_COOKIES`::
+ This can be set to a comma-separated list of strings. When a curl trace
+ is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header
+ sent by the client is dumped, values of cookies whose key is in that
+ list (case-sensitive) are redacted.
+
`GIT_LITERAL_PATHSPECS`::
Setting this variable to `1` will cause Git to treat all
pathspecs literally, rather than as glob patterns. For example,
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 30687de81a..c21f5ca109 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -392,46 +392,14 @@ Long Running Filter Process
If the filter command (a string value) is defined via
`filter.<driver>.process` then Git can process all blobs with a
single filter invocation for the entire life of a single Git
-command. This is achieved by using a packet format (pkt-line,
-see technical/protocol-common.txt) based protocol over standard
-input and standard output as follows. All packets, except for the
-"*CONTENT" packets and the "0000" flush packet, are considered
-text and therefore are terminated by a LF.
-
-Git starts the filter when it encounters the first file
-that needs to be cleaned or smudged. After the filter started
-Git sends a welcome message ("git-filter-client"), a list of supported
-protocol version numbers, and a flush packet. Git expects to read a welcome
-response message ("git-filter-server"), exactly one protocol version number
-from the previously sent list, and a flush packet. All further
-communication will be based on the selected version. The remaining
-protocol description below documents "version=2". Please note that
-"version=42" in the example below does not exist and is only there
-to illustrate how the protocol would look like with more than one
-version.
-
-After the version negotiation Git sends a list of all capabilities that
-it supports and a flush packet. Git expects to read a list of desired
-capabilities, which must be a subset of the supported capabilities list,
-and a flush packet as response:
-------------------------
-packet: git> git-filter-client
-packet: git> version=2
-packet: git> version=42
-packet: git> 0000
-packet: git< git-filter-server
-packet: git< version=2
-packet: git< 0000
-packet: git> capability=clean
-packet: git> capability=smudge
-packet: git> capability=not-yet-invented
-packet: git> 0000
-packet: git< capability=clean
-packet: git< capability=smudge
-packet: git< 0000
-------------------------
-Supported filter capabilities in version 2 are "clean", "smudge",
-and "delay".
+command. This is achieved by using the long-running process protocol
+(described in technical/long-running-process-protocol.txt).
+
+When Git encounters the first file that needs to be cleaned or smudged,
+it starts the filter and performs the handshake. In the handshake, the
+welcome message sent by Git is "git-filter-client", only version 2 is
+suppported, and the supported capabilities are "clean", "smudge", and
+"delay".
Afterwards Git sends a list of "key=value" pairs terminated with
a flush packet. The list will contain at least the filter command
@@ -517,12 +485,6 @@ the protocol then Git will stop the filter process and restart it
with the next file that needs to be processed. Depending on the
`filter.<driver>.required` flag Git will interpret that as error.
-After the filter has processed a command it is expected to wait for
-a "key=value" list containing the next command. Git will close
-the command pipe on exit. The filter is expected to detect EOF
-and exit gracefully on its own. Git will wait until the filter
-process has stopped.
-
Delay
^^^^^
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 63260f0056..ff5d7f9ed6 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -102,12 +102,11 @@ PATTERN FORMAT
(relative to the toplevel of the work tree if not from a
`.gitignore` file).
- - Otherwise, Git treats the pattern as a shell glob suitable
- for consumption by fnmatch(3) with the FNM_PATHNAME flag:
- wildcards in the pattern will not match a / in the pathname.
- For example, "Documentation/{asterisk}.html" matches
- "Documentation/git.html" but not "Documentation/ppc/ppc.html"
- or "tools/perf/Documentation/perf.html".
+ - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
+ anything except "`/`", "`?`" matches any one character except "`/`"
+ and "`[]`" matches one character in a selected range. See
+ fnmatch(3) and the FNM_PATHNAME flag for a more detailed
+ description.
- A leading slash matches the beginning of the pathname.
For example, "/{asterisk}.c" matches "cat-file.c" but not
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 4a584f3c5d..4b8c93ec59 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -466,6 +466,13 @@ set by Git if the remote helper has the 'option' capability.
Transmit <string> as a push option. As the push option
must not contain LF or NUL characters, the string is not encoded.
+'option from-promisor' {'true'|'false'}::
+ Indicate that these objects are being fetched from a promisor.
+
+'option no-dependents' {'true'|'false'}::
+ Indicate that only the objects wanted need to be fetched, not
+ their dependents.
+
SEE ALSO
--------
linkgit:git-remote[1]
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index 46cf120f66..4d6c17782f 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the
superproject expects the submodule’s working directory to be at.
The section `submodule.foo.*` in the `.gitmodules` file gives additional
-hints to Gits porcelain layer such as where to obtain the submodule via
-the `submodule.foo.url` setting.
+hints to Git's porcelain layer. For example, the `submodule.foo.url`
+setting specifies where to obtain the submodule.
Submodules can be used for at least two different use cases:
@@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:
2. Splitting a (logically single) project into multiple
repositories and tying them back together. This can be used to
- overcome current limitations of Gits implementation to have
+ overcome current limitations of Git's implementation to have
finer grained access:
- * Size of the git repository:
+ * Size of the Git repository:
In its current form Git scales up poorly for large repositories containing
content that is not compressed by delta computation between trees.
- However you can also use submodules to e.g. hold large binary assets
- and these repositories are then shallowly cloned such that you do not
+ For example, you can use submodules to hold large binary assets
+ and these repositories can be shallowly cloned such that you do not
have a large history locally.
* Transfer size:
In its current form Git requires the whole working tree present. It
does not allow partial trees to be transferred in fetch or clone.
+ If the project you work on consists of multiple repositories tied
+ together as submodules in a superproject, you can avoid fetching the
+ working trees of the repositories you are not interested in.
* Access control:
By restricting user access to submodules, this can be used to implement
read/write policies for different users.
@@ -73,9 +76,10 @@ The configuration of submodules
Submodule operations can be configured using the following mechanisms
(from highest to lowest precedence):
- * The command line for those commands that support taking submodule specs.
- Most commands have a boolean flag '--recurse-submodules' whether to
- recurse into submodules. Examples are `ls-files` or `checkout`.
+ * The command line for those commands that support taking submodules
+ as part of their pathspecs. Most commands have a boolean flag
+ `--recurse-submodules` which specify whether to recurse into submodules.
+ Examples are `grep` and `checkout`.
Some commands take enums, such as `fetch` and `push`, where you can
specify how submodules are affected.
@@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms
For example an effect from the submodule's `.gitignore` file
would be observed when you run `git status --ignore-submodules=none` in
the superproject. This collects information from the submodule's working
-directory by running `status` in the submodule, which does pay attention
-to its `.gitignore` file.
+directory by running `status` in the submodule while paying attention
+to the `.gitignore` file of the submodule.
+
The submodule's `$GIT_DIR/config` file would come into play when running
`git push --recurse-submodules=check` in the superproject, as this would
@@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`
file.
* The configuration file `$GIT_DIR/config` in the superproject.
- Typical configuration at this place is controlling if a submodule
- is recursed into at all via the `active` flag for example.
+ Git only recurses into active submodules (see "ACTIVE SUBMODULES"
+ section below).
+
If the submodule is not yet initialized, then the configuration
-inside the submodule does not exist yet, so configuration where to
+inside the submodule does not exist yet, so where to
obtain the submodule from is configured here for example.
- * the `.gitmodules` file inside the superproject. Additionally to the
- required mapping between submodule's name and path, a project usually
+ * The `.gitmodules` file inside the superproject. A project usually
uses this file to suggest defaults for the upstream collection
- of repositories.
+ of repositories for the mapping that is required between a
+ submodule's name and its path.
+
-This file mainly serves as the mapping between name and path in
-the superproject, such that the submodule's git directory can be
+This file mainly serves as the mapping between the name and path of submodules
+in the superproject, such that the submodule's Git directory can be
located.
+
If the submodule has never been initialized, this is the only place
@@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules/<name>/`
of the superproject.
* Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,
-but no submodule working directory. The submodule’s git directory
-may be there as after deinitializing the git directory is kept around.
+but no submodule working directory. The submodule’s Git directory
+may be there as after deinitializing the Git directory is kept around.
The directory which is supposed to be the working directory is empty instead.
+
A submodule can be deinitialized by running `git submodule deinit`.
@@ -160,6 +164,60 @@ from another repository.
To completely remove a submodule, manually delete
`$GIT_DIR/modules/<name>/`.
+ACTIVE SUBMODULES
+-----------------
+
+A submodule is considered active,
+
+ (a) if `submodule.<name>.active` is set to `true`
+ or
+ (b) if the submodule's path matches the pathspec in `submodule.active`
+ or
+ (c) if `submodule.<name>.url` is set.
+
+and these are evaluated in this order.
+
+For example:
+
+ [submodule "foo"]
+ active = false
+ url = https://example.org/foo
+ [submodule "bar"]
+ active = true
+ url = https://example.org/bar
+ [submodule "baz"]
+ url = https://example.org/baz
+
+In the above config only the submodule 'bar' and 'baz' are active,
+'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because
+(a) takes precedence over (c)
+
+Note that (c) is a historical artefact and will be ignored if the
+(a) and (b) specify that the submodule is not active. In other words,
+if we have an `submodule.<name>.active` set to `false` or if the
+submodule's path is excluded in the pathspec in `submodule.active`, the
+url doesn't matter whether it is present or not. This is illustrated in
+the example that follows.
+
+ [submodule "foo"]
+ active = true
+ url = https://example.org/foo
+ [submodule "bar"]
+ url = https://example.org/bar
+ [submodule "baz"]
+ url = https://example.org/baz
+ [submodule "bob"]
+ ignore = true
+ [submodule]
+ active = b*
+ active = :(exclude) baz
+
+In here all submodules except 'baz' (foo, bar, bob) are active.
+'foo' due to its own active flag and all the others due to the
+submodule active pathspec, which specifies that any submodule
+starting with 'b' except 'baz' are also active, regardless of the
+presence of the .url field.
+
Workflow for a third party library
----------------------------------
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 22f5c9b43d..7b273635de 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -750,10 +750,21 @@ The form '--missing=allow-any' will allow object traversal to continue
if a missing object is encountered. Missing objects will silently be
omitted from the results.
+
+The form '--missing=allow-promisor' is like 'allow-any', but will only
+allow object traversal to continue for EXPECTED promisor missing objects.
+Unexpected missing objects will raise an error.
++
The form '--missing=print' is like 'allow-any', but will also print a
list of the missing objects. Object IDs are prefixed with a ``?'' character.
endif::git-rev-list[]
+--exclude-promisor-objects::
+ (For internal use only.) Prefilter object traversal at
+ promisor boundary. This is used with partial clone. This is
+ stronger than `--missing=allow-promisor` because it limits the
+ traversal, rather than just silencing errors about missing
+ objects.
+
--no-walk[=(sorted|unsorted)]::
Only show the given commits, but do not traverse their ancestors.
This has no effect if a range is specified. If the argument
diff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt
index 03bb0e950d..a1162e5bcd 100644
--- a/Documentation/technical/api-object-access.txt
+++ b/Documentation/technical/api-object-access.txt
@@ -7,7 +7,7 @@ Talk about <sha1_file.c> and <object.h> family, things like
* read_object_with_reference()
* has_sha1_file()
* write_sha1_file()
-* pretend_sha1_file()
+* pretend_object_file()
* lookup_{object,commit,tag,blob,tree}
* parse_{object,commit,tag,blob,tree}
* Use of object flags
diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt
new file mode 100644
index 0000000000..aa0aa9af1c
--- /dev/null
+++ b/Documentation/technical/long-running-process-protocol.txt
@@ -0,0 +1,50 @@
+Long-running process protocol
+=============================
+
+This protocol is used when Git needs to communicate with an external
+process throughout the entire life of a single Git command. All
+communication is in pkt-line format (see technical/protocol-common.txt)
+over standard input and standard output.
+
+Handshake
+---------
+
+Git starts by sending a welcome message (for example,
+"git-filter-client"), a list of supported protocol version numbers, and
+a flush packet. Git expects to read the welcome message with "server"
+instead of "client" (for example, "git-filter-server"), exactly one
+protocol version number from the previously sent list, and a flush
+packet. All further communication will be based on the selected version.
+The remaining protocol description below documents "version=2". Please
+note that "version=42" in the example below does not exist and is only
+there to illustrate how the protocol would look like with more than one
+version.
+
+After the version negotiation Git sends a list of all capabilities that
+it supports and a flush packet. Git expects to read a list of desired
+capabilities, which must be a subset of the supported capabilities list,
+and a flush packet as response:
+------------------------
+packet: git> git-filter-client
+packet: git> version=2
+packet: git> version=42
+packet: git> 0000
+packet: git< git-filter-server
+packet: git< version=2
+packet: git< 0000
+packet: git> capability=clean
+packet: git> capability=smudge
+packet: git> capability=not-yet-invented
+packet: git> 0000
+packet: git< capability=clean
+packet: git< capability=smudge
+packet: git< 0000
+------------------------
+
+Shutdown
+--------
+
+Git will close
+the command pipe on exit. The filter is expected to detect EOF
+and exit gracefully on its own. Git will wait until the filter
+process has stopped.
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index cd31edc91e..7fee6b780a 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -241,6 +241,7 @@ out of what the server said it could do with the first 'want' line.
upload-request = want-list
*shallow-line
*1depth-request
+ [filter-request]
flush-pkt
want-list = first-want
@@ -256,6 +257,8 @@ out of what the server said it could do with the first 'want' line.
additional-want = PKT-LINE("want" SP obj-id)
depth = 1*DIGIT
+
+ filter-request = PKT-LINE("filter" SP filter-spec)
----
Clients MUST send all the obj-ids it wants from the reference
@@ -278,6 +281,11 @@ complete those commits. Commits whose parents are not received as a
result are defined as shallow and marked as such in the server. This
information is sent back to the client in the next step.
+The client can optionally request that pack-objects omit various
+objects from the packfile using one of several filtering techniques.
+These are intended for use with partial clone and partial fetch
+operations. See `rev-list` for possible "filter-spec" values.
+
Once all the 'want's and 'shallow's (and optional 'deepen') are
transferred, clients MUST send a flush-pkt, to tell the server side
that it is done sending the list.
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index 26dcc6f502..332d209b58 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -309,3 +309,11 @@ to accept a signed push certificate, and asks the <nonce> to be
included in the push certificate. A send-pack client MUST NOT
send a push-cert packet unless the receive-pack server advertises
this capability.
+
+filter
+------
+
+If the upload-pack server advertises the 'filter' capability,
+fetch-pack may send "filter" commands to request a partial clone
+or partial fetch and request that the server omit various objects
+from the packfile.
diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt
index 00ad37986e..e03eaccebc 100644
--- a/Documentation/technical/repository-version.txt
+++ b/Documentation/technical/repository-version.txt
@@ -86,3 +86,15 @@ for testing format-1 compatibility.
When the config key `extensions.preciousObjects` is set to `true`,
objects in the repository MUST NOT be deleted (e.g., by `git-prune` or
`git repack -d`).
+
+`partialclone`
+~~~~~~~~~~~~~~
+
+When the config key `extensions.partialclone` is set, it indicates
+that the repo was created with a partial clone (or later performed
+a partial fetch) and that the remote may have omitted sending
+certain unwanted objects. Such a remote is called a "promisor remote"
+and it promises that all such omitted objects can be fetched from it
+in the future.
+
+The value of this key is the name of the promisor remote.