summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines53
-rw-r--r--Documentation/Makefile51
-rw-r--r--Documentation/MyFirstContribution.txt4
-rw-r--r--Documentation/MyFirstObjectWalk.txt2
-rw-r--r--Documentation/RelNotes/2.30.6.txt60
-rw-r--r--Documentation/RelNotes/2.31.5.txt5
-rw-r--r--Documentation/RelNotes/2.32.4.txt5
-rw-r--r--Documentation/RelNotes/2.33.5.txt5
-rw-r--r--Documentation/RelNotes/2.34.5.txt5
-rw-r--r--Documentation/RelNotes/2.35.5.txt5
-rw-r--r--Documentation/RelNotes/2.36.3.txt5
-rw-r--r--Documentation/RelNotes/2.37.2.txt24
-rw-r--r--Documentation/RelNotes/2.37.3.txt46
-rw-r--r--Documentation/RelNotes/2.37.4.txt65
-rw-r--r--Documentation/RelNotes/2.38.0.txt242
-rw-r--r--Documentation/RelNotes/2.38.1.txt5
-rw-r--r--Documentation/RelNotes/2.38.2.txt60
-rw-r--r--Documentation/RelNotes/2.39.0.txt346
-rw-r--r--Documentation/ReviewingGuidelines.txt162
-rw-r--r--Documentation/SubmittingPatches4
-rwxr-xr-xDocumentation/build-docdep.perl5
-rwxr-xr-xDocumentation/cmd-list.perl2
-rw-r--r--Documentation/config.txt4
-rw-r--r--Documentation/config/bundle.txt24
-rw-r--r--Documentation/config/core.txt2
-rw-r--r--Documentation/config/diff.txt15
-rw-r--r--Documentation/config/difftool.txt28
-rw-r--r--Documentation/config/feature.txt3
-rw-r--r--Documentation/config/format.txt4
-rw-r--r--Documentation/config/fsck.txt4
-rw-r--r--Documentation/config/fsmonitor--daemon.txt11
-rw-r--r--Documentation/config/grep.txt7
-rw-r--r--Documentation/config/log.txt15
-rw-r--r--Documentation/config/lsrefs.txt2
-rw-r--r--Documentation/config/mergetool.txt2
-rw-r--r--Documentation/config/notes.txt43
-rw-r--r--Documentation/config/pack.txt9
-rw-r--r--Documentation/config/protocol.txt8
-rw-r--r--Documentation/config/push.txt14
-rw-r--r--Documentation/config/sendemail.txt40
-rw-r--r--Documentation/config/transfer.txt2
-rw-r--r--Documentation/fsck-msgids.txt161
-rw-r--r--Documentation/git-add.txt11
-rw-r--r--Documentation/git-am.txt12
-rw-r--r--Documentation/git-annotate.txt2
-rw-r--r--Documentation/git-apply.txt10
-rw-r--r--Documentation/git-blame.txt6
-rw-r--r--Documentation/git-branch.txt4
-rw-r--r--Documentation/git-bugreport.txt18
-rw-r--r--Documentation/git-bundle.txt15
-rw-r--r--Documentation/git-checkout.txt7
-rw-r--r--Documentation/git-cherry-pick.txt5
-rw-r--r--Documentation/git-clean.txt17
-rw-r--r--Documentation/git-clone.txt16
-rw-r--r--Documentation/git-column.txt7
-rw-r--r--Documentation/git-commit-graph.txt17
-rw-r--r--Documentation/git-commit.txt4
-rw-r--r--Documentation/git-credential-cache--daemon.txt4
-rw-r--r--Documentation/git-credential-cache.txt4
-rw-r--r--Documentation/git-credential.txt2
-rw-r--r--Documentation/git-diagnose.txt65
-rw-r--r--Documentation/git-diff-files.txt2
-rw-r--r--Documentation/git-diff.txt15
-rw-r--r--Documentation/git-difftool.txt27
-rw-r--r--Documentation/git-fast-export.txt2
-rw-r--r--Documentation/git-fast-import.txt7
-rw-r--r--Documentation/git-fetch.txt7
-rw-r--r--Documentation/git-format-patch.txt11
-rw-r--r--Documentation/git-fsck.txt14
-rw-r--r--Documentation/git-fsmonitor--daemon.txt37
-rw-r--r--Documentation/git-gc.txt3
-rw-r--r--Documentation/git-grep.txt29
-rw-r--r--Documentation/git-hash-object.txt3
-rw-r--r--Documentation/git-help.txt27
-rw-r--r--Documentation/git-imap-send.txt2
-rw-r--r--Documentation/git-init.txt7
-rw-r--r--Documentation/git-interpret-trailers.txt15
-rw-r--r--Documentation/git-log.txt60
-rw-r--r--Documentation/git-ls-files.txt4
-rw-r--r--Documentation/git-mailinfo.txt7
-rw-r--r--Documentation/git-maintenance.txt27
-rw-r--r--Documentation/git-merge-base.txt4
-rw-r--r--Documentation/git-merge-tree.txt76
-rw-r--r--Documentation/git-merge.txt10
-rw-r--r--Documentation/git-mergetool.txt3
-rw-r--r--Documentation/git-multi-pack-index.txt11
-rw-r--r--Documentation/git-mv.txt4
-rw-r--r--Documentation/git-notes.txt55
-rw-r--r--Documentation/git-pack-redundant.txt4
-rw-r--r--Documentation/git-patch-id.txt24
-rw-r--r--Documentation/git-prune-packed.txt2
-rw-r--r--Documentation/git-push.txt13
-rw-r--r--Documentation/git-range-diff.txt4
-rw-r--r--Documentation/git-read-tree.txt2
-rw-r--r--Documentation/git-rebase.txt39
-rw-r--r--Documentation/git-receive-pack.txt4
-rw-r--r--Documentation/git-reflog.txt19
-rw-r--r--Documentation/git-repack.txt6
-rw-r--r--Documentation/git-rerere.txt2
-rw-r--r--Documentation/git-rev-list.txt2
-rw-r--r--Documentation/git-rev-parse.txt7
-rw-r--r--Documentation/git-revert.txt14
-rw-r--r--Documentation/git-send-email.txt51
-rw-r--r--Documentation/git-send-pack.txt5
-rw-r--r--Documentation/git-shortlog.txt8
-rw-r--r--Documentation/git-show-branch.txt11
-rw-r--r--Documentation/git-show-ref.txt4
-rw-r--r--Documentation/git-sparse-checkout.txt2
-rw-r--r--Documentation/git-stash.txt24
-rw-r--r--Documentation/git-status.txt2
-rw-r--r--Documentation/git-switch.txt7
-rw-r--r--Documentation/git-symbolic-ref.txt11
-rw-r--r--Documentation/git-tag.txt18
-rw-r--r--Documentation/git-update-index.txt2
-rw-r--r--Documentation/git-update-server-info.txt8
-rw-r--r--Documentation/git-upload-archive.txt4
-rw-r--r--Documentation/git-upload-pack.txt7
-rw-r--r--Documentation/git-var.txt2
-rw-r--r--Documentation/git-verify-commit.txt2
-rw-r--r--Documentation/git-verify-pack.txt2
-rw-r--r--Documentation/git-verify-tag.txt2
-rw-r--r--Documentation/git-worktree.txt3
-rw-r--r--Documentation/git.txt60
-rw-r--r--Documentation/gitcredentials.txt16
-rw-r--r--Documentation/gitformat-bundle.txt (renamed from Documentation/technical/bundle-format.txt)44
-rw-r--r--Documentation/gitformat-chunk.txt (renamed from Documentation/technical/chunk-format.txt)29
-rw-r--r--Documentation/gitformat-commit-graph.txt (renamed from Documentation/technical/commit-graph-format.txt)53
-rw-r--r--Documentation/gitformat-index.txt (renamed from Documentation/technical/index-format.txt)22
-rw-r--r--Documentation/gitformat-pack.txt (renamed from Documentation/technical/pack-format.txt)160
-rw-r--r--Documentation/gitformat-signature.txt (renamed from Documentation/technical/signature-format.txt)21
-rw-r--r--Documentation/gitprotocol-capabilities.txt (renamed from Documentation/technical/protocol-capabilities.txt)32
-rw-r--r--Documentation/gitprotocol-common.txt (renamed from Documentation/technical/protocol-common.txt)23
-rw-r--r--Documentation/gitprotocol-http.txt (renamed from Documentation/technical/http-protocol.txt)35
-rw-r--r--Documentation/gitprotocol-pack.txt (renamed from Documentation/technical/pack-protocol.txt)28
-rw-r--r--Documentation/gitprotocol-v2.txt (renamed from Documentation/technical/protocol-v2.txt)31
-rw-r--r--Documentation/gitremote-helpers.txt9
-rw-r--r--Documentation/glossary-content.txt27
-rw-r--r--Documentation/howto/coordinate-embargoed-releases.txt165
-rw-r--r--Documentation/howto/maintain-git.txt11
-rw-r--r--Documentation/howto/recover-corrupted-object-harder.txt2
-rw-r--r--Documentation/includes/cmd-config-section-all.txt3
-rw-r--r--Documentation/includes/cmd-config-section-rest.txt3
-rwxr-xr-xDocumentation/lint-fsck-msgids.perl70
-rwxr-xr-xDocumentation/lint-man-section-order.perl3
-rw-r--r--Documentation/rerere-options.txt9
-rw-r--r--Documentation/rev-list-options.txt56
-rw-r--r--Documentation/revisions.txt2
-rw-r--r--Documentation/scalar.txt166
-rw-r--r--Documentation/technical/api-error-handling.txt2
-rw-r--r--Documentation/technical/api-parse-options.txt49
-rw-r--r--Documentation/technical/api-simple-ipc.txt2
-rw-r--r--Documentation/technical/api-trace2.txt230
-rw-r--r--Documentation/technical/bitmap-format.txt39
-rw-r--r--Documentation/technical/bundle-uri.txt572
-rw-r--r--Documentation/technical/commit-graph.txt12
-rw-r--r--Documentation/technical/cruft-packs.txt123
-rw-r--r--Documentation/technical/hash-function-transition.txt2
-rw-r--r--Documentation/technical/long-running-process-protocol.txt2
-rw-r--r--Documentation/technical/packfile-uri.txt2
-rw-r--r--Documentation/technical/parallel-checkout.txt2
-rw-r--r--Documentation/technical/partial-clone.txt2
-rw-r--r--Documentation/technical/remembering-renames.txt4
-rw-r--r--Documentation/technical/repository-version.txt4
-rw-r--r--Documentation/technical/scalar.txt61
-rw-r--r--Documentation/technical/sparse-checkout.txt1103
-rw-r--r--Documentation/user-manual.txt2
166 files changed, 4984 insertions, 880 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 4c756be..9d5c278 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -162,8 +162,6 @@ For shell scripts specifically (not exhaustive):
- We do not use \{m,n\};
- - We do not use -E;
-
- We do not use ? or + (which are \{0,1\} and \{1,\}
respectively in BRE) but that goes without saying as these
are ERE elements not BRE (note that \? and \+ are not even part
@@ -204,10 +202,19 @@ For C programs:
by e.g. "echo DEVELOPER=1 >>config.mak".
- We try to support a wide range of C compilers to compile Git with,
- including old ones. You should not use features from newer C
+ including old ones. As of Git v2.35.0 Git requires C99 (we check
+ "__STDC_VERSION__"). You should not use features from a newer C
standard, even if your compiler groks them.
- There are a few exceptions to this guideline:
+ New C99 features have been phased in gradually, if something's new
+ in C99 but not used yet don't assume that it's safe to use, some
+ compilers we target have only partial support for it. These are
+ considered safe to use:
+
+ . since around 2007 with 2b6854c863a, we have been using
+ initializer elements which are not computable at load time. E.g.:
+
+ const char *args[] = {"constant", variable, NULL};
. since early 2012 with e1327023ea, we have been using an enum
definition whose last element is followed by a comma. This, like
@@ -223,18 +230,24 @@ For C programs:
. since early 2021 with 765dc168882, we have been using variadic
macros, mostly for printf-like trace and debug macros.
- These used to be forbidden, but we have not heard any breakage
- report, and they are assumed to be safe.
+ . since late 2021 with 44ba10d6, we have had variables declared in
+ the for loop "for (int i = 0; i < 10; i++)".
+
+ New C99 features that we cannot use yet:
+
+ . %z and %zu as a printf() argument for a size_t (the %z being for
+ the POSIX-specific ssize_t). Instead you should use
+ printf("%"PRIuMAX, (uintmax_t)v). These days the MSVC version we
+ rely on supports %z, but the C library used by MinGW does not.
+
+ . Shorthand like ".a.b = *c" in struct initializations is known to
+ trip up an older IBM XLC version, use ".a = { .b = *c }" instead.
+ See the 33665d98 (reftable: make assignments portable to AIX xlc
+ v12.01, 2022-03-28).
- Variables have to be declared at the beginning of the block, before
the first statement (i.e. -Wdeclaration-after-statement).
- - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)"
- is still not allowed in this codebase. We are in the process of
- allowing it by waiting to see that 44ba10d6 (revision: use C99
- declaration of variable in for() loop, 2021-11-14) does not get
- complaints. Let's revisit this around November 2022.
-
- NULL pointers shall be written as NULL, not as 0.
- When declaring pointers, the star sides with the variable
@@ -606,7 +619,7 @@ Writing Documentation:
avoidance of gendered pronouns.
- When it becomes awkward to stick to this style, prefer "you" when
- addressing the the hypothetical user, and possibly "we" when
+ addressing the hypothetical user, and possibly "we" when
discussing how the program might react to the user. E.g.
You can use this option instead of --xyz, but we might remove
@@ -650,8 +663,8 @@ Writing Documentation:
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<extra>]
- (Zero or one <extra>.)
+ [<file>...]
+ (Zero or more of <file>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
@@ -665,6 +678,16 @@ Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
+ Don't use spacing around "|" tokens when they're used to seperate the
+ alternate arguments of an option:
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
+
Parentheses are used for grouping:
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4f801f4..9c67c3a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,13 +21,25 @@ MAN1_TXT += $(filter-out \
MAN1_TXT += git.txt
MAN1_TXT += gitk.txt
MAN1_TXT += gitweb.txt
+MAN1_TXT += scalar.txt
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
MAN5_TXT += gitattributes.txt
+MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-chunk.txt
+MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-pack.txt
+MAN5_TXT += gitformat-signature.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
MAN5_TXT += gitmailmap.txt
MAN5_TXT += gitmodules.txt
+MAN5_TXT += gitprotocol-capabilities.txt
+MAN5_TXT += gitprotocol-common.txt
+MAN5_TXT += gitprotocol-http.txt
+MAN5_TXT += gitprotocol-pack.txt
+MAN5_TXT += gitprotocol-v2.txt
MAN5_TXT += gitrepository-layout.txt
MAN5_TXT += gitweb.conf.txt
@@ -51,6 +63,7 @@ HOWTO_TXT += $(wildcard howto/*.txt)
DOC_DEP_TXT += $(wildcard *.txt)
DOC_DEP_TXT += $(wildcard config/*.txt)
+DOC_DEP_TXT += $(wildcard includes/*.txt)
ifdef MAN_FILTER
MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ -90,31 +103,24 @@ SP_ARTICLES += howto/coordinate-embargoed-releases
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
SP_ARTICLES += $(API_DOCS)
+TECH_DOCS += ReviewingGuidelines
TECH_DOCS += MyFirstContribution
TECH_DOCS += MyFirstObjectWalk
TECH_DOCS += SubmittingPatches
TECH_DOCS += ToolsForGit
TECH_DOCS += technical/bitmap-format
-TECH_DOCS += technical/bundle-format
-TECH_DOCS += technical/cruft-packs
+TECH_DOCS += technical/bundle-uri
TECH_DOCS += technical/hash-function-transition
-TECH_DOCS += technical/http-protocol
-TECH_DOCS += technical/index-format
TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/multi-pack-index
-TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
-TECH_DOCS += technical/pack-protocol
TECH_DOCS += technical/parallel-checkout
TECH_DOCS += technical/partial-clone
-TECH_DOCS += technical/protocol-capabilities
-TECH_DOCS += technical/protocol-common
-TECH_DOCS += technical/protocol-v2
TECH_DOCS += technical/racy-git
TECH_DOCS += technical/reftable
+TECH_DOCS += technical/scalar
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
@@ -290,6 +296,8 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
cmds-synchingrepositories.txt \
cmds-synchelpers.txt \
cmds-guide.txt \
+ cmds-developerinterfaces.txt \
+ cmds-userinterfaces.txt \
cmds-purehelpers.txt \
cmds-foreignscminterface.txt
@@ -343,8 +351,16 @@ $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
manpage-base-url.xsl: manpage-base-url.xsl.in
$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
- $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+manpage-prereqs := manpage-base-url.xsl $(wildcard manpage*.xsl)
+manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+%.1 : %.xml $(manpage-prereqs)
+ $(manpage-cmd)
+%.5 : %.xml $(manpage-prereqs)
+ $(manpage-cmd)
+%.7 : %.xml $(manpage-prereqs)
+ $(manpage-cmd)
%.xml : %.txt $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
@@ -468,8 +484,19 @@ $(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
.PHONY: lint-docs-man-section-order
lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
+.PHONY: lint-docs-fsck-msgids
+LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok
+$(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl
+$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
+ $(call mkdir_p_parent_template)
+ $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
+ ../fsck.h fsck-msgids.txt $@
+
+lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
+
## Lint: list of targets above
.PHONY: lint-docs
+lint-docs: lint-docs-fsck-msgids
lint-docs: lint-docs-gitlink
lint-docs: lint-docs-man-end-blurb
lint-docs: lint-docs-man-section-order
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 1da15d9..ccfd0cb 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -736,7 +736,7 @@ the {lore}[Git mailing list archive]:
2022-02-21 1:43 ` John Cai
2022-02-21 1:50 ` Taylor Blau
2022-02-23 19:50 ` John Cai
-2022-02-18 20:00 ` // other replies ellided
+2022-02-18 20:00 ` // other replies elided
2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason
2022-02-18 20:26 ` Junio C Hamano
@@ -1160,7 +1160,7 @@ all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format
your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
and your range-diff will be prefaced with "Range-diff against v1".
-Afer you run this command, `format-patch` will output the patches to the `psuh/`
+After you run this command, `format-patch` will output the patches to the `psuh/`
directory, alongside the v1 patches. Using a single directory makes it easy to
refer to the old v1 patches while proofreading the v2 patches, but you will need
to be careful to send out only the v2 patches. We will use a pattern like
diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
index 8d9e855..eee513e 100644
--- a/Documentation/MyFirstObjectWalk.txt
+++ b/Documentation/MyFirstObjectWalk.txt
@@ -534,7 +534,7 @@ the arguments to `traverse_commit_list()`.
- `void *show_data`: A context buffer which is passed in turn to `show_commit`
and `show_object`.
-In addition, `traverse_commit_list_filtered()` has an additional paramter:
+In addition, `traverse_commit_list_filtered()` has an additional parameter:
- `struct oidset *omitted`: A linked-list of object IDs which the provided
filter caused to be omitted.
diff --git a/Documentation/RelNotes/2.30.6.txt b/Documentation/RelNotes/2.30.6.txt
new file mode 100644
index 0000000..d649071
--- /dev/null
+++ b/Documentation/RelNotes/2.30.6.txt
@@ -0,0 +1,60 @@
+Git v2.30.6 Release Notes
+=========================
+
+This release addresses the security issues CVE-2022-39253 and
+CVE-2022-39260.
+
+Fixes since v2.30.5
+-------------------
+
+ * CVE-2022-39253:
+ When relying on the `--local` clone optimization, Git dereferences
+ symbolic links in the source repository before creating hardlinks
+ (or copies) of the dereferenced link in the destination repository.
+ This can lead to surprising behavior where arbitrary files are
+ present in a repository's `$GIT_DIR` when cloning from a malicious
+ repository.
+
+ Git will no longer dereference symbolic links via the `--local`
+ clone mechanism, and will instead refuse to clone repositories that
+ have symbolic links present in the `$GIT_DIR/objects` directory.
+
+ Additionally, the value of `protocol.file.allow` is changed to be
+ "user" by default.
+
+ * CVE-2022-39260:
+ An overly-long command string given to `git shell` can result in
+ overflow in `split_cmdline()`, leading to arbitrary heap writes and
+ remote code execution when `git shell` is exposed and the directory
+ `$HOME/git-shell-commands` exists.
+
+ `git shell` is taught to refuse interactive commands that are
+ longer than 4MiB in size. `split_cmdline()` is hardened to reject
+ inputs larger than 2GiB.
+
+Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis. The
+fix was authored by Taylor Blau, with help from Johannes Schindelin.
+
+Credit for finding CVE-2022-39260 goes to Kevin Backhouse of GitHub.
+The fix was authored by Kevin Backhouse, Jeff King, and Taylor Blau.
+
+
+Jeff King (2):
+ shell: add basic tests
+ shell: limit size of interactive commands
+
+Kevin Backhouse (1):
+ alias.c: reject too-long cmdline strings in split_cmdline()
+
+Taylor Blau (11):
+ builtin/clone.c: disallow `--local` clones with symlinks
+ t/lib-submodule-update.sh: allow local submodules
+ t/t1NNN: allow local submodules
+ t/2NNNN: allow local submodules
+ t/t3NNN: allow local submodules
+ t/t4NNN: allow local submodules
+ t/t5NNN: allow local submodules
+ t/t6NNN: allow local submodules
+ t/t7NNN: allow local submodules
+ t/t9NNN: allow local submodules
+ transport: make `protocol.file.allow` be "user" by default
diff --git a/Documentation/RelNotes/2.31.5.txt b/Documentation/RelNotes/2.31.5.txt
new file mode 100644
index 0000000..0d87e6e
--- /dev/null
+++ b/Documentation/RelNotes/2.31.5.txt
@@ -0,0 +1,5 @@
+Git v2.31.5 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.32.4.txt b/Documentation/RelNotes/2.32.4.txt
new file mode 100644
index 0000000..76c67b2
--- /dev/null
+++ b/Documentation/RelNotes/2.32.4.txt
@@ -0,0 +1,5 @@
+Git v2.32.4 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.33.5.txt b/Documentation/RelNotes/2.33.5.txt
new file mode 100644
index 0000000..a636526
--- /dev/null
+++ b/Documentation/RelNotes/2.33.5.txt
@@ -0,0 +1,5 @@
+Git v2.33.5 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.34.5.txt b/Documentation/RelNotes/2.34.5.txt
new file mode 100644
index 0000000..0e89992
--- /dev/null
+++ b/Documentation/RelNotes/2.34.5.txt
@@ -0,0 +1,5 @@
+Git v2.34.5 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.35.5.txt b/Documentation/RelNotes/2.35.5.txt
new file mode 100644
index 0000000..e19cc48
--- /dev/null
+++ b/Documentation/RelNotes/2.35.5.txt
@@ -0,0 +1,5 @@
+Git v2.35.5 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.36.3.txt b/Documentation/RelNotes/2.36.3.txt
new file mode 100644
index 0000000..56db77b
--- /dev/null
+++ b/Documentation/RelNotes/2.36.3.txt
@@ -0,0 +1,5 @@
+Git v2.36.3 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.37.2.txt b/Documentation/RelNotes/2.37.2.txt
index 300fb09..d82b29e 100644
--- a/Documentation/RelNotes/2.37.2.txt
+++ b/Documentation/RelNotes/2.37.2.txt
@@ -61,4 +61,28 @@ Fixes since v2.37.1
* Workaround for a false positive compiler warning.
+ * The resolve-undo information in the index was not protected against
+ GC, which has been corrected.
+
+ * A corner case bug where lazily fetching objects from a promisor
+ remote resulted in infinite recursion has been corrected.
+
+ * "git p4" working on UTF-16 files on Windows did not implement
+ CRLF-to-LF conversion correctly, which has been corrected.
+
+ * "git p4" did not handle non-ASCII client name well, which has been
+ corrected.
+
+ * "rerere-train" script (in contrib/) used to honor commit.gpgSign
+ while recreating the throw-away merges.
+
+ * "git checkout" miscounted the paths it updated, which has been
+ corrected.
+
+ * Fix for a bug that makes write-tree to fail to write out a
+ non-existent index as a tree, introduced in 2.37.
+
+ * There was a bug in the codepath to upgrade generation information
+ in commit-graph from v1 to v2 format, which has been corrected.
+
Also contains minor documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.37.3.txt b/Documentation/RelNotes/2.37.3.txt
new file mode 100644
index 0000000..d66689e
--- /dev/null
+++ b/Documentation/RelNotes/2.37.3.txt
@@ -0,0 +1,46 @@
+Git 2.37.3 Release Notes
+========================
+
+This primarily is to backport various fixes accumulated on the 'master'
+front since 2.37.2.
+
+Fixes since v2.37.2
+-------------------
+
+ * The build procedure for Windows that uses CMake has been updated to
+ pick up the shell interpreter from local installation location.
+
+ * Conditionally allow building Python interpreter on Windows
+
+ * Fix to lstat() emulation on Windows.
+
+ * Older gcc with -Wall complains about the universal zero initializer
+ "struct s = { 0 };" idiom, which makes developers' lives
+ inconvenient (as -Werror is enabled by DEVELOPER=YesPlease). The
+ build procedure has been tweaked to help these compilers.
+
+ * Plug memory leaks in the failure code path in the "merge-ort" merge
+ strategy backend.
+
+ * Avoid repeatedly running getconf to ask libc version in the test
+ suite, and instead just as it once per script.
+
+ * Platform-specific code that determines if a directory is OK to use
+ as a repository has been taught to report more details, especially
+ on Windows.
+
+ * "vimdiff3" regression has been corrected.
+
+ * "git fsck" reads mode from tree objects but canonicalizes the mode
+ before passing it to the logic to check object sanity, which has
+ hid broken tree objects from the checking logic. This has been
+ corrected, but to help exiting projects with broken tree objects
+ that they cannot fix retroactively, the severity of anomalies this
+ code detects has been demoted to "info" for now.
+
+ * Fixes to sparse index compatibility work for "reset" and "checkout"
+ commands.
+
+ * Documentation for "git add --renormalize" has been improved.
+
+Also contains other minor documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.37.4.txt b/Documentation/RelNotes/2.37.4.txt
new file mode 100644
index 0000000..e42a5c1
--- /dev/null
+++ b/Documentation/RelNotes/2.37.4.txt
@@ -0,0 +1,65 @@
+Git 2.37.4 Release Notes
+========================
+
+This primarily is to backport various fixes accumulated on the 'master'
+front since 2.37.3, and also includes the same security fixes as in
+v2.30.6.
+
+Fixes since v2.37.3
+-------------------
+
+ * CVE-2022-39253:
+ When relying on the `--local` clone optimization, Git dereferences
+ symbolic links in the source repository before creating hardlinks
+ (or copies) of the dereferenced link in the destination repository.
+ This can lead to surprising behavior where arbitrary files are
+ present in a repository's `$GIT_DIR` when cloning from a malicious
+ repository.
+
+ Git will no longer dereference symbolic links via the `--local`
+ clone mechanism, and will instead refuse to clone repositories that
+ have symbolic links present in the `$GIT_DIR/objects` directory.
+
+ Additionally, the value of `protocol.file.allow` is changed to be
+ "user" by default.
+
+ Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis.
+ The fix was authored by Taylor Blau, with help from Johannes
+ Schindelin.
+
+ * CVE-2022-39260:
+ An overly-long command string given to `git shell` can result in
+ overflow in `split_cmdline()`, leading to arbitrary heap writes and
+ remote code execution when `git shell` is exposed and the directory
+ `$HOME/git-shell-commands` exists.
+
+ `git shell` is taught to refuse interactive commands that are
+ longer than 4MiB in size. `split_cmdline()` is hardened to reject
+ inputs larger than 2GiB.
+
+ Credit for finding CVE-2022-39260 goes to Kevin Backhouse of
+ GitHub. The fix was authored by Kevin Backhouse, Jeff King, and
+ Taylor Blau.
+
+ * An earlier optimization discarded a tree-object buffer that is
+ still in use, which has been corrected.
+
+ * Fix deadlocks between main Git process and subprocess spawned via
+ the pipe_command() API, that can kill "git add -p" that was
+ reimplemented in C recently.
+
+ * xcalloc(), imitating calloc(), takes "number of elements of the
+ array", and "size of a single element", in this order. A call that
+ does not follow this ordering has been corrected.
+
+ * The preload-index codepath made copies of pathspec to give to
+ multiple threads, which were left leaked.
+
+ * Update the version of Ubuntu used for GitHub Actions CI from 18.04
+ to 22.04.
+
+ * The auto-stashed local changes created by "git merge --autostash"
+ was mixed into a conflicted state left in the working tree, which
+ has been corrected.
+
+Also contains other minor documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.38.0.txt b/Documentation/RelNotes/2.38.0.txt
index 335b0e8..870581f 100644
--- a/Documentation/RelNotes/2.38.0.txt
+++ b/Documentation/RelNotes/2.38.0.txt
@@ -6,7 +6,7 @@ UI, Workflows & Features
* "git remote show [-n] frotz" now pays attention to negative
pathspec.
- * "git push" sometimes perform poorly when reachability bitmaps are
+ * "git push" sometimes performs poorly when reachability bitmaps are
used, even in a repository where other operations are helped by
bitmaps. The push.useBitmaps configuration variable is introduced
to allow disabling use of reachability bitmaps only for "git push".
@@ -27,7 +27,7 @@ UI, Workflows & Features
what locale they are in by sending Accept-Language HTTP header, but
this was done only for some requests but not others.
- * Introduce a discovery.barerepository configuration variable that
+ * Introduce a safe.barerepository configuration variable that
allows users to forbid discovery of bare repositories.
* Various messages that come from the pack-bitmap codepaths have been
@@ -45,6 +45,49 @@ UI, Workflows & Features
restore the working tree to the state before the command was
initiated, but in some corner cases it didn't.
+ * Operating modes like "--batch" of "git cat-file" command learned to
+ take NUL-terminated input, instead of one-item-per-line.
+
+ * "git rm" has become more aware of the sparse-index feature.
+
+ * "git rev-list --disk-usage" learned to take an optional value
+ "human" to show the reported value in human-readable format, like
+ "3.40MiB".
+
+ * The "diagnose" feature to create a zip archive for diagnostic
+ material has been lifted from "scalar" and made into a feature of
+ "git bugreport".
+
+ * The namespaces used by "log --decorate" from "refs/" hierarchy by
+ default has been tightened.
+
+ * "git rev-list --ancestry-path=C A..B" is a natural extension of
+ "git rev-list A..B"; instead of choosing a subset of A..B to those
+ that have ancestry relationship with A, it lets a subset with
+ ancestry relationship with C.
+
+ * "scalar" now enables built-in fsmonitor on enlisted repositories,
+ when able.
+
+ * The bash prompt (in contrib/) learned to optionally indicate when
+ the index is unmerged.
+
+ * "git clone" command learned the "--bundle-uri" option to coordinate
+ with hosting sites the use of pre-prepared bundle files.
+
+ * "git range-diff" learned to honor pathspec argument if given.
+
+ * "git format-patch --from=<ident>" can be told to add an in-body
+ "From:" line even for commits that are authored by the given
+ <ident> with "--force-in-body-from" option.
+
+ * The built-in fsmonitor refuses to work on a network mounted
+ repositories; a configuration knob for users to override this has
+ been introduced.
+
+ * The "scalar" addition from Microsoft is now part of the core Git
+ installation.
+
Performance, Internal Implementation, Development Support etc.
@@ -87,7 +130,7 @@ Performance, Internal Implementation, Development Support etc.
* The way "git multi-pack" uses parse-options API has been improved.
- * A coccinelle rule (in contrib/) to encourage use of COPY_ARRAY
+ * A Coccinelle rule (in contrib/) to encourage use of COPY_ARRAY
macro has been improved.
* API tweak to make it easier to run fuzz testing on commit-graph parser.
@@ -101,6 +144,43 @@ Performance, Internal Implementation, Development Support etc.
* Add a level of redirection to array allocation API in xdiff part,
to make it easier to share with the libgit2 project.
+ * "git fetch" client logs the partial clone filter used in the trace2
+ output.
+
+ * The "bundle URI" design gets documented.
+
+ * The common ancestor negotiation exchange during a "git fetch"
+ session now leaves trace log.
+
+ * Test portability improvements.
+ (merge 4d1d843be7 mt/rot13-in-c later to maint).
+
+ * The "subcommand" mode is introduced to parse-options API and update
+ the command line parser of Git commands with subcommands.
+
+ * The pack bitmap file gained a bitmap-lookup table to speed up
+ locating the necessary bitmap for a given commit.
+
+ * The assembly version of SHA-1 implementation for PPC has been
+ removed.
+
+ * The server side that responds to "git fetch" and "git clone"
+ request has been optimized by allowing it to send objects in its
+ object store without recomputing and validating the object names.
+
+ * Annotate function parameters that are not used (but cannot be
+ removed for structural reasons), to prepare us to later compile
+ with -Wunused warning turned on.
+
+ * Share the text used to explain configuration variables used by "git
+ <subcmd>" in "git help <subcmd>" with the text from "git help config".
+
+ * "git mv A B" in a sparsely populated working tree can be asked to
+ move a path from a directory that is "in cone" to another directory
+ that is "out of cone". Handling of such a case has been improved.
+
+ * The chainlint script for our tests has been revamped.
+
Fixes since v2.37
-----------------
@@ -134,27 +214,21 @@ Fixes since v2.37
* Recent update to vimdiff layout code has been made more robust
against different end-user vim settings.
- * Plug various memory leaks.
- (merge ece3974ba6 ab/leakfix later to maint).
-
- * Plug various memory leaks in test-tool commands.
- (merge f40a693450 ab/test-tool-leakfix later to maint).
+ * Plug various memory leaks, both in the main code and in test-tool
+ commands.
* Fixes a long-standing corner case bug around directory renames in
the merge-ort strategy.
* The resolve-undo information in the index was not protected against
GC, which has been corrected.
- (merge e0ad13977a jc/resolve-undo later to maint).
* A corner case bug where lazily fetching objects from a promisor
remote resulted in infinite recursion has been corrected.
- (merge cb88b37cb9 hx/lookup-commit-in-graph-fix later to maint).
* "git clone" from a repository with some ref whose HEAD is unborn
did not set the HEAD in the resulting repository correctly, which
has been corrected.
- (merge daf7898abb jk/clone-unborn-confusion later to maint).
* An earlier attempt to plug leaks placed a clean-up label to jump to
at a bogus place, which as been corrected.
@@ -167,50 +241,164 @@ Fixes since v2.37
* A fix for a regression in test framework.
* mkstemp() emulation on Windows has been improved.
- (merge ae25974de3 rs/mingw-tighten-mkstemp later to maint).
* Add missing documentation for "include" and "includeIf" features in
"git config" file format, which incidentally teaches the command
line completion to include them in its offerings.
- (merge 07aed58017 mb/config-document-include later to maint).
* Avoid "white/black-list" in documentation and code comments.
- (merge f5adaa5cc3 ds/doc-wo-whitelist later to maint).
* Workaround for a compiler warning against use of die() in
osx-keychain (in contrib/).
- (merge f2fc531585 ld/osx-keychain-usage-fix later to maint).
* Workaround for a false positive compiler warning.
- (merge b4f52f09ae ds/win-syslog-compiler-fix later to maint).
* "git p4" working on UTF-16 files on Windows did not implement
CRLF-to-LF conversion correctly, which has been corrected.
- (merge 4d35f74421 mb/p4-utf16-crlf later to maint).
* "git p4" did not handle non-ASCII client name well, which has been
corrected.
- (merge d205483695 kk/p4-client-name-encoding-fix later to maint).
* "rerere-train" script (in contrib/) used to honor commit.gpgSign
while recreating the throw-away merges.
- (merge cc391fc886 cl/rerere-train-with-no-sign later to maint).
* "git checkout" miscounted the paths it updated, which has been
corrected.
- (merge 611c7785e8 mt/checkout-count-fix later to maint).
* Fix for a bug that makes write-tree to fail to write out a
non-existent index as a tree, introduced in 2.37.
- (merge 4447d4129d tk/untracked-cache-with-uall later to maint).
* There was a bug in the codepath to upgrade generation information
in commit-graph from v1 to v2 format, which has been corrected.
- (merge 9550f6c16a tb/commit-graph-genv2-upgrade-fix later to maint).
+
+ * Gitweb had legacy URL shortener that is specific to the way
+ projects hosted on kernel.org used to (but no longer) work, which
+ has been removed.
+
+ * Fix build procedure for Windows that uses CMake so that it can pick
+ up the shell interpreter from local installation location.
+
+ * Conditionally allow building Python interpreter on Windows
+
+ * Fix to lstat() emulation on Windows.
+
+ * Older gcc with -Wall complains about the universal zero initializer
+ "struct s = { 0 };" idiom, which makes developers' lives
+ inconvenient (as -Werror is enabled by DEVELOPER=YesPlease). The
+ build procedure has been tweaked to help these compilers.
+
+ * Plug memory leaks in the failure code path in the "merge-ort" merge
+ strategy backend.
+
+ * "git symbolic-ref symref non..sen..se" is now diagnosed as an error.
+
+ * A follow-up fix to a fix for a regression in 2.36 around hooks.
+
+ * Avoid repeatedly running getconf to ask libc version in the test
+ suite, and instead just as it once per script.
+
+ * Platform-specific code that determines if a directory is OK to use
+ as a repository has been taught to report more details, especially
+ on Windows.
+
+ * "vimdiff3" regression fix.
+
+ * "git fsck" reads mode from tree objects but canonicalizes the mode
+ before passing it to the logic to check object sanity, which has
+ hid broken tree objects from the checking logic. This has been
+ corrected, but to help existing projects with broken tree objects
+ that they cannot fix retroactively, the severity of anomalies this
+ code detects has been demoted to "info" for now.
+
+ * Fixes to sparse index compatibility work for "reset" and "checkout"
+ commands.
+
+ * An earlier optimization discarded a tree-object buffer that is
+ still in use, which has been corrected.
+
+ * Fix deadlocks between main Git process and subprocess spawned via
+ the pipe_command() API, that can kill "git add -p" that was
+ reimplemented in C recently.
+
+ * The sequencer machinery translated messages left in the reflog by
+ mistake, which has been corrected.
+
+ * xcalloc(), imitating calloc(), takes "number of elements of the
+ array", and "size of a single element", in this order. A call that
+ does not follow this ordering has been corrected.
+
+ * The preload-index codepath made copies of pathspec to give to
+ multiple threads, which were left leaked.
+
+ * Update the version of Ubuntu used for GitHub Actions CI from 18.04
+ to 22.04.
+
+ * The auto-stashed local changes created by "git merge --autostash"
+ was mixed into a conflicted state left in the working tree, which
+ has been corrected.
+
+ * Multi-pack index got corrupted when preferred pack changed from one
+ pack to another in a certain way, which has been corrected.
+ (merge 99e4d084ff tb/midx-with-changing-preferred-pack-fix later to maint).
+
+ * The clean-up of temporary files created via mks_tempfile_dt() was
+ racy and attempted to unlink() the leading directory when signals
+ are involved, which has been corrected.
+ (merge babe2e0559 rs/tempfile-cleanup-race-fix later to maint).
+
+ * FreeBSD portability fix for "git maintenance" that spawns "crontab"
+ to schedule tasks.
+ (merge ee69e7884e bc/gc-crontab-fix later to maint).
+
+ * Those who use diff-so-fancy as the diff-filter noticed a regression
+ or two in the code that parses the diff output in the built-in
+ version of "add -p", which has been corrected.
+ (merge 0a101676e5 js/add-p-diff-parsing-fix later to maint).
+
+ * Segfault fix-up to an earlier fix to the topic to teach "git reset"
+ and "git checkout" work better in a sparse checkout.
+ (merge 037f8ea6d9 vd/sparse-reset-checkout-fixes later to maint).
+
+ * "git diff --no-index A B" managed its the pathnames of its two
+ input files rather haphazardly, sometimes leaking them. The
+ command line argument processing has been straightened out to clean
+ it up.
+ (merge 2b43dd0eb5 rs/diff-no-index-cleanup later to maint).
+
+ * "git rev-list --verify-objects" ought to inspect the contents of
+ objects and notice corrupted ones, but it didn't when the commit
+ graph is in use, which has been corrected.
+ (merge b27ccae34b jk/rev-list-verify-objects-fix later to maint).
+
+ * More fixes to "add -p"
+ (merge 64ec8efb83 js/builtin-add-p-portability-fix later to maint).
+
+ * The parser in the script interface to parse-options in "git
+ rev-parse" has been updated to diagnose a bogus input correctly.
+ (merge f20b9c36d0 ow/rev-parse-parseopt-fix later to maint).
+
+ * The code that manages list-object-filter structure, used in partial
+ clones, leaked the instances, which has been plugged.
+ (merge 66eede4a37 jk/plug-list-object-filter-leaks later to maint).
+
+ * Fix another UI regression in the reimplemented "add -p".
+ (merge f6f0ee247f rs/add-p-worktree-mode-prompt-fix later to maint).
+
+ * "git fetch" over protocol v2 sent an incorrect ref prefix request
+ to the server and made "git pull" with configured fetch refspec
+ that does not cover the remote branch to merge with fail, which has
+ been corrected.
+ (merge 49ca2fba39 jk/proto-v2-ref-prefix-fix later to maint).
+
+ * A result from opendir() was leaking in the commit-graph expiration
+ codepath, which has been plugged.
+ (merge 12f1ae5324 ml/commit-graph-expire-dir-leak-fix later to maint).
+
+ * Just like we have coding guidelines, we now have guidelines for
+ reviewers.
+ (merge e01b851923 vd/doc-reviewing-guidelines later to maint).
* Other code cleanup, docfix, build fix, etc.
- (merge a700395eaf ma/t4200-update later to maint).
- (merge ae436f283c ma/sparse-checkout-cone-doc-fix later to maint).
- (merge a10f6e2bda sg/index-format-doc-update later to maint).
- (merge ce5f07983d mt/pkt-line-comment-tweak later to maint).
- (merge 1e11fab59c jc/string-list-cleanup later to maint).
+ (merge 77b9e85c0f vd/fix-perf-tests later to maint).
+ (merge 0682bc43f5 jk/test-crontab-fixes later to maint).
+ (merge b46dd1726c cc/doc-trailer-whitespace-rules later to maint).
diff --git a/Documentation/RelNotes/2.38.1.txt b/Documentation/RelNotes/2.38.1.txt
new file mode 100644
index 0000000..b2b5854
--- /dev/null
+++ b/Documentation/RelNotes/2.38.1.txt
@@ -0,0 +1,5 @@
+Git v2.38.1 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.
diff --git a/Documentation/RelNotes/2.38.2.txt b/Documentation/RelNotes/2.38.2.txt
new file mode 100644
index 0000000..086b900
--- /dev/null
+++ b/Documentation/RelNotes/2.38.2.txt
@@ -0,0 +1,60 @@
+Git 2.38.2 Release Notes
+========================
+
+This is to backport various fixes accumulated during the development
+towards Git 2.39, the next feature release.
+
+
+Fixes since v2.38.1
+-------------------
+
+ * Update CodingGuidelines to clarify what features to use and avoid
+ in C99.
+
+ * The codepath that reads from the index v4 had unaligned memory
+ accesses, which has been corrected.
+
+ * "git remote rename" failed to rename a remote without fetch
+ refspec, which has been corrected.
+
+ * "git clone" did not like to see the "--bare" and the "--origin"
+ options used together without a good reason.
+
+ * Fix messages incorrectly marked for translation.
+
+ * "git fsck" failed to release contents of tree objects already used
+ from the memory, which has been fixed.
+
+ * "git rebase -i" can mistakenly attempt to apply a fixup to a commit
+ itself, which has been corrected.
+
+ * In read-only repositories, "git merge-tree" tried to come up with a
+ merge result tree object, which it failed (which is not wrong) and
+ led to a segfault (which is bad), which has been corrected.
+
+ * Force C locale while running tests around httpd to make sure we can
+ find expected error messages in the log.
+
+ * Fix a logic in "mailinfo -b" that miscomputed the length of a
+ substring, which lead to an out-of-bounds access.
+
+ * The codepath to sign learned to report errors when it fails to read
+ from "ssh-keygen".
+
+ * "GIT_EDITOR=: git branch --edit-description" resulted in failure,
+ which has been corrected.
+
+ * Documentation on various Boolean GIT_* environment variables have
+ been clarified.
+
+ * "git multi-pack-index repack/expire" used to repack unreachable
+ cruft into a new pack, which have been corrected.
+
+ * The code to clean temporary object directories (used for
+ quarantine) tried to remove them inside its signal handler, which
+ was a no-no.
+
+ * "git branch --edit-description" on an unborh branch misleadingly
+ said that no such branch exists, which has been corrected.
+
+Also contains various documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.39.0.txt b/Documentation/RelNotes/2.39.0.txt
new file mode 100644
index 0000000..bb649e4
--- /dev/null
+++ b/Documentation/RelNotes/2.39.0.txt
@@ -0,0 +1,346 @@
+Git v2.39 Release Notes
+=======================
+
+UI, Workflows & Features
+------------------------
+
+ * "git grep" learned to expand the sparse-index more lazily and on
+ demand in a sparse checkout.
+
+ * By default, use of fsmonitor on a repository on networked
+ filesystem is disabled. Add knobs to make it workable on macOS.
+
+ * After checking out a "branch" that is a symbolic-ref that points at
+ another branch, "git symbolic-ref HEAD" reports the underlying
+ branch, not the symbolic-ref the user gave checkout as argument.
+ The command learned the "--no-recurse" option to stop after
+ dereferencing a symbolic-ref only once.
+
+ * "git branch --edit-description @{-1}" is now a way to edit branch
+ description of the branch you were on before switching to the
+ current branch.
+
+ * "git merge-tree --stdin" is a new way to request a series of merges
+ and report the merge results.
+
+ * "git shortlog" learned to group by the "format" string.
+
+ * A new "--include-whitespace" option is added to "git patch-id", and
+ existing bugs in the internal patch-id logic that did not match
+ what "git patch-id" produces have been corrected.
+
+ * Enable gc.cruftpacks by default for those who opt into
+ feature.experimental setting.
+
+ * "git repack" learns to send cruft objects out of the way into
+ packfiles outside the repository.
+
+ * 'scalar reconfigure -a' is taught to automatically remove
+ scalar.repo entires which no longer exist.
+
+ * Redact headers from cURL's h2h3 module in GIT_CURL_VERBOSE and
+ others.
+
+ * 'git maintenance register' is taught to write configuration to an
+ arbitrary path, and 'git for-each-repo' is taught to expand tilde
+ characters in paths.
+
+ * When creating new notes, the template used to get a stray empty
+ newline, which has been removed.
+
+ * "git receive-pack" used to use all the local refs as the boundary for
+ checking connectivity of the data "git push" sent, but now it uses
+ only the refs that it advertised to the pusher. In a repository with
+ the .hideRefs configuration, this reduces the resources needed to
+ perform the check.
+
+ * With '--recurse-submodules=on-demand', all submodules are
+ recursively pushed.
+
+
+Performance, Internal Implementation, Development Support etc.
+--------------------------------------------------------------
+
+ * With a bit of header twiddling, use the native regexp library on
+ macOS instead of the compat/ one.
+
+ * Prepare for GNU [ef]grep that throw warning of their uses.
+
+ * Sources related to fuzz testing have been moved down to their own
+ directory.
+
+ * Most credential helpers ignored unknown entries in a credential
+ description, but a few died upon seeing them. The latter were
+ taught to ignore them, too
+
+ * "scalar unregister" in a repository that is already been
+ unregistered reported an error.
+
+ * Remove error detection from a function that fetches from promisor
+ remotes, and make it die when such a fetch fails to bring all the
+ requested objects, to give an early failure to various operations.
+
+ * Update CodingGuidelines to clarify what features to use and avoid
+ in C99.
+
+ * Avoid false-positive from LSan whose assumption may be broken with
+ higher optimization levels.
+
+ * Enable address and undefined sanitizer tasks at GitHub Actions CI.
+
+ * More UNUSED annotation to help using -Wunused option with the
+ compiler.
+ (merge 4b992f0a24 jk/unused-anno-more later to maint).
+
+ * Rewrite a deep recursion in the skipping negotiator to use a loop
+ with on-heap prio queue to avoid stack wastage.
+
+ * Add documentation for message IDs in fsck error messages.
+
+ * Define the logical elements of a "bundle list", data structure to
+ store them in-core, format to transfer them, and code to parse
+ them.
+
+ * The role the security mailing list plays in an embargoed release
+ has been documented.
+
+ * Two new facilities, "timer" and "counter", are introduced to the
+ trace2 API.
+
+ * Code simplification by using strvec_pushf() instead of building an
+ argument in a separate strbuf.
+
+ * Make sure generated dependency file is stably sorted to help
+ developers debugging their build issues.
+
+ * The glossary entries for "commit-graph file" and "reachability
+ bitmap" have been added.
+
+ * Various tests exercising the transfer.credentialsInUrl
+ configuration are taught to avoid making requests which require
+ resolving localhost to reduce CI-flakiness.
+
+ * A redundant diagnostic message is dropped from test_path_is_missing().
+
+ * Simplify the run-command API.
+
+ * Update the actions/github-script dependency in CI to avoid a
+ deprecation warning.
+
+ * Progress on being able to initialize a rev_info struct with a
+ macro.
+
+ * Add trace2 counters to the region to clear skip worktree bits in a
+ sparse checkout.
+
+ * Modernize test script to avoid "test -f" and friends.
+
+ * Avoid calling 'cache_tree_update()' when doing so would be
+ redundant.
+
+ * Update the credential-cache documentation to provide a more
+ realistic example.
+
+ * Makefile comments updates and reordering to clarify knobs used to
+ choose SHA implementations.
+
+ * A design document for sparse-checkout's future directions has been
+ added.
+
+ * Teach chainlint.pl to annotate the original test definition instead
+ of the token stream.
+
+ * "make coccicheck" is time consuming. It has been made to run more
+ incrementally.
+
+ * `parse_object()` has been hardened to check for the existence of a
+ suspected blob object.
+
+ * Adjust the documentation build procedure to GNUmake version 4.4,
+ which made some changes to how pattern rule with multiple targets
+ are handled.
+
+
+Fixes since v2.38
+-----------------
+
+ * The codepath that reads from the index v4 had unaligned memory
+ accesses, which has been corrected.
+
+ * Fix messages incorrectly marked for translation.
+
+ * "git fsck" failed to release contents of tree objects already used
+ from the memory, which has been fixed.
+
+ * "git clone" did not like to see the "--bare" and the "--origin"
+ options used together without a good reason.
+
+ * "git remote rename" failed to rename a remote without fetch
+ refspec, which has been corrected.
+
+ * Documentation on various Boolean GIT_* environment variables have
+ been clarified.
+
+ * "git rebase -i" can mistakenly attempt to apply a fixup to a commit
+ itself, which has been corrected.
+
+ * "git multi-pack-index repack/expire" used to repack unreachable
+ cruft into a new pack, which have been corrected.
+
+ * In read-only repositories, "git merge-tree" tried to come up with a
+ merge result tree object, which it failed (which is not wrong) and
+ led to a segfault (which is bad), which has been corrected.
+
+ * Force C locale while running tests around httpd to make sure we can
+ find expected error messages in the log.
+
+ * Fix a logic in "mailinfo -b" that miscomputed the length of a
+ substring, which lead to an out-of-bounds access.
+
+ * The codepath to sign learned to report errors when it fails to read
+ from "ssh-keygen".
+
+ * Code clean-up that results in plugging a leak.
+
+ * "GIT_EDITOR=: git branch --edit-description" resulted in failure,
+ which has been corrected.
+
+ * The code to clean temporary object directories (used for
+ quarantine) tried to remove them inside its signal handler, which
+ was a no-no.
+
+ * Update comment in the Makefile about the RUNTIME_PREFIX config knob.
+
+ * Clarify that "the sentence after <area>: prefix does not begin with
+ a capital letter" rule applies only to the commit title.
+
+ * "git branch --edit-description" on an unborh branch misleadingly
+ said that no such branch exists, which has been corrected.
+
+ * Work around older clang that warns against C99 zero initialization
+ syntax for struct.
+
+ * Giving "--invert-grep" and "--all-match" without "--grep" to the
+ "git log" command resulted in an attempt to access grep pattern
+ expression structure that has not been allocated, which has been
+ corrected.
+ (merge db84376f98 ab/grep-simplify-extended-expression later to maint).
+
+ * "git diff rev^!" did not show combined diff to go to the rev from
+ its parents.
+ (merge a79c6b6081 rs/diff-caret-bang-with-parents later to maint).
+
+ * Allow configuration files in "protected" scopes to include other
+ configuration files.
+ (merge ecec57b3c9 gc/bare-repo-discovery later to maint).
+
+ * Give a bit more diversity to macOS CI by using sha1dc in one of the
+ jobs (the other one tests Apple Common Crypto).
+ (merge 1ad5c3df35 jc/ci-osx-with-sha1dc later to maint).
+
+ * A bugfix with tracing support in midx codepath
+ (merge e9c3839944 tb/midx-bitmap-selection-fix later to maint).
+
+ * When geometric repacking feature is in use together with the
+ --pack-kept-objects option, we lost packs marked with .keep files.
+ (merge 197443e80a tb/save-keep-pack-during-geometric-repack later to maint).
+
+ * Move a global variable added as a hack during regression fixes to
+ its proper place in the API.
+ (merge 0b0ab95f17 ab/run-hook-api-cleanup later to maint).
+
+ * Update to build procedure with VS using CMake/CTest.
+ (merge c858750b41 js/cmake-updates later to maint).
+
+ * The short-help text shown by "git cmd -h" and the synopsis text
+ shown at the beginning of "git help cmd" have been made more
+ consistent.
+
+ * When creating a multi-pack bitmap, remove per-pack bitmap files
+ unconditionally as they will never be consulted.
+ (merge 55d902cd61 tb/remove-unused-pack-bitmap later to maint).
+
+ * Fix a longstanding syntax error in Git.pm error codepath.
+
+ * "git diff --stat" etc. were invented back when everything was ASCII
+ and strlen() was a way to measure the display width of a string;
+ adjust them to compute the display width assuming UTF-8 pathnames.
+ (merge ce8529b2bb tb/diffstat-with-utf8-strwidth later to maint).
+
+ * "git branch --edit-description" can exit with status -1 which is
+ not a good practice; it learned to use 1 as everybody else instead.
+
+ * "git apply" limits its input to a bit less than 1 GiB.
+
+ * Merging a branch with directory renames into a branch that changes
+ the directory to a symlink was mishandled by the ort merge
+ strategy, which has been corrected.
+
+ * A bugfix to "git subtree" in its split and merge features.
+
+ * Fix some bugs in the reflog messages when rebasing and changes the
+ reflog messages of "rebase --apply" to match "rebase --merge" with
+ the aim of making the reflog easier to parse.
+
+ * "git rebase --keep-base" used to discard the commits that are
+ already cherry-picked to the upstream, even when "keep-base" meant
+ that the base, on top of which the history is being rebuilt, does
+ not yet include these cherry-picked commits. The --keep-base
+ option now implies --reapply-cherry-picks and --no-fork-point
+ options.
+
+ * The way "git repack" creared temporary files when it received a
+ signal was prone to deadlocking, which has been corrected.
+
+ * Various tests exercising the transfer.credentialsInUrl
+ configuration are taught to avoid making requests which require
+ resolving localhost to reduce CI-flakiness.
+
+ * The adjust_shared_perm() helper function learned to refrain from
+ setting the "g+s" bit on directories when it is not necessary.
+
+ * "git archive" mistakenly complained twice about a missing
+ executable, which has been corrected.
+
+ * Fix a bug where `git branch -d` did not work on an orphaned HEAD.
+
+ * `git rebase --update-refs` would delete references when all
+ `update-ref` commands in the sequencer were removed, which has been
+ corrected.
+
+ * Fix a regression in the bisect-helper which mistakenly treats
+ arguments to the command given to 'git bisect run' as arguments to
+ the helper.
+
+ * Correct an error where `git rebase` would mistakenly use a branch or
+ tag named "refs/rewritten/xyz" when missing a rebase label.
+
+ * Assorted fixes of parsing end-user input as integers.
+ (merge 14770cf0de pw/config-int-parse-fixes later to maint).
+
+ * "git prune" may try to iterate over .git/objects/pack for trash
+ files to remove in it, and loudly fail when the directory is
+ missing, which is not necessary. The command has been taught to
+ ignore such a failure.
+ (merge 6974765352 ew/prune-with-missing-objects-pack later to maint).
+
+ * Add one more candidate directory that may house httpd modules while
+ running tests.
+ (merge 1c7dc23d41 es/locate-httpd-module-location-in-test later to maint).
+
+ * A handful of leaks in the line-log machinery have been plugged.
+
+ * The format of a line in /proc/cpuinfo that describes a CPU on s390x
+ looked different from everybody else, and the code in chainlint.pl
+ failed to parse it.
+ (merge 1f51b77f4f ah/chainlint-cpuinfo-parse-fix later to maint).
+
+ * Adjust the GitHub CI to newer ubuntu release.
+ (merge 0d3507f3e7 jx/ci-ubuntu-fix later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge 413bc6d20a ds/cmd-main-reorder later to maint).
+ (merge 8d2863e4ed nw/t1002-cleanup later to maint).
+ (merge 7c2dc122f9 rs/list-objects-filter-leakfix later to maint).
+ (merge 288fcb1c94 zk/push-use-bitmaps later to maint).
+ (merge 42db324c0f km/merge-recursive-typofix later to maint).
diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt
new file mode 100644
index 0000000..0e323d5
--- /dev/null
+++ b/Documentation/ReviewingGuidelines.txt
@@ -0,0 +1,162 @@
+Reviewing Patches in the Git Project
+====================================
+
+Introduction
+------------
+The Git development community is a widely distributed, diverse, ever-changing
+group of individuals. Asynchronous communication via the Git mailing list poses
+unique challenges when reviewing or discussing patches. This document contains
+some guiding principles and helpful tools you can use to make your reviews both
+more efficient for yourself and more effective for other contributors.
+
+Note that none of the recommendations here are binding or in any way a
+requirement of participation in the Git community. They are provided as a
+resource to supplement your skills as a contributor.
+
+Principles
+----------
+
+Selecting patch(es) to review
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you are looking for a patch series in need of review, start by checking
+latest "What's cooking in git.git" email
+(https://lore.kernel.org/git/xmqqilm1yp3m.fsf@gitster.g/[example]). The "What's
+cooking" emails & replies can be found using the query `s:"What's cooking"` on
+the https://lore.kernel.org/git/[`lore.kernel.org` mailing list archive];
+alternatively, you can find the contents of the "What's cooking" email tracked
+in `whats-cooking.txt` on the `todo` branch of Git. Topics tagged with "Needs
+review" and those in the "[New Topics]" section are typically those that would
+benefit the most from additional review.
+
+Patches can also be searched manually in the mailing list archive using a query
+like `s:"PATCH" -s:"Re:"`. You can browse these results for topics relevant to
+your expertise or interest.
+
+If you've already contributed to Git, you may also be CC'd in another
+contributor's patch series. These are topics where the author feels that your
+attention is warranted. This may be because their patch changes something you
+wrote previously (making you a good judge of whether the new approach does or
+doesn't work), or because you have the expertise to provide an exceptionally
+helpful review. There is no requirement to review these patches but, in the
+spirit of open source collaboration, you should strongly consider doing so.
+
+Reviewing patches
+~~~~~~~~~~~~~~~~~
+While every contributor takes their own approach to reviewing patches, here are
+some general pieces of advice to make your reviews as clear and helpful as
+possible. The advice is broken into two rough categories: high-level reviewing
+guidance, and concrete tips for interacting with patches on the mailing list.
+
+==== High-level guidance
+- Remember to review the content of commit messages for correctness and clarity,
+ in addition to the code change in the patch's diff. The commit message of a
+ patch should accurately and fully explain the code change being made in the
+ diff.
+
+- Reviewing test coverage is an important - but easy to overlook - component of
+ reviews. A patch's changes may be covered by existing tests, or new tests may
+ be introduced to exercise new behavior. Checking out a patch or series locally
+ allows you to manually mutate lines of new & existing tests to verify expected
+ pass/fail behavior. You can use this information to verify proper coverage or
+ to suggest additional tests the author could add.
+
+- When providing a recommendation, be as clear as possible about whether you
+ consider it "blocking" (the code would be broken or otherwise made worse if an
+ issue isn't fixed) or "non-blocking" (the patch could be made better by taking
+ the recommendation, but acceptance of the series does not require it).
+ Non-blocking recommendations can be particularly ambiguous when they are
+ related to - but outside the scope of - a series ("nice-to-have"s), or when
+ they represent only stylistic differences between the author and reviewer.
+
+- When commenting on an issue, try to include suggestions for how the author
+ could fix it. This not only helps the author to understand and fix the issue,
+ it also deepens and improves your understanding of the topic.
+
+- Reviews do not need to exclusively point out problems. Feel free to "think out
+ loud" in your review: describe how you read & understood a complex section of
+ a patch, ask a question about something that confused you, point out something
+ you found exceptionally well-written, etc. In particular, uplifting feedback
+ goes a long way towards encouraging contributors to participate more actively
+ in the Git community.
+
+==== Performing your review
+- Provide your review comments per-patch in a plaintext "Reply-All" email to the
+ relevant patch. Comments should be made inline, immediately below the relevant
+ section(s).
+
+- You may find that the limited context provided in the patch diff is sometimes
+ insufficient for a thorough review. In such cases, you can review patches in
+ your local tree by either applying patches with linkgit:git-am[1] or checking
+ out the associated branch from https://github.com/gitster/git once the series
+ is tracked there.
+
+- Large, complicated patch diffs are sometimes unavoidable, such as when they
+ refactor existing code. If you find such a patch difficult to parse, try
+ reviewing the diff produced with the `--color-moved` and/or
+ `--ignore-space-change` options.
+
+- If a patch is long, you are encouraged to delete parts of it that are
+ unrelated to your review from the email reply. Make sure to leave enough
+ context for readers to understand your comments!
+
+- If you cannot complete a full review of a series all at once, consider letting
+ the author know (on- or off-list) if/when you plan to review the rest of the
+ series.
+
+Completing a review
+~~~~~~~~~~~~~~~~~~~
+Once each patch of a series is reviewed, the author (and/or other contributors)
+may discuss the review(s). This may result in no changes being applied, or the
+author will send a new version of their patch(es).
+
+After a series is rerolled in response to your or others' review, make sure to
+re-review the updates. If you are happy with the state of the patch series,
+explicitly indicate your approval (typically with a reply to the latest
+version's cover letter). Optionally, you can let the author know that they can
+add a "Reviewed-by: <you>" trailer if they resubmit the reviewed patch verbatim
+in a later iteration of the series.
+
+Finally, subsequent "What's cooking" emails may explicitly ask whether a
+reviewed topic is ready for merging to the `next` branch (typically phrased
+"Will merge to \'next\'?"). You can help the maintainer and author by responding
+with a short description of the state of your (and others', if applicable)
+review, including the links to the relevant thread(s).
+
+Terminology
+-----------
+nit: ::
+ Denotes a small issue that should be fixed, such as a typographical error
+ or mis-alignment of conditions in an `if()` statement.
+
+aside: ::
+optional: ::
+non-blocking: ::
+ Indicates to the reader that the following comment should not block the
+ acceptance of the patch or series. These are typically recommendations
+ related to code organization & style, or musings about topics related to
+ the patch in question, but beyond its scope.
+
+s/<before>/<after>/::
+ Shorthand for "you wrote <before>, but I think you meant <after>," usually
+ for misspellings or other typographical errors. The syntax is a reference
+ to "substitute" command commonly found in Unix tools such as `ed`, `sed`,
+ `vim`, and `perl`.
+
+cover letter::
+ The "Patch 0" of a multi-patch series. This email describes the
+ high-level intent and structure of the patch series to readers on the
+ Git mailing list. It is also where the changelog notes and range-diff of
+ subsequent versions are provided by the author.
++
+On single-patch submissions, cover letter content is typically not sent as a
+separate email. Instead, it is inserted between the end of the patch's commit
+message (after the `---`) and the beginning of the diff.
+
+#leftoverbits::
+ Used by either an author or a reviewer to describe features or suggested
+ changes that are out-of-scope of a given patch or series, but are relevant
+ to the topic for the sake of discussion.
+
+See Also
+--------
+link:MyFirstContribution.html[MyFirstContribution]
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 5bd795e..927f732 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -153,7 +153,9 @@ files you are modifying to see the current conventions.
[[summary-section]]
The title sentence after the "area:" prefix omits the full stop at the
-end, and its first word is not capitalized unless there is a reason to
+end, and its first word is not capitalized (the omission
+of capitalization applies only to the word after the "area:"
+prefix of the title) unless there is a reason to
capitalize it other than because it is the first word in the sentence.
E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt:
improve...", not "githooks.txt: Improve...". But "refs: HEAD is also
diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl
index ba4205e..1b3ac8f 100755
--- a/Documentation/build-docdep.perl
+++ b/Documentation/build-docdep.perl
@@ -38,9 +38,10 @@ while ($changed) {
}
}
-while (my ($text, $included) = each %include) {
+foreach my $text (sort keys %include) {
+ my $included = $include{$text};
if (! exists $included{$text} &&
(my $base = $text) =~ s/\.txt$//) {
- print "$base.html $base.xml : ", join(" ", keys %$included), "\n";
+ print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n";
}
}
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index af5da45..755a110 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -10,7 +10,7 @@ sub format_one {
$state = 0;
open I, '<', "$name.txt" or die "No such file $name.txt";
while (<I>) {
- if (/^git[a-z0-9-]*\(([0-9])\)$/) {
+ if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) {
$mansection = $1;
next;
}
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 5b5b976..0e93aef 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -387,6 +387,8 @@ include::config/branch.txt[]
include::config/browser.txt[]
+include::config/bundle.txt[]
+
include::config/checkout.txt[]
include::config/clean.txt[]
@@ -423,6 +425,8 @@ include::config/filter.txt[]
include::config/fsck.txt[]
+include::config/fsmonitor--daemon.txt[]
+
include::config/gc.txt[]
include::config/gitcvs.txt[]
diff --git a/Documentation/config/bundle.txt b/Documentation/config/bundle.txt
new file mode 100644
index 0000000..daa21eb
--- /dev/null
+++ b/Documentation/config/bundle.txt
@@ -0,0 +1,24 @@
+bundle.*::
+ The `bundle.*` keys may appear in a bundle list file found via the
+ `git clone --bundle-uri` option. These keys currently have no effect
+ if placed in a repository config file, though this will change in the
+ future. See link:technical/bundle-uri.html[the bundle URI design
+ document] for more details.
+
+bundle.version::
+ This integer value advertises the version of the bundle list format
+ used by the bundle list. Currently, the only accepted value is `1`.
+
+bundle.mode::
+ This string value should be either `all` or `any`. This value describes
+ whether all of the advertised bundles are required to unbundle a
+ complete understanding of the bundled information (`all`) or if any one
+ of the listed bundle URIs is sufficient (`any`).
+
+bundle.<id>.*::
+ The `bundle.<id>.*` keys are used to describe a single item in the
+ bundle list, grouped under `<id>` for identification purposes.
+
+bundle.<id>.uri::
+ This string value defines the URI by which Git can reach the contents
+ of this `<id>`. This URI may be a bundle file or another bundle list.
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index 37afbaf..dfbdaf0 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -618,7 +618,7 @@ but risks losing recent work in the event of an unclean system shutdown.
* `loose-object` hardens objects added to the repo in loose-object form.
* `pack` hardens objects added to the repo in packfile form.
* `pack-metadata` hardens packfile bitmaps and indexes.
-* `commit-graph` hardens the commit graph file.
+* `commit-graph` hardens the commit-graph file.
* `index` hardens the index when it is modified.
* `objects` is an aggregate option that is equivalent to
`loose-object,pack`.
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index 32f8483..35a7bf8 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -178,21 +178,6 @@ diff.<driver>.cachetextconv::
Set this option to true to make the diff driver cache the text
conversion outputs. See linkgit:gitattributes[5] for details.
-diff.tool::
- Controls which diff tool is used by linkgit:git-difftool[1].
- This variable overrides the value configured in `merge.tool`.
- The list below shows the valid built-in values.
- Any other value is treated as a custom diff tool and requires
- that a corresponding difftool.<tool>.cmd variable is defined.
-
-diff.guitool::
- Controls which diff tool is used by linkgit:git-difftool[1] when
- the -g/--gui flag is specified. This variable overrides the value
- configured in `merge.guitool`. The list below shows the valid
- built-in values. Any other value is treated as a custom diff tool
- and requires that a corresponding difftool.<guitool>.cmd variable
- is defined.
-
include::../mergetools-diff.txt[]
diff.indentHeuristic::
diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt
index 6762594..a3f8211 100644
--- a/Documentation/config/difftool.txt
+++ b/Documentation/config/difftool.txt
@@ -1,6 +1,17 @@
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
+diff.tool::
+ Controls which diff tool is used by linkgit:git-difftool[1].
+ This variable overrides the value configured in `merge.tool`.
+ The list below shows the valid built-in values.
+ Any other value is treated as a custom diff tool and requires
+ that a corresponding difftool.<tool>.cmd variable is defined.
+
+diff.guitool::
+ Controls which diff tool is used by linkgit:git-difftool[1] when
+ the -g/--gui flag is specified. This variable overrides the value
+ configured in `merge.guitool`. The list below shows the valid
+ built-in values. Any other value is treated as a custom diff tool
+ and requires that a corresponding difftool.<guitool>.cmd variable
+ is defined.
difftool.<tool>.cmd::
Specify the command to invoke the specified diff tool.
@@ -9,6 +20,17 @@ difftool.<tool>.cmd::
file containing the contents of the diff pre-image and 'REMOTE'
is set to the name of the temporary file containing the contents
of the diff post-image.
++
+See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
+
+difftool.<tool>.path::
+ Override the path for the given tool. This is useful in case
+ your tool is not in the PATH.
+
+difftool.trustExitCode::
+ Exit difftool if the invoked diff tool returns a non-zero exit status.
++
+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
difftool.prompt::
Prompt before each invocation of the diff tool.
diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt
index cdecd04..95975e5 100644
--- a/Documentation/config/feature.txt
+++ b/Documentation/config/feature.txt
@@ -14,6 +14,9 @@ feature.experimental::
+
* `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by
skipping more commits at a time, reducing the number of round trips.
++
+* `gc.cruftPacks=true` reduces disk space used by unreachable objects during
+garbage collection, preventing loose object explosions.
feature.manyFiles::
Enable config options that optimize for repos with many files in the
diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt
index fdbc06a..c7303d8 100644
--- a/Documentation/config/format.txt
+++ b/Documentation/config/format.txt
@@ -15,6 +15,10 @@ format.from::
different. If set to a non-boolean value, format-patch uses that
value instead of your committer identity. Defaults to false.
+format.forceInBodyFrom::
+ Provides the default value for the `--[no-]force-in-body-from`
+ option to format-patch. Defaults to false.
+
format.numbered::
A boolean which can enable or disable sequence numbers in patch
subjects. It defaults to "auto" which enables it only if there
diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt
index 450e8c3..a3c865d 100644
--- a/Documentation/config/fsck.txt
+++ b/Documentation/config/fsck.txt
@@ -35,6 +35,10 @@ allow new instances of the same breakages go unnoticed.
Setting an unknown `fsck.<msg-id>` value will cause fsck to die, but
doing the same for `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>`
will only cause git to warn.
++
+See `Fsck Messages` section of linkgit:git-fsck[1] for supported
+values of `<msg-id>`.
+
fsck.skipList::
The path to a list of object names (i.e. one unabbreviated SHA-1 per
diff --git a/Documentation/config/fsmonitor--daemon.txt b/Documentation/config/fsmonitor--daemon.txt
new file mode 100644
index 0000000..c225c6c
--- /dev/null
+++ b/Documentation/config/fsmonitor--daemon.txt
@@ -0,0 +1,11 @@
+fsmonitor.allowRemote::
+ By default, the fsmonitor daemon refuses to work against network-mounted
+ repositories. Setting `fsmonitor.allowRemote` to `true` overrides this
+ behavior. Only respected when `core.fsmonitor` is set to `true`.
+
+fsmonitor.socketDir::
+ This Mac OS-specific option, if set, specifies the directory in
+ which to create the Unix domain socket used for communication
+ between the fsmonitor daemon and various Git commands. The directory must
+ reside on a native Mac OS filesystem. Only respected when `core.fsmonitor`
+ is set to `true`.
diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index 182edd8..e521f20 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -17,8 +17,11 @@ grep.extendedRegexp::
other than 'default'.
grep.threads::
- Number of grep worker threads to use.
- See `grep.threads` in linkgit:git-grep[1] for more information.
+ Number of grep worker threads to use. If unset (or set to 0), Git will
+ use as many threads as the number of logical cores available.
+
+grep.fullName::
+ If set to true, enable `--full-name` option by default.
grep.fallbackToNoIndex::
If set to true, fall back to git grep --no-index if git grep
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 456eb07..5f96cf8 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -7,6 +7,10 @@ log.date::
Set the default date-time mode for the 'log' command.
Setting a value for log.date is similar to using 'git log''s
`--date` option. See linkgit:git-log[1] for details.
++
+If the format is set to "auto:foo" and the pager is in use, format
+"foo" will be the used for the date format. Otherwise "default" will
+be used.
log.decorate::
Print out the ref names of any commits that are shown by the log
@@ -18,6 +22,11 @@ log.decorate::
names are shown. This is the same as the `--decorate` option
of the `git log`.
+log.initialDecorationSet::
+ By default, `git log` only shows decorations for certain known ref
+ namespaces. If 'all' is specified, then show all refs as
+ decorations.
+
log.excludeDecoration::
Exclude the specified patterns from the log decorations. This is
similar to the `--decorate-refs-exclude` command-line option, but
@@ -25,9 +34,9 @@ log.excludeDecoration::
option.
log.diffMerges::
- Set default diff format to be used for merge commits. See
- `--diff-merges` in linkgit:git-log[1] for details.
- Defaults to `separate`.
+ Set diff format to be used when `--diff-merges=on` is
+ specified, see `--diff-merges` in linkgit:git-log[1] for
+ details. Defaults to `separate`.
log.follow::
If `true`, `git log` will act as if the `--follow` option was used when
diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt
index adeda0f..3d88fb0 100644
--- a/Documentation/config/lsrefs.txt
+++ b/Documentation/config/lsrefs.txt
@@ -1,7 +1,7 @@
lsrefs.unborn::
May be "advertise" (the default), "allow", or "ignore". If "advertise",
the server will respond to the client sending "unborn" (as described in
- protocol-v2.txt) and will advertise support for this feature during the
+ linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the
protocol v2 capability advertisement. "allow" is the same as
"advertise" except that the server will not advertise support for this
feature; this is useful for load-balanced servers that cannot be
diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt
index 90b3809..e779a12 100644
--- a/Documentation/config/mergetool.txt
+++ b/Documentation/config/mergetool.txt
@@ -59,7 +59,7 @@ mergetool.hideResolved::
possible and write the 'MERGED' file containing conflict markers around
any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally
represent the versions of the file from before Git's conflict
- resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwriten so
+ resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so
that only the unresolved conflicts are presented to the merge tool. Can
be configured per-tool via the `mergetool.<tool>.hideResolved`
configuration variable. Defaults to `false`.
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d..c7c4811 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -3,6 +3,9 @@ notes.mergeStrategy::
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
`cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
section of linkgit:git-notes[1] for more information on each strategy.
++
+This setting can be overridden by passing the `--strategy` option to
+linkgit:git-notes[1].
notes.<name>.mergeStrategy::
Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
linkgit:git-notes[1] for more information on the available strategies.
notes.displayRef::
- The (fully qualified) refname from which to show notes when
- showing commit messages. The value of this variable can be set
- to a glob, in which case notes from all matching refs will be
- shown. You may also specify this configuration variable
- several times. A warning will be issued for refs that do not
- exist, but a glob that does not match any refs is silently
- ignored.
+ Which ref (or refs, if a glob or specified more than once), in
+ addition to the default set by `core.notesRef` or
+ `GIT_NOTES_REF`, to read notes from when showing commit
+ messages with the 'git log' family of commands.
+
This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
environment variable, which must be a colon separated list of refs or
globs.
+
+A warning will be issued for refs that do not exist,
+but a glob that does not match any refs is silently ignored.
++
+This setting can be disabled by the `--no-notes` option to the 'git
+log' family of commands, or by the `--notes=<ref>` option accepted by
+those commands.
++
The effective value of "core.notesRef" (possibly overridden by
GIT_NOTES_REF) is also implicitly added to the list of refs to be
displayed.
notes.rewrite.<command>::
When rewriting commits with <command> (currently `amend` or
- `rebase`) and this variable is set to `true`, Git
- automatically copies your notes from the original to the
- rewritten commit. Defaults to `true`, but see
- "notes.rewriteRef" below.
+ `rebase`), if this variable is `false`, git will not copy
+ notes from the original to the rewritten commit. Defaults to
+ `true`. See also "`notes.rewriteRef`" below.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
notes.rewriteMode::
When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ environment variable.
notes.rewriteRef::
When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. The ref may be a
- glob, in which case notes in all matching refs will be copied.
- You may also specify this configuration several times.
+ qualified) ref whose notes should be copied. May be a glob,
+ in which case notes in all matching refs will be copied. You
+ may also specify this configuration several times.
+
Does not have a default value; you must configure this variable to
enable note rewriting. Set it to `refs/notes/commits` to enable
rewriting for the default commit notes.
+
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+See `notes.rewrite.<command>` above for a further description of its format.
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index ad7f73a..53093d9 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -164,9 +164,16 @@ When writing a multi-pack reachability bitmap, no new namehashes are
computed; instead, any namehashes stored in an existing bitmap are
permuted into their appropriate location when writing a new bitmap.
+pack.writeBitmapLookupTable::
+ When true, Git will include a "lookup table" section in the
+ bitmap index (if one is written). This table is used to defer
+ loading individual bitmaps as late as possible. This can be
+ beneficial in repositories that have relatively large bitmap
+ indexes. Defaults to false.
+
pack.writeReverseIndex::
When true, git will write a corresponding .rev file (see:
- link:../technical/pack-format.html[Documentation/technical/pack-format.txt])
+ linkgit:gitformat-pack[5])
for each new packfile that it writes in all places except for
linkgit:git-fast-import[1] and in the bulk checkin mechanism.
Defaults to false.
diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt
index 756591d..a9bf187 100644
--- a/Documentation/config/protocol.txt
+++ b/Documentation/config/protocol.txt
@@ -1,10 +1,10 @@
protocol.allow::
If set, provide a user defined default policy for all protocols which
don't explicitly have a policy (`protocol.<name>.allow`). By default,
- if unset, known-safe protocols (http, https, git, ssh, file) have a
+ if unset, known-safe protocols (http, https, git, ssh) have a
default policy of `always`, known-dangerous protocols (ext) have a
- default policy of `never`, and all other protocols have a default
- policy of `user`. Supported policies:
+ default policy of `never`, and all other protocols (including file)
+ have a default policy of `user`. Supported policies:
+
--
@@ -58,6 +58,6 @@ protocol.version::
* `1` - the original wire protocol with the addition of a version string
in the initial response from the server.
-* `2` - link:technical/protocol-v2.html[wire protocol version 2].
+* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].
--
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 7386fea..43338b6 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -110,18 +110,8 @@ This will result in only b (a and c are cleared).
----
push.recurseSubmodules::
- Make sure all submodule commits used by the revisions to be pushed
- are available on a remote-tracking branch. If the value is 'check'
- then Git will verify that all submodule commits that changed in the
- revisions to be pushed are available on at least one remote of the
- submodule. If any commits are missing, the push will be aborted and
- exit with non-zero status. If the value is 'on-demand' then all
- submodules that changed in the revisions to be pushed will be
- pushed. If on-demand was not able to push all necessary revisions
- it will also be aborted and exit with non-zero status. If the value
- is 'no' then default behavior of ignoring submodules when pushing
- is retained. You may override this configuration at time of push by
- specifying '--recurse-submodules=check|on-demand|no'.
+ May be "check", "on-demand", "only", or "no", with the same behavior
+ as that of "push --recurse-submodules".
If not set, 'no' is used by default, unless 'submodule.recurse' is
set (in which case a 'true' value means 'on-demand').
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
index 50baa5d..51da708 100644
--- a/Documentation/config/sendemail.txt
+++ b/Documentation/config/sendemail.txt
@@ -18,17 +18,49 @@ sendemail.<identity>.*::
identity is selected, through either the command-line or
`sendemail.identity`.
+sendemail.multiEdit::
+ If true (default), a single editor instance will be spawned to edit
+ files you have to edit (patches when `--annotate` is used, and the
+ summary when `--compose` is used). If false, files will be edited one
+ after the other, spawning a new editor each time.
+
+sendemail.confirm::
+ Sets the default for whether to confirm before sending. Must be
+ one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
+ in the linkgit:git-send-email[1] documentation for the meaning of these
+ values.
+
sendemail.aliasesFile::
+ To avoid typing long email addresses, point this to one or more
+ email aliases files. You must also supply `sendemail.aliasFileType`.
+
sendemail.aliasFileType::
+ Format of the file(s) specified in sendemail.aliasesFile. Must be
+ one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
++
+What an alias file in each format looks like can be found in
+the documentation of the email program of the same name. The
+differences and limitations from the standard formats are
+described below:
++
+--
+sendmail;;
+* Quoted aliases and quoted addresses are not supported: lines that
+ contain a `"` symbol are ignored.
+* Redirection to a file (`/path/name`) or pipe (`|command`) is not
+ supported.
+* File inclusion (`:include: /path/name`) is not supported.
+* Warnings are printed on the standard error output for any
+ explicitly unsupported constructs, and any other lines that are not
+ recognized by the parser.
+--
sendemail.annotate::
sendemail.bcc::
sendemail.cc::
sendemail.ccCmd::
sendemail.chainReplyTo::
-sendemail.confirm::
sendemail.envelopeSender::
sendemail.from::
-sendemail.multiEdit::
sendemail.signedoffbycc::
sendemail.smtpPass::
sendemail.suppresscc::
@@ -44,7 +76,9 @@ sendemail.thread::
sendemail.transferEncoding::
sendemail.validate::
sendemail.xmailer::
- See linkgit:git-send-email[1] for description.
+ These configuration variables all provide a default for
+ linkgit:git-send-email[1] command-line options. See its
+ documentation for details.
sendemail.signedoffcc (deprecated)::
Deprecated alias for `sendemail.signedoffbycc`.
diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt
index 7ed917f..264812c 100644
--- a/Documentation/config/transfer.txt
+++ b/Documentation/config/transfer.txt
@@ -13,7 +13,7 @@ Note that this is currently limited to detecting credentials in
You might want to enable this to prevent inadvertent credentials
exposure, e.g. because:
+
-* The OS or system where you're running git may not provide way way or
+* The OS or system where you're running git may not provide a way or
otherwise allow you to configure the permissions of the
configuration file where the username and/or password are stored.
* Even if it does, having such data stored "at rest" might expose you
diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt
new file mode 100644
index 0000000..7af76ff
--- /dev/null
+++ b/Documentation/fsck-msgids.txt
@@ -0,0 +1,161 @@
+`badDate`::
+ (ERROR) Invalid date format in an author/committer line.
+
+`badDateOverflow`::
+ (ERROR) Invalid date value in an author/committer line.
+
+`badEmail`::
+ (ERROR) Invalid email format in an author/committer line.
+
+`badFilemode`::
+ (INFO) A tree contains a bad filemode entry.
+
+`badName`::
+ (ERROR) An author/committer name is empty.
+
+`badObjectSha1`::
+ (ERROR) An object has a bad sha1.
+
+`badParentSha1`::
+ (ERROR) A commit object has a bad parent sha1.
+
+`badTagName`::
+ (INFO) A tag has an invalid format.
+
+`badTimezone`::
+ (ERROR) Found an invalid time zone in an author/committer line.
+
+`badTree`::
+ (ERROR) A tree cannot be parsed.
+
+`badTreeSha1`::
+ (ERROR) A tree has an invalid format.
+
+`badType`::
+ (ERROR) Found an invalid object type.
+
+`duplicateEntries`::
+ (ERROR) A tree contains duplicate file entries.
+
+`emptyName`::
+ (WARN) A path contains an empty name.
+
+`extraHeaderEntry`::
+ (IGNORE) Extra headers found after `tagger`.
+
+`fullPathname`::
+ (WARN) A path contains the full path starting with "/".
+
+`gitattributesSymlink`::
+ (INFO) `.gitattributes` is a symlink.
+
+`gitignoreSymlink`::
+ (INFO) `.gitignore` is a symlink.
+
+`gitmodulesBlob`::
+ (ERROR) A non-blob found at `.gitmodules`.
+
+`gitmodulesLarge`::
+ (ERROR) The `.gitmodules` file is too large to parse.
+
+`gitmodulesMissing`::
+ (ERROR) Unable to read `.gitmodules` blob.
+
+`gitmodulesName`::
+ (ERROR) A submodule name is invalid.
+
+`gitmodulesParse`::
+ (INFO) Could not parse `.gitmodules` blob.
+
+`gitmodulesLarge`;
+ (ERROR) `.gitmodules` blob is too large to parse.
+
+`gitmodulesPath`::
+ (ERROR) `.gitmodules` path is invalid.
+
+`gitmodulesSymlink`::
+ (ERROR) `.gitmodules` is a symlink.
+
+`gitmodulesUpdate`::
+ (ERROR) Found an invalid submodule update setting.
+
+`gitmodulesUrl`::
+ (ERROR) Found an invalid submodule url.
+
+`hasDot`::
+ (WARN) A tree contains an entry named `.`.
+
+`hasDotdot`::
+ (WARN) A tree contains an entry named `..`.
+
+`hasDotgit`::
+ (WARN) A tree contains an entry named `.git`.
+
+`mailmapSymlink`::
+ (INFO) `.mailmap` is a symlink.
+
+`missingAuthor`::
+ (ERROR) Author is missing.
+
+`missingCommitter`::
+ (ERROR) Committer is missing.
+
+`missingEmail`::
+ (ERROR) Email is missing in an author/committer line.
+
+`missingNameBeforeEmail`::
+ (ERROR) Missing name before an email in an author/committer line.
+
+`missingObject`::
+ (ERROR) Missing `object` line in tag object.
+
+`missingSpaceBeforeDate`::
+ (ERROR) Missing space before date in an author/committer line.
+
+`missingSpaceBeforeEmail`::
+ (ERROR) Missing space before the email in author/committer line.
+
+`missingTag`::
+ (ERROR) Unexpected end after `type` line in a tag object.
+
+`missingTagEntry`::
+ (ERROR) Missing `tag` line in a tag object.
+
+`missingTaggerEntry`::
+ (INFO) Missing `tagger` line in a tag object.
+
+`missingTree`::
+ (ERROR) Missing `tree` line in a commit object.
+
+`missingType`::
+ (ERROR) Invalid type value on the `type` line in a tag object.
+
+`missingTypeEntry`::
+ (ERROR) Missing `type` line in a tag object.
+
+`multipleAuthors`::
+ (ERROR) Multiple author lines found in a commit.
+
+`nulInCommit`::
+ (WARN) Found a NUL byte in the commit object body.
+
+`nulInHeader`::
+ (FATAL) NUL byte exists in the object header.
+
+`nullSha1`::
+ (WARN) Tree contains entries pointing to a null sha1.
+
+`treeNotSorted`::
+ (ERROR) A tree is not properly sorted.
+
+`unknownType`::
+ (ERROR) Found an unknown object type.
+
+`unterminatedHeader`::
+ (FATAL) Missing end-of-line in the object header.
+
+`zeroPaddedDate`::
+ (ERROR) Found a zero padded date in an author/commiter line.
+
+`zeroPaddedFilemode`::
+ (WARN) Found a zero padded filemode in a tree.
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 11eb70f..a030d33 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -188,7 +188,9 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
forcibly add them again to the index. This is useful after
changing `core.autocrlf` configuration or the `text` attribute
in order to correct files added with wrong CRLF/LF line endings.
- This option implies `-u`.
+ This option implies `-u`. Lone CR characters are untouched, thus
+ while a CRLF cleans to LF, a CRCRLF sequence is only partially
+ cleaned to CRLF.
--chmod=(+|-)x::
Override the executable bit of the added files. The executable
@@ -431,6 +433,13 @@ they will make the patch impossible to apply:
* deleting context or removal lines
* modifying the contents of context or removal lines
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/add.txt[]
+
SEE ALSO
--------
linkgit:git-status[1]
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 09107fb..326276e 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -112,10 +112,7 @@ default. You can use `--no-utf8` to override this.
am.threeWay configuration variable. For more information,
see am.threeWay in linkgit:git-config[1].
---rerere-autoupdate::
---no-rerere-autoupdate::
- Allow the rerere mechanism to update the index with the
- result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
--ignore-space-change::
--ignore-whitespace::
@@ -261,6 +258,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,
and `post-applypatch` hooks. See linkgit:githooks[5] for more
information.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/am.txt[]
+
SEE ALSO
--------
linkgit:git-apply[1].
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index e44a831..5ae8aab 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information
SYNOPSIS
--------
[verse]
-'git annotate' [<options>] <file> [<revision>]
+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>
DESCRIPTION
-----------
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index b6d77f4..1d478cb 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.
CONFIGURATION
-------------
-apply.ignoreWhitespace::
- Set to 'change' if you want changes in whitespace to be ignored by default.
- Set to one of: no, none, never, false if you want changes in
- whitespace to be significant.
-apply.whitespace::
- When no `--whitespace` flag is given from the command
- line, this configuration item is used as the default.
+include::includes/cmd-config-section-all.txt[]
+
+include::config/apply.txt[]
SUBMODULES
----------
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index d7a46cc..4400a17 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -241,6 +241,12 @@ MAPPING AUTHORS
See linkgit:gitmailmap[5].
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/blame.txt[]
SEE ALSO
--------
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index ae82378..12c5f84 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -336,6 +336,10 @@ CONFIGURATION
`--list` is used or implied. The default is to use a pager.
See linkgit:git-config[1].
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/branch.txt[]
+
EXAMPLES
--------
diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt
index d8817bf..eca726e 100644
--- a/Documentation/git-bugreport.txt
+++ b/Documentation/git-bugreport.txt
@@ -9,6 +9,7 @@ SYNOPSIS
--------
[verse]
'git bugreport' [(-o | --output-directory) <path>] [(-s | --suffix) <format>]
+ [--diagnose[=<mode>]]
DESCRIPTION
-----------
@@ -31,6 +32,10 @@ The following information is captured automatically:
- A list of enabled hooks
- $SHELL
+Additional information may be gathered into a separate zip archive using the
+`--diagnose` option, and can be attached alongside the bugreport document to
+provide additional context to readers.
+
This tool is invoked via the typical Git setup process, which means that in some
cases, it might not be able to launch - for example, if a relevant config file
is unreadable. In this kind of scenario, it may be helpful to manually gather
@@ -49,6 +54,19 @@ OPTIONS
named 'git-bugreport-<formatted suffix>'. This should take the form of a
strftime(3) format string; the current local time will be used.
+--no-diagnose::
+--diagnose[=<mode>]::
+ Create a zip archive of supplemental information about the user's
+ machine, Git client, and repository state. The archive is written to the
+ same output directory as the bug report and is named
+ 'git-diagnostics-<formatted suffix>'.
++
+Without `mode` specified, the diagnostic archive will contain the default set of
+statistics reported by `git diagnose`. An optional `mode` value may be specified
+to change which information is included in the archive. See
+linkgit:git-diagnose[1] for the list of valid values for `mode` and details
+about their usage.
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 7685b57..18a022b 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -42,7 +42,7 @@ BUNDLE FORMAT
Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
header indicating what references are contained within the bundle.
-Like the the packed archive format itself bundles can either be
+Like the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
See the "OBJECT PREREQUISITES" section below.
@@ -56,10 +56,8 @@ using "thin packs", bundles created using exclusions are smaller in
size. That they're "thin" under the hood is merely noted here as a
curiosity, and as a reference to other documentation.
-See link:technical/bundle-format.html[the `bundle-format`
-documentation] for more details and the discussion of "thin pack" in
-link:technical/pack-format.html[the pack format documentation] for
-further details.
+See linkgit:gitformat-bundle[5] for more details and the discussion of
+"thin pack" in linkgit:gitformat-pack[5] for further details.
OPTIONS
-------
@@ -77,7 +75,7 @@ verify <file>::
commits exist and are fully linked in the current repository.
Then, 'git bundle' prints a list of missing commits, if any.
Finally, information about additional capabilities, such as "object
- filter", is printed. See "Capabilities" in link:technical/bundle-format.html
+ filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5]
for more information. The exit code is zero for success, but will
be nonzero if the bundle file is invalid.
@@ -337,6 +335,11 @@ You can also see what references it offers:
$ git ls-remote mybundle
----------------
+FILE FORMAT
+-----------
+
+See linkgit:gitformat-bundle[5].
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9f37e22..4cb9d55 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -600,6 +600,13 @@ $ edit frotz
$ git add frotz
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-switch[1],
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 78dcc91..1e8ac9d 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -156,10 +156,7 @@ effect to your index in a row.
Pass the merge strategy-specific option through to the
merge strategy. See linkgit:git-merge[1] for details.
---rerere-autoupdate::
---no-rerere-autoupdate::
- Allow the rerere mechanism to update the index with the
- result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
SEQUENCER SUBCOMMANDS
---------------------
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index a7f309d..160d08b 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]
DESCRIPTION
-----------
@@ -20,16 +20,16 @@ Normally, only files unknown to Git are removed, but if the `-x`
option is specified, ignored files are also removed. This can, for
example, be useful to remove all build products.
-If any optional `<path>...` arguments are given, only those paths
-are affected.
+If any optional `<pathspec>...` arguments are given, only those paths
+that match the pathspec are affected.
OPTIONS
-------
-d::
- Normally, when no <path> is specified, git clean will not
+ Normally, when no <pathspec> is specified, git clean will not
recurse into untracked directories to avoid removing too much.
Specify -d to have it recurse into such directories as well.
- If any paths are specified, -d is irrelevant; all untracked
+ If a <pathspec> is specified, -d is irrelevant; all untracked
files matching the specified paths (with exceptions for nested
git directories mentioned under `--force`) will be removed.
@@ -133,6 +133,13 @@ help::
Show brief usage of interactive git-clean.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clean.txt[]
+
SEE ALSO
--------
linkgit:gitignore[5]
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 632bd13..d6434d2 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -323,6 +323,13 @@ or `--mirror` is given)
for `host.xz:foo/.git`). Cloning into an existing directory
is only allowed if the directory is empty.
+--bundle-uri=<uri>::
+ Before fetching from the remote, fetch a bundle from the given
+ `<uri>` and unbundle the data into the local repository. The refs
+ in the bundle will be stored under the hidden `refs/bundle/*`
+ namespace. This option is incompatible with `--depth`,
+ `--shallow-since`, and `--shallow-exclude`.
+
:git-clone: 1
include::urls.txt[]
@@ -363,6 +370,15 @@ $ cd my-linux
$ git clone --bare -l /home/proj/.git /pub/scm/proj.git
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/init.txt[]
+
+include::config/clone.txt[]
+
GIT
---
diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt
index 6cea9ab..1843164 100644
--- a/Documentation/git-column.txt
+++ b/Documentation/git-column.txt
@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7
v2.4.8 v2.4.9
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/column.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index e1f48c9..c8dbceb 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -10,7 +10,10 @@ SYNOPSIS
--------
[verse]
'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]
-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]
+'git commit-graph write' [--object-dir <dir>] [--append]
+ [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
+ [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+ <split options>
DESCRIPTION
@@ -142,6 +145,18 @@ $ git show-ref -s | git commit-graph write --stdin-commits
$ git rev-parse HEAD | git commit-graph write --stdin-commits --append
------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/commitgraph.txt[]
+
+
+FILE FORMAT
+-----------
+
+see linkgit:gitformat-commit-graph[5].
GIT
---
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 6c60bf9..225c6c9 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the
`VISUAL` environment variable, or the `EDITOR` environment variable (in that
order). See linkgit:git-var[1] for details.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/commit.txt[]
+
HOOKS
-----
This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,
diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
index 01e1c21..650a15a 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.txt
@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
SYNOPSIS
--------
[verse]
-'git credential-cache{litdd}daemon' [--debug] <socket>
+'git credential-cache{litdd}daemon' [--debug] <socket-path>
DESCRIPTION
-----------
@@ -16,7 +16,7 @@ DESCRIPTION
NOTE: You probably don't want to invoke this command yourself; it is
started automatically when you use linkgit:git-credential-cache[1].
-This command listens on the Unix domain socket specified by `<socket>`
+This command listens on the Unix domain socket specified by `<socket-path>`
for `git-credential-cache` clients. Clients may store and retrieve
credentials. Each credential is held for a timeout specified by the
client; once no credentials are held, the daemon exits.
diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt
index 0216c18..432e159 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -69,10 +69,10 @@ $ git push http://example.com/repo.git
------------------------------------
You can provide options via the credential.helper configuration
-variable (this example drops the cache time to 5 minutes):
+variable (this example increases the cache time to 1 hour):
-------------------------------------------------------
-$ git config credential.helper 'cache --timeout=300'
+$ git config credential.helper 'cache --timeout=3600'
-------------------------------------------------------
GIT
diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index f186730..ac2818b 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -160,6 +160,8 @@ empty string.
Components which are missing from the URL (e.g., there is no
username in the example above) will be left unset.
+Unrecognised attributes are silently discarded.
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-diagnose.txt b/Documentation/git-diagnose.txt
new file mode 100644
index 0000000..3ec8cc7
--- /dev/null
+++ b/Documentation/git-diagnose.txt
@@ -0,0 +1,65 @@
+git-diagnose(1)
+================
+
+NAME
+----
+git-diagnose - Generate a zip archive of diagnostic information
+
+SYNOPSIS
+--------
+[verse]
+'git diagnose' [(-o | --output-directory) <path>] [(-s | --suffix) <format>]
+ [--mode=<mode>]
+
+DESCRIPTION
+-----------
+Collects detailed information about the user's machine, Git client, and
+repository state and packages that information into a zip archive. The
+generated archive can then, for example, be shared with the Git mailing list to
+help debug an issue or serve as a reference for independent debugging.
+
+By default, the following information is captured in the archive:
+
+ * 'git version --build-options'
+ * The path to the repository root
+ * The available disk space on the filesystem
+ * The name and size of each packfile, including those in alternate object
+ stores
+ * The total count of loose objects, as well as counts broken down by
+ `.git/objects` subdirectory
+
+Additional information can be collected by selecting a different diagnostic mode
+using the `--mode` option.
+
+This tool differs from linkgit:git-bugreport[1] in that it collects much more
+detailed information with a greater focus on reporting the size and data shape
+of repository contents.
+
+OPTIONS
+-------
+-o <path>::
+--output-directory <path>::
+ Place the resulting diagnostics archive in `<path>` instead of the
+ current directory.
+
+-s <format>::
+--suffix <format>::
+ Specify an alternate suffix for the diagnostics archive name, to create
+ a file named 'git-diagnostics-<formatted suffix>'. This should take the
+ form of a strftime(3) format string; the current local time will be
+ used.
+
+--mode=(stats|all)::
+ Specify the type of diagnostics that should be collected. The default behavior
+ of 'git diagnose' is equivalent to `--mode=stats`.
++
+The `--mode=all` option collects everything included in `--mode=stats`, as well
+as copies of `.git`, `.git/hooks`, `.git/info`, `.git/logs`, and
+`.git/objects/info` directories. This additional information may be sensitive,
+as it can be used to reconstruct the full contents of the diagnosed repository.
+Users should exercise caution when sharing an archive generated with
+`--mode=all`.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index bf1febb..591e380 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index
SYNOPSIS
--------
[verse]
-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 6236c75..52b6792 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -79,10 +79,10 @@ If --merge-base is given, use the merge base of the two commits for the
This form is to view the results of a merge commit. The first
listed <commit> must be the merge itself; the remaining two or
- more commits should be its parents. A convenient way to produce
- the desired set of revisions is to use the `^@` suffix.
- For instance, if `master` names a merge commit, `git diff master
- master^@` gives the same combined diff as `git show master`.
+ more commits should be its parents. Convenient ways to produce
+ the desired set of revisions are to use the suffixes `^@` and
+ `^!`. If A is a merge commit, then `git diff A A^@`,
+ `git diff A^!` and `git show A` all give the same combined diff.
'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
@@ -213,6 +213,13 @@ $ git diff -R <2>
rewrites (very expensive).
<2> Output diff in reverse.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/diff.txt[]
+
SEE ALSO
--------
diff(1),
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 143b0c4..9d14c3c 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.
See linkgit:git-diff[1] for the full list of supported options.
-CONFIG VARIABLES
-----------------
+CONFIGURATION
+-------------
'git difftool' falls back to 'git mergetool' config variables when the
difftool equivalents have not been defined.
-diff.tool::
- The default diff tool to use.
+include::includes/cmd-config-section-rest.txt[]
-diff.guitool::
- The default diff tool to use when `--gui` is specified.
-
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
-
-difftool.<tool>.cmd::
- Specify the command to invoke the specified diff tool.
-+
-See the `--tool=<tool>` option above for more details.
-
-difftool.prompt::
- Prompt before each invocation of the diff tool.
-
-difftool.trustExitCode::
- Exit difftool if the invoked diff tool returns a non-zero exit status.
-+
-See the `--trust-exit-code` option above for more details.
+include::config/difftool.txt[]
SEE ALSO
--------
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 1978dbd..4643ddb 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -9,7 +9,7 @@ git-fast-export - Git data exporter
SYNOPSIS
--------
[verse]
-'git fast-export [<options>]' | 'git fast-import'
+'git fast-export' [<options>] | 'git fast-import'
DESCRIPTION
-----------
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 39cfa05..8b5dd6a 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an
import in progress, at the cost of some added running time and worse
compression.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fastimport.txt[]
+
SEE ALSO
--------
linkgit:git-fast-export[1]
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index e9d3646..63d9569 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -285,6 +285,13 @@ linkgit:git-gc[1]).
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fetch.txt[]
+
BUGS
----
Using --recurse-submodules can only fetch new commits in submodules that are
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index be797d7..dfcc7da 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -275,6 +275,17 @@ header). Note also that `git send-email` already handles this
transformation for you, and this option should not be used if you are
feeding the result to `git send-email`.
+--[no-]force-in-body-from::
+ With the e-mail sender specified via the `--from` option, by
+ default, an in-body "From:" to identify the real author of
+ the commit is added at the top of the commit log message if
+ the sender is different from the author. With this option,
+ the in-body "From:" is added even when the sender and the
+ author have the same name and address, which may help if the
+ mailing list software mangles the sender's identity.
+ Defaults to the value of the `format.forceInBodyFrom`
+ configuration variable.
+
--add-header=<header>::
Add an arbitrary header to the email headers. This is in addition
to any configured headers, and may be used multiple times.
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 5088783..b6a0f8a 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -107,6 +107,8 @@ care about this output and want to speed it up further.
CONFIGURATION
-------------
+include::includes/cmd-config-section-all.txt[]
+
include::config/fsck.txt[]
DISCUSSION
@@ -150,6 +152,18 @@ hash mismatch <object>::
object database value.
This indicates a serious data integrity problem.
+
+FSCK MESSAGES
+-------------
+
+The following lists the types of errors `git fsck` detects and what
+each error means, with their default severity. The severity of the
+error, other than those that are marked as "(FATAL)", can be tweaked
+by setting the corresponding `fsck.<msg-id>` configuration variable.
+
+include::fsck-msgids.txt[]
+
+
Environment Variables
---------------------
diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt
index cc142fb..8238ead 100644
--- a/Documentation/git-fsmonitor--daemon.txt
+++ b/Documentation/git-fsmonitor--daemon.txt
@@ -3,7 +3,7 @@ git-fsmonitor{litdd}daemon(1)
NAME
----
-git-fsmonitor--daemon - A Built-in File System Monitor
+git-fsmonitor--daemon - A Built-in Filesystem Monitor
SYNOPSIS
--------
@@ -17,7 +17,7 @@ DESCRIPTION
-----------
A daemon to watch the working directory for file and directory
-changes using platform-specific file system notification facilities.
+changes using platform-specific filesystem notification facilities.
This daemon communicates directly with commands like `git status`
using the link:technical/api-simple-ipc.html[simple IPC] interface
@@ -63,13 +63,44 @@ CAVEATS
-------
The fsmonitor daemon does not currently know about submodules and does
-not know to filter out file system events that happen within a
+not know to filter out filesystem events that happen within a
submodule. If fsmonitor daemon is watching a super repo and a file is
modified within the working directory of a submodule, it will report
the change (as happening against the super repo). However, the client
will properly ignore these extra events, so performance may be affected
but it will not cause an incorrect result.
+By default, the fsmonitor daemon refuses to work against network-mounted
+repositories; this may be overridden by setting `fsmonitor.allowRemote` to
+`true`. Note, however, that the fsmonitor daemon is not guaranteed to work
+correctly with all network-mounted repositories and such use is considered
+experimental.
+
+On Mac OS, the inter-process communication (IPC) between various Git
+commands and the fsmonitor daemon is done via a Unix domain socket (UDS) -- a
+special type of file -- which is supported by native Mac OS filesystems,
+but not on network-mounted filesystems, NTFS, or FAT32. Other filesystems
+may or may not have the needed support; the fsmonitor daemon is not guaranteed
+to work with these filesystems and such use is considered experimental.
+
+By default, the socket is created in the `.git` directory, however, if the
+`.git` directory is on a network-mounted filesystem, it will be instead be
+created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a
+network-mounted filesystem in which case you must set the configuration
+variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native
+filesystem in which to create the socket file.
+
+If none of the above directories (`.git`, `$HOME`, or `fsmonitor.socketDir`)
+is on a native Mac OS file filesystem the fsmonitor daemon will report an
+error that will cause the daemon and the currently running command to exit.
+
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fsmonitor--daemon.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 0af7540..a65c9aa 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -110,8 +110,7 @@ users and their repositories.
CONFIGURATION
-------------
-The below documentation is the same as what's found in
-linkgit:git-config[1]:
+include::includes/cmd-config-section-all.txt[]
include::config/gc.txt[]
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 58d944b..dabdbe8 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -343,34 +343,9 @@ performance in this case, it might be desirable to use `--threads=1`.
CONFIGURATION
-------------
-grep.lineNumber::
- If set to true, enable `-n` option by default.
-
-grep.column::
- If set to true, enable the `--column` option by default.
-
-grep.patternType::
- Set the default matching behavior. Using a value of 'basic', 'extended',
- 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
- `--fixed-strings`, or `--perl-regexp` option accordingly, while the
- value 'default' will return to the default matching behavior.
-
-grep.extendedRegexp::
- If set to true, enable `--extended-regexp` option by default. This
- option is ignored when the `grep.patternType` option is set to a value
- other than 'default'.
-
-grep.threads::
- Number of grep worker threads to use. If unset (or set to 0), Git will
- use as many threads as the number of logical cores available.
-
-grep.fullName::
- If set to true, enable `--full-name` option by default.
-
-grep.fallbackToNoIndex::
- If set to true, fall back to git grep --no-index if git grep
- is executed outside of a git repository. Defaults to false.
+include::includes/cmd-config-section-all.txt[]
+include::config/grep.txt[]
GIT
---
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index df9e2c5..472b5bb 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]
+ [--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
DESCRIPTION
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 239c68d..2b0b5e3 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -9,14 +9,16 @@ SYNOPSIS
--------
[verse]
'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
-'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
+'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
'git help' [-g|--guides]
'git help' [-c|--config]
+'git help' [--user-interfaces]
+'git help' [--developer-interfaces]
DESCRIPTION
-----------
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no '<command>' or '<doc>' given, the synopsis of the 'git'
command and a list of the most commonly used Git commands are printed
on the standard output.
@@ -26,8 +28,8 @@ printed on the standard output.
If the option `--guides` or `-g` is given, a list of the
Git concept guides is also printed on the standard output.
-If a command, or a guide, is given, a manual page for that command or
-guide is brought up. The 'man' program is used by default for this
+If a command or other documentation is given, the relevant manual page
+will be brought up. The 'man' program is used by default for this
purpose, but this can be overridden by other options or configuration
variables.
@@ -69,6 +71,23 @@ OPTIONS
--guides::
Prints a list of the Git concept guides on the standard output.
+--user-interfaces::
+ Prints a list of the repository, command and file interfaces
+ documentation on the standard output.
++
+In-repository file interfaces such as `.git/info/exclude` are
+documented here (see linkgit:gitrepository-layout[5]), as well as
+in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).
++
+This section of the documentation also covers general or widespread
+user-interface conventions (e.g. linkgit:gitcli[7]), and
+pseudo-configuration such as the file-based `.git/hooks/*` interface
+described in linkgit:githooks[5].
+
+--developer-interfaces::
+ Print list of file formats, protocols and other developer
+ interfaces documentation on the standard output.
+
-i::
--info::
Display manual page for the command in the 'info' format. The
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 63cf498..f7b1851 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -54,6 +54,8 @@ CONFIGURATION
To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set
to appropriate values.
+include::includes/cmd-config-section-rest.txt[]
+
include::config/imap.txt[]
EXAMPLES
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index ad921fe..160dea1 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -169,6 +169,13 @@ $ git commit <3>
<2> Add all existing files to the index.
<3> Record the pristine state as the first commit in the history.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/init.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 956a01d..22ff3a6 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages
SYNOPSIS
--------
[verse]
-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]
-'git interpret-trailers' [<options>] [--parse] [<file>...]
+'git interpret-trailers' [--in-place] [--trim-empty]
+ [(--trailer <token>[(=|:)<value>])...]
+ [--parse] [<file>...]
DESCRIPTION
-----------
@@ -60,10 +61,12 @@ non-whitespace lines before a line that starts with '---' (followed by a
space or the end of the line). Such three minus signs start the patch
part of the message. See also `--no-divider` below.
-When reading trailers, there can be whitespaces after the
-token, the separator and the value. There can also be whitespaces
-inside the token and the value. The value may be split over multiple lines with
-each subsequent line starting with whitespace, like the "folding" in RFC 822.
+When reading trailers, there can be no whitespace before or inside the
+token, but any number of regular space and tab characters are allowed
+between the token and the separator. There can be whitespaces before,
+inside or after the value. The value may be split over multiple lines
+with each subsequent line starting with at least one whitespace, like
+the "folding" in RFC 822.
Note that 'trailers' do not follow and are not intended to follow many
rules for RFC 822 headers. For example they do not follow
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 20e87ce..2a66cf8 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -45,13 +45,23 @@ OPTIONS
--decorate-refs=<pattern>::
--decorate-refs-exclude=<pattern>::
- If no `--decorate-refs` is given, pretend as if all refs were
- included. For each candidate, do not use it for decoration if it
+ For each candidate reference, do not use it for decoration if it
matches any patterns given to `--decorate-refs-exclude` or if it
doesn't match any of the patterns given to `--decorate-refs`. The
`log.excludeDecoration` config option allows excluding refs from
the decorations, but an explicit `--decorate-refs` pattern will
override a match in `log.excludeDecoration`.
++
+If none of these options or config settings are given, then references are
+used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`,
+`refs/stash/`, or `refs/tags/`.
+
+--clear-decorations::
+ When specified, this option clears all previous `--decorate-refs`
+ or `--decorate-refs-exclude` options and relaxes the default
+ decoration filter to include all references. This option is
+ assumed if the config value `log.initialDecorationSet` is set to
+ `all`.
--source::
Print out the ref name given on the command line by which each
@@ -199,47 +209,11 @@ i18n.logOutputEncoding::
Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
otherwise.
-log.date::
- Default format for human-readable dates. (Compare the
- `--date` option.) Defaults to "default", which means to write
- dates like `Sat May 8 19:35:34 2010 -0500`.
-+
-If the format is set to "auto:foo" and the pager is in use, format
-"foo" will be the used for the date format. Otherwise "default" will
-be used.
-
-log.follow::
- If `true`, `git log` will act as if the `--follow` option was used when
- a single <path> is given. This has the same limitations as `--follow`,
- i.e. it cannot be used to follow multiple files and does not work well
- on non-linear history.
-
-log.showRoot::
- If `false`, `git log` and related commands will not treat the
- initial commit as a big creation event. Any root commits in
- `git log -p` output would be shown without a diff attached.
- The default is `true`.
-
-log.showSignature::
- If `true`, `git log` and related commands will act as if the
- `--show-signature` option was passed to them.
-
-mailmap.*::
- See linkgit:git-shortlog[1].
-
-notes.displayRef::
- Which refs, in addition to the default set by `core.notesRef`
- or `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the `log` family of commands. See
- linkgit:git-notes[1].
-+
-May be an unabbreviated ref name or a glob and may be specified
-multiple times. A warning will be issued for refs that do not exist,
-but a glob that does not match any refs is silently ignored.
-+
-This setting can be disabled by the `--no-notes` option,
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
-and overridden by the `--notes=<ref>` option.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/log.txt[]
+
+include::config/notes.txt[]
GIT
---
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index d798641..440043c 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -10,8 +10,8 @@ SYNOPSIS
--------
[verse]
'git ls-files' [-z] [-t] [-v] [-f]
- [-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored]
- [-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified]
+ [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
+ [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
[--directory [--no-empty-directory]] [--eol]
[--deduplicate]
[-x <pattern>|--exclude=<pattern>]
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 3fcfd96..2806028 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.
<patch>::
The patch extracted from e-mail.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/mailinfo.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index e56bad2..805e5a2 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git maintenance' run [<options>]
'git maintenance' start [--scheduler=<scheduler>]
-'git maintenance' (stop|register|unregister)
+'git maintenance' (stop|register|unregister) [<options>]
DESCRIPTION
@@ -50,13 +50,13 @@ stop::
the background maintenance is restarted later.
register::
- Initialize Git config values so any scheduled maintenance will
- start running on this repository. This adds the repository to the
- `maintenance.repo` config variable in the current user's global
- config and enables some recommended configuration values for
- `maintenance.<task>.schedule`. The tasks that are enabled are safe
- for running in the background without disrupting foreground
- processes.
+ Initialize Git config values so any scheduled maintenance will start
+ running on this repository. This adds the repository to the
+ `maintenance.repo` config variable in the current user's global config,
+ or the config specified by --config-file option, and enables some
+ recommended configuration values for `maintenance.<task>.schedule`. The
+ tasks that are enabled are safe for running in the background without
+ disrupting foreground processes.
+
The `register` subcommand will also set the `maintenance.strategy` config
value to `incremental`, if this value is not previously set. The
@@ -79,6 +79,10 @@ unregister::
Remove the current repository from background maintenance. This
only removes the repository from the configured list. It does not
stop the background maintenance processes from running.
++
+The `unregister` subcommand will report an error if the current repository
+is not already registered. Use the `--force` option to return success even
+when the current repository is not registered.
TASKS
-----
@@ -397,6 +401,13 @@ 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.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/maintenance.txt[]
+
GIT
---
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 2d944e0..b01ba3d 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
--------
[verse]
-'git merge-base' [-a|--all] <commit> <commit>...
-'git merge-base' [-a|--all] --octopus <commit>...
+'git merge-base' [-a | --all] <commit> <commit>...
+'git merge-base' [-a | --all] --octopus <commit>...
'git merge-base' --is-ancestor <commit> <commit>
'git merge-base' --independent <commit>...
'git merge-base' --fork-point <ref> [<commit>]
diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
index d6c3567..04bcc41 100644
--- a/Documentation/git-merge-tree.txt
+++ b/Documentation/git-merge-tree.txt
@@ -81,6 +81,31 @@ Whereas for a conflicted merge, the output is by default of the form:
These are discussed individually below.
+However, there is an exception. If `--stdin` is passed, then there is
+an extra section at the beginning, a NUL character at the end, and then
+all the sections repeat for each line of input. Thus, if the first merge
+is conflicted and the second is clean, the output would be of the form:
+
+ <Merge status>
+ <OID of toplevel tree>
+ <Conflicted file info>
+ <Informational messages>
+ NUL
+ <Merge status>
+ <OID of toplevel tree>
+ NUL
+
+[[MS]]
+Merge status
+~~~~~~~~~~~~
+
+This is an integer status followed by a NUL character. The integer status is:
+
+ 0: merge had conflicts
+ 1: merge was clean
+ &lt;0: something prevented the merge from running (e.g. access to repository
+ objects denied by filesystem)
+
[[OIDTLT]]
OID of toplevel tree
~~~~~~~~~~~~~~~~~~~~
@@ -108,18 +133,50 @@ character instead of a newline character.
Informational messages
~~~~~~~~~~~~~~~~~~~~~~
-This always starts with a blank line (or NUL if `-z` is passed) to
-separate it from the previous sections, and then has free-form
-messages about the merge, such as:
+This section provides informational messages, typically about
+conflicts. The format of the section varies significantly depending
+on whether `-z` is passed.
+
+If `-z` is passed:
+
+The output format is zero or more conflict informational records, each
+of the form:
+
+ <list-of-paths><conflict-type>NUL<conflict-message>NUL
+
+where <list-of-paths> is of the form
+
+ <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL
+
+and includes paths (or branch names) affected by the conflict or
+informational message in <conflict-message>. Also, <conflict-type> is a
+stable string explaining the type of conflict, such as
+
+ * "Auto-merging"
+ * "CONFLICT (rename/delete)"
+ * "CONFLICT (submodule lacks merge base)"
+ * "CONFLICT (binary)"
+
+and <conflict-message> is a more detailed message about the conflict which often
+(but not always) embeds the <stable-short-type-description> within it. These
+strings may change in future Git versions. Some examples:
* "Auto-merging <file>"
* "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..."
- * "Failed to merge submodule <submodule> (<reason>)"
+ * "Failed to merge submodule <submodule> (no merge base)"
* "Warning: cannot merge binary files: <filename>"
-Note that these free-form messages will never have a NUL character
-in or between them, even if -z is passed. It is simply a large block
-of text taking up the remainder of the output.
+If `-z` is NOT passed:
+
+This section starts with a blank line to separate it from the previous
+sections, and then only contains the <conflict-message> information
+from the previous section (separated by newlines). These are
+non-stable strings that should not be parsed by scripts, and are just
+meant for human consumption. Also, note that while <conflict-message>
+strings usually do not contain embedded newlines, they sometimes do.
+(However, the free-form messages will never have an embedded NUL
+character). So, the entire block of information is meant for human
+readers as an agglomeration of all conflict messages.
EXIT STATUS
-----------
@@ -127,7 +184,10 @@ EXIT STATUS
For a successful, non-conflicted merge, the exit status is 0. When the
merge has conflicts, the exit status is 1. If the merge is not able to
complete (or start) due to some kind of error, the exit status is
-something other than 0 or 1 (and the output is unspecified).
+something other than 0 or 1 (and the output is unspecified). When
+--stdin is passed, the return status is 0 for both successful and
+conflicted merges, and something other than 0 or 1 if it cannot complete
+all the requested merges.
USAGE NOTES
-----------
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 3125473..2d6a139 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -90,10 +90,7 @@ invocations. The automated message can include the branch description.
If `--log` is specified, a shortlog of the commits being merged
will be appended to the specified message.
---rerere-autoupdate::
---no-rerere-autoupdate::
- Allow the rerere mechanism to update the index with the
- result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
--overwrite-ignore::
--no-overwrite-ignore::
@@ -386,13 +383,16 @@ include::merge-strategies.txt[]
CONFIGURATION
-------------
-include::config/merge.txt[]
branch.<name>.mergeOptions::
Sets default options for merging into branch <name>. The syntax and
supported options are the same as those of 'git merge', but option
values containing whitespace characters are currently not supported.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/merge.txt[]
+
SEE ALSO
--------
linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index f784027..c44e205 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -102,6 +102,9 @@ success of the resolution after the custom tool has exited.
CONFIGURATION
-------------
:git-mergetool: 1
+
+include::includes/cmd-config-section-all.txt[]
+
include::config/mergetool.txt[]
TEMPORARY FILES
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
index c588fb9..3696506 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.txt
@@ -70,9 +70,10 @@ verify::
Verify the contents of the MIDX file.
expire::
- Delete the pack-files that are tracked by the MIDX file, but
- have no objects referenced by the MIDX. Rewrite the MIDX file
- afterward to remove all references to these pack-files.
+ Delete the pack-files that are tracked by the MIDX file, but
+ have no objects referenced by the MIDX (with the exception of
+ `.keep` packs and cruft packs). Rewrite the MIDX file afterward
+ to remove all references to these pack-files.
repack::
Create a new pack-file containing objects in small pack-files
@@ -128,8 +129,8 @@ $ git multi-pack-index verify
SEE ALSO
--------
See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
-Document] and link:technical/pack-format.html[The Multi-Pack-Index
-Format] for more information on the multi-pack-index feature.
+Document] and linkgit:gitformat-pack[5] for more information on the
+multi-pack-index feature and its file format.
GIT
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 79449bf..fb0220f 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' <options>... <args>...
+'git mv' [<options>] <source>... <destination>
DESCRIPTION
-----------
@@ -30,7 +30,7 @@ OPTIONS
-------
-f::
--force::
- Force renaming or moving of a file even if the target exists
+ Force renaming or moving of a file even if the <destination> exists.
-k::
Skip move or rename actions which would lead to an error
condition. An error happens when a source is neither existing nor
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a42006..efbc10f 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
after a three dash separator line.
To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
+"notes.displayRef" discussion in <<CONFIGURATION>>.
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write
some special-purpose tools to do something useful with them.
+[[CONFIGURATION]]
CONFIGURATION
-------------
@@ -316,57 +317,9 @@ core.notesRef::
This setting can be overridden through the environment and
command line.
-notes.mergeStrategy::
- Which merge strategy to choose by default when resolving notes
- conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
- `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
- section above for more information on each strategy.
-+
-This setting can be overridden by passing the `--strategy` option.
-
-notes.<name>.mergeStrategy::
- Which merge strategy to choose when doing a notes merge into
- refs/notes/<name>. This overrides the more general
- "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
- for more information on each available strategy.
-
-notes.displayRef::
- Which ref (or refs, if a glob or specified more than once), in
- addition to the default set by `core.notesRef` or
- `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the 'git log' family of commands.
- This setting can be overridden on the command line or by the
- `GIT_NOTES_DISPLAY_REF` environment variable.
- See linkgit:git-log[1].
-
-notes.rewrite.<command>::
- When rewriting commits with <command> (currently `amend` or
- `rebase`), if this variable is `false`, git will not copy
- notes from the original to the rewritten commit. Defaults to
- `true`. See also "`notes.rewriteRef`" below.
-+
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
-environment variable.
+include::includes/cmd-config-section-rest.txt[]
-notes.rewriteMode::
- When copying notes during a rewrite, what to do if the target
- commit already has a note. Must be one of `overwrite`,
- `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
- `concatenate`.
-+
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
-environment variable.
-
-notes.rewriteRef::
- When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. May be a glob,
- in which case notes in all matching refs will be copied. You
- may also specify this configuration several times.
-+
-Does not have a default value; you must configure this variable to
-enable note rewriting.
-+
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+include::config/notes.txt[]
ENVIRONMENT
diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt
index ee7034b..99ef138 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.txt
@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
SYNOPSIS
--------
[verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)
DESCRIPTION
-----------
@@ -34,7 +34,7 @@ OPTIONS
--alt-odb::
Don't require objects present in packs from alternate object
- directories to be present in local packs.
+ database (odb) directories to be present in local packs.
--verbose::
Outputs some statistics to stderr. Has a small performance penalty.
diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
index 442caff..1d15fa4 100644
--- a/Documentation/git-patch-id.txt
+++ b/Documentation/git-patch-id.txt
@@ -8,18 +8,18 @@ git-patch-id - Compute unique ID for a patch
SYNOPSIS
--------
[verse]
-'git patch-id' [--stable | --unstable]
+'git patch-id' [--stable | --unstable | --verbatim]
DESCRIPTION
-----------
Read a patch from the standard input and compute the patch ID for it.
A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a
-patch, with whitespace and line numbers ignored. As such, it's "reasonably
-stable", but at the same time also reasonably unique, i.e., two patches that
-have the same "patch ID" are almost guaranteed to be the same thing.
+patch, with line numbers ignored. As such, it's "reasonably stable", but at
+the same time also reasonably unique, i.e., two patches that have the same
+"patch ID" are almost guaranteed to be the same thing.
-IOW, you can use this thing to look for likely duplicate commits.
+The main usecase for this command is to look for likely duplicate commits.
When dealing with 'git diff-tree' output, it takes advantage of
the fact that the patch is prefixed with the object name of the
@@ -30,6 +30,12 @@ This can be used to make a mapping from patch ID to commit ID.
OPTIONS
-------
+--verbatim::
+ Calculate the patch-id of the input as it is given, do not strip
+ any whitespace.
+
+ This is the default if patchid.verbatim is true.
+
--stable::
Use a "stable" sum of hashes as the patch ID. With this option:
- Reordering file diffs that make up a patch does not affect the ID.
@@ -45,14 +51,16 @@ OPTIONS
of "-O<orderfile>", thereby making existing databases storing such
"unstable" or historical patch-ids unusable.
+ - All whitespace within the patch is ignored and does not affect the id.
+
This is the default if patchid.stable is set to true.
--unstable::
Use an "unstable" hash as the patch ID. With this option,
the result produced is compatible with the patch-id value produced
- by git 1.9 and older. Users with pre-existing databases storing
- patch-ids produced by git 1.9 and older (who do not deal with reordered
- patches) may want to use this option.
+ by git 1.9 and older and whitespace is ignored. Users with pre-existing
+ databases storing patch-ids produced by git 1.9 and older (who do not deal
+ with reordered patches) may want to use this option.
This is the default.
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 9fed59a..844d6f8 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files
SYNOPSIS
--------
[verse]
-'git prune-packed' [-n|--dry-run] [-q|--quiet]
+'git prune-packed' [-n | --dry-run] [-q | --quiet]
DESCRIPTION
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 2f25aa3..5bb1d5a 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -409,10 +409,14 @@ Specifying `--no-force-if-includes` disables this behavior.
all submodules that changed in the revisions to be pushed will be
pushed. If on-demand was not able to push all necessary revisions it will
also be aborted and exit with non-zero status. If 'only' is used all
- submodules will be recursively pushed while the superproject is left
+ submodules will be pushed while the superproject is left
unpushed. A value of 'no' or using `--no-recurse-submodules` can be used
to override the push.recurseSubmodules configuration variable when no
submodule recursion is required.
++
+When using 'on-demand' or 'only', if a submodule has a
+"push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration,
+further recursion will occur. In this case, "only" is treated as "on-demand".
--[no-]verify::
Toggle the pre-push hook (see linkgit:githooks[5]). The
@@ -692,6 +696,13 @@ a `git gc` command on the origin repository.
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/push.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index fe350d7..0b39371 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.txt
@@ -12,6 +12,7 @@ SYNOPSIS
[--no-dual-color] [--creation-factor=<factor>]
[--left-only | --right-only]
( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> )
+ [[--] <path>...]
DESCRIPTION
-----------
@@ -19,6 +20,9 @@ DESCRIPTION
This command shows the differences between two versions of a patch
series, or more generally, two commit ranges (ignoring merge commits).
+In the presence of `<path>` arguments, these commit ranges are limited
+accordingly.
+
To that end, it first finds pairs of commits from both commit ranges
that correspond with each other. Two commits are said to correspond when
the diff between their patches (i.e. the author information, the commit
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index b9bfdc0..7567955 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index
SYNOPSIS
--------
[verse]
-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 080658c..f9675bd 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -218,12 +218,14 @@ leave out at most one of A and B, in which case it defaults to HEAD.
merge base of `<upstream>` and `<branch>`. Running
`git rebase --keep-base <upstream> <branch>` is equivalent to
running
- `git rebase --onto <upstream>...<branch> <upstream> <branch>`.
+ `git rebase --reapply-cherry-picks --no-fork-point --onto <upstream>...<branch> <upstream> <branch>`.
+
This option is useful in the case where one is developing a feature on
top of an upstream branch. While the feature is being worked on, the
upstream branch may advance and it may not be the best idea to keep
-rebasing on top of the upstream but to keep the base commit as-is.
+rebasing on top of the upstream but to keep the base commit as-is. As
+the base commit is unchanged this option implies `--reapply-cherry-picks`
+to avoid losing commits.
+
Although both this option and `--fork-point` find the merge base between
`<upstream>` and `<branch>`, this option uses the merge base as the _starting
@@ -278,7 +280,8 @@ See also INCOMPATIBLE OPTIONS below.
Note that commits which start empty are kept (unless `--no-keep-empty`
is specified), and commits which are clean cherry-picks (as determined
by `git log --cherry-mark ...`) are detected and dropped as a
-preliminary step (unless `--reapply-cherry-picks` is passed).
+preliminary step (unless `--reapply-cherry-picks` or `--keep-base` is
+passed).
+
See also INCOMPATIBLE OPTIONS below.
@@ -311,13 +314,16 @@ See also INCOMPATIBLE OPTIONS below.
upstream changes, the behavior towards them is controlled by
the `--empty` flag.)
+
-By default (or if `--no-reapply-cherry-picks` is given), these commits
-will be automatically dropped. Because this necessitates reading all
-upstream commits, this can be expensive in repos with a large number
-of upstream commits that need to be read. When using the 'merge'
-backend, warnings will be issued for each dropped commit (unless
-`--quiet` is given). Advice will also be issued unless
-`advice.skippedCherryPicks` is set to false (see linkgit:git-config[1]).
+
+In the absence of `--keep-base` (or if `--no-reapply-cherry-picks` is
+given), these commits will be automatically dropped. Because this
+necessitates reading all upstream commits, this can be expensive in
+repositories with a large number of upstream commits that need to be
+read. When using the 'merge' backend, warnings will be issued for each
+dropped commit (unless `--quiet` is given). Advice will also be issued
+unless `advice.skippedCherryPicks` is set to false (see
+linkgit:git-config[1]).
+
+
`--reapply-cherry-picks` allows rebase to forgo reading all upstream
commits, potentially improving performance.
@@ -376,10 +382,7 @@ See also INCOMPATIBLE OPTIONS below.
+
See also INCOMPATIBLE OPTIONS below.
---rerere-autoupdate::
---no-rerere-autoupdate::
- Allow the rerere mechanism to update the index with the
- result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
-S[<keyid>]::
--gpg-sign[=<keyid>]::
@@ -446,9 +449,9 @@ When `--fork-point` is active, 'fork_point' will be used instead of
<branch>` command (see linkgit:git-merge-base[1]). If 'fork_point'
ends up being empty, the `<upstream>` will be used as a fallback.
+
-If `<upstream>` is given on the command line, then the default is
-`--no-fork-point`, otherwise the default is `--fork-point`. See also
-`rebase.forkpoint` in linkgit:git-config[1].
+If `<upstream>` or `--keep-base` is given on the command line, then
+the default is `--no-fork-point`, otherwise the default is
+`--fork-point`. See also `rebase.forkpoint` in linkgit:git-config[1].
+
If your branch was based on `<upstream>` but `<upstream>` was rewound and
your branch contains commits which were dropped, this option can be used
@@ -1262,6 +1265,8 @@ merge cmake
CONFIGURATION
-------------
+include::includes/cmd-config-section-all.txt[]
+
include::config/rebase.txt[]
include::config/sequencer.txt[]
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 014a784..65ff518 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <directory>
+'git receive-pack' <git-dir>
DESCRIPTION
-----------
@@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1].
OPTIONS
-------
-<directory>::
+<git-dir>::
The repository to sync into.
--http-backend-info-refs::
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 5ced7ad..ec64cbf 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -9,22 +9,18 @@ git-reflog - Manage reflog information
SYNOPSIS
--------
[verse]
-'git reflog' <subcommand> <options>
-
-DESCRIPTION
------------
-The command takes various subcommands, and different options
-depending on the subcommand:
-
-[verse]
-'git reflog' ['show'] [<log-options>] [<ref>]
+'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
[--rewrite] [--updateref] [--stale-fix]
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
'git reflog delete' [--rewrite] [--updateref]
- [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}...
+ [--dry-run | -n] [--verbose] <ref>@{<specifier>}...
'git reflog exists' <ref>
+DESCRIPTION
+-----------
+This command manages the information recorded in the reflogs.
+
Reference logs, or "reflogs", record when the tips of branches and
other references were updated in the local repository. Reflogs are
useful in various Git commands, to specify the old value of a
@@ -33,7 +29,8 @@ moves ago", `master@{one.week.ago}` means "where master used to point
to one week ago in this local repository", and so on. See
linkgit:gitrevisions[7] for more details.
-This command manages the information recorded in the reflogs.
+The command takes various subcommands, and different options
+depending on the subcommand:
The "show" subcommand (which is also the default, in the absence of
any subcommands) shows the log of the reference provided in the
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 0bf1389..4017157 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -74,6 +74,12 @@ to the new separate pack will be written.
immediately instead of waiting for the next `git gc` invocation.
Only useful with `--cruft -d`.
+--expire-to=<dir>::
+ Write a cruft pack containing pruned objects (if any) to the
+ directory `<dir>`. This option is useful for keeping a copy of
+ any pruned objects in a separate directory as a backup. Only
+ useful with `--cruft -d`.
+
-l::
Pass the `--local` option to 'git pack-objects'. See
linkgit:git-pack-objects[1].
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4cfc883..992b469 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]
DESCRIPTION
-----------
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 20bb8e8..51029a2 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order
SYNOPSIS
--------
[verse]
-'git rev-list' [<options>] <commit>... [[--] <path>...]
+'git rev-list' [<options>] <commit>... [--] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 6b8ca08..bcd8069 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -197,6 +197,13 @@ respectively, and they must begin with `refs/` when applied to `--glob`
or `--all`. If a trailing '/{asterisk}' is intended, it must be given
explicitly.
+--exclude-hidden=[receive|uploadpack]::
+ Do not include refs that would be hidden by `git-receive-pack` or
+ `git-upload-pack` by consulting the appropriate `receive.hideRefs` or
+ `uploadpack.hideRefs` configuration along with `transfer.hideRefs` (see
+ linkgit:git-config[1]). This option affects the next pseudo-ref option
+ `--all` or `--glob` and is cleared after processing them.
+
--disambiguate=<prefix>::
Show every object whose name begins with the given prefix.
The <prefix> must be at least 4 hexadecimal digits long to
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 8463fe9..d2e10d3 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -8,7 +8,7 @@ git-revert - Revert some existing commits
SYNOPSIS
--------
[verse]
-'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...
+'git revert' [--[no-]edit] [-n] [-m <parent-number>] [-s] [-S[<keyid>]] <commit>...
'git revert' (--continue | --skip | --abort | --quit)
DESCRIPTION
@@ -112,10 +112,7 @@ effect to your index in a row.
Pass the merge strategy-specific option through to the
merge strategy. See linkgit:git-merge[1] for details.
---rerere-autoupdate::
---no-rerere-autoupdate::
- Allow the rerere mechanism to update the index with the
- result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
--reference::
Instead of starting the body of the log message with "This
@@ -145,6 +142,13 @@ EXAMPLES
changes. The revert only modifies the working tree and the
index.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/revert.txt[]
+
SEE ALSO
--------
linkgit:git-cherry-pick[1]
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 41cd8cb..765b2df 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -178,9 +178,18 @@ Sending
for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
--smtp-encryption=<encryption>::
- Specify the encryption to use, either 'ssl' or 'tls'. Any other
- value reverts to plain SMTP. Default is the value of
- `sendemail.smtpEncryption`.
+ Specify in what way encrypting begins for the SMTP connection.
+ Valid values are 'ssl' and 'tls'. Any other value reverts to plain
+ (unencrypted) SMTP, which defaults to port 25.
+ Despite the names, both values will use the same newer version of TLS,
+ but for historic reasons have these names. 'ssl' refers to "implicit"
+ encryption (sometimes called SMTPS), that uses port 465 by default.
+ 'tls' refers to "explicit" encryption (often known as STARTTLS),
+ that uses port 25 by default. Other ports might be used by the SMTP
+ server, which are not the default. Commonly found alternative port for
+ 'tls' and unencrypted is 587. You need to check your provider's
+ documentation or your server configuration to make sure
+ for your own case. Default is the value of `sendemail.smtpEncryption`.
--smtp-domain=<FQDN>::
Specifies the Fully Qualified Domain Name (FQDN) used in the
@@ -456,41 +465,9 @@ Information
CONFIGURATION
-------------
-sendemail.aliasesFile::
- To avoid typing long email addresses, point this to one or more
- email aliases files. You must also supply `sendemail.aliasFileType`.
+include::includes/cmd-config-section-all.txt[]
-sendemail.aliasFileType::
- Format of the file(s) specified in sendemail.aliasesFile. Must be
- one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
-+
-What an alias file in each format looks like can be found in
-the documentation of the email program of the same name. The
-differences and limitations from the standard formats are
-described below:
-+
---
-sendmail;;
-* Quoted aliases and quoted addresses are not supported: lines that
- contain a `"` symbol are ignored.
-* Redirection to a file (`/path/name`) or pipe (`|command`) is not
- supported.
-* File inclusion (`:include: /path/name`) is not supported.
-* Warnings are printed on the standard error output for any
- explicitly unsupported constructs, and any other lines that are not
- recognized by the parser.
---
-
-sendemail.multiEdit::
- If true (default), a single editor instance will be spawned to edit
- files you have to edit (patches when `--annotate` is used, and the
- summary when `--compose` is used). If false, files will be edited one
- after the other, spawning a new editor each time.
-
-sendemail.confirm::
- Sets the default for whether to confirm before sending. Must be
- one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
- in the previous section for the meaning of these values.
+include::config/sendemail.txt[]
EXAMPLES
--------
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index be41f11..595b002 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -9,9 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository
SYNOPSIS
--------
[verse]
-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+'git send-pack' [--mirror] [--dry-run] [--force]
+ [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
- [--[no-]signed|--signed=(true|false|if-asked)]
+ [--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
DESCRIPTION
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index f64e770..7d0277d 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -47,6 +47,11 @@ OPTIONS
Each pretty-printed commit will be rewrapped before it is shown.
+--date=<format>::
+ Show dates formatted according to the given date string. (See
+ the `--date` option in the "Commit Formatting" section of
+ linkgit:git-log[1]). Useful with `--group=format:<format>`.
+
--group=<type>::
Group commits based on `<type>`. If no `--group` option is
specified, the default is `author`. `<type>` is one of:
@@ -59,6 +64,9 @@ OPTIONS
example, if your project uses `Reviewed-by` trailers, you might want
to see who has been reviewing with
`git shortlog -ns --group=trailer:reviewed-by`.
+ - `format:<format>`, any string accepted by the `--format` option of
+ 'git log'. (See the "PRETTY FORMATS" section of
+ linkgit:git-log[1].)
+
Note that commits that do not include the trailer will not be counted.
Likewise, commits with multiple trailers (e.g., multiple signoffs) may
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 5cc2fce..71f608b 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits
SYNOPSIS
--------
[verse]
-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]
+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
[(<rev> | <glob>)...]
-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]
DESCRIPTION
-----------
@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.
Without `--list`, the output also shows how these tips are
topologically related with each other.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/showbranch.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index ab4d271..d1d56f6 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository
SYNOPSIS
--------
[verse]
-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]
- [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]
+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]
+ [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
[--heads] [--] [<pattern>...]
'git show-ref' --exclude-existing[=<pattern>]
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 3776705..68392d2 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout <subcommand> [<options>]'
+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]
DESCRIPTION
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 6e15f47..f4bb611 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -9,17 +9,20 @@ SYNOPSIS
--------
[verse]
'git stash' list [<log-options>]
-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]
-'git stash' drop [-q|--quiet] [<stash>]
-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+'git stash' drop [-q | --quiet] [<stash>]
+'git stash' pop [--index] [-q | --quiet] [<stash>]
+'git stash' apply [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [-m|--message <message>]
+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [<message>]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
DESCRIPTION
-----------
@@ -47,7 +50,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
COMMANDS
--------
-push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
+push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
Save your local modifications to a new 'stash entry' and roll them
back to HEAD (in the working tree and in the index).
@@ -382,6 +385,13 @@ grep commit | cut -d\ -f3 |
xargs git log --merges --no-walk --grep=WIP
----------------------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/stash.txt[]
+
SEE ALSO
--------
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 54a4b29..5e438a7 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -9,7 +9,7 @@ git-status - Show the working tree status
SYNOPSIS
--------
[verse]
-'git status' [<options>...] [--] [<pathspec>...]
+'git status' [<options>] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index bbcbdce..c60fc9c 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -265,6 +265,13 @@ always create a new name for it (without switching away):
$ git switch -c good-surprises
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-checkout[1],
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt
index ef68ad2..102c83e 100644
--- a/Documentation/git-symbolic-ref.txt
+++ b/Documentation/git-symbolic-ref.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'git symbolic-ref' [-m <reason>] <name> <ref>
-'git symbolic-ref' [-q] [--short] <name>
+'git symbolic-ref' [-q] [--short] [--no-recurse] <name>
'git symbolic-ref' --delete [-q] <name>
DESCRIPTION
@@ -46,6 +46,15 @@ OPTIONS
When showing the value of <name> as a symbolic ref, try to shorten the
value, e.g. from `refs/heads/master` to `master`.
+--recurse::
+--no-recurse::
+ When showing the value of <name> as a symbolic ref, if
+ <name> refers to another symbolic ref, follow such a chain
+ of symbolic refs until the result no longer points at a
+ symbolic ref (`--recurse`, which is the default).
+ `--no-recurse` stops after dereferencing only a single level
+ of symbolic ref.
+
-m::
Update the reflog for <name> with <reason>. This is valid only
when creating or updating a symbolic ref.
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 31a97a1..fdc72b5 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
SYNOPSIS
--------
[verse]
-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
@@ -26,19 +26,19 @@ to delete, list or verify tags.
Unless `-f` is given, the named tag must not yet exist.
-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
+If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
creates a 'tag' object, and requires a tag message. Unless
`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
in the tag message.
-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
are absent, `-a` is implied.
Otherwise, a tag reference that points directly at the given object
(i.e., a lightweight tag) is created.
A GnuPG signed tag object will be created when `-s` or `-u
-<keyid>` is used. When `-u <keyid>` is not used, the
+<key-id>` is used. When `-u <key-id>` is not used, the
committer identity for the current user is used to find the
GnuPG key for signing. The configuration variable `gpg.program`
is used to specify custom GnuPG binary.
@@ -72,8 +72,8 @@ OPTIONS
Override `tag.gpgSign` configuration variable that is
set to force each and every tag to be signed.
--u <keyid>::
---local-user=<keyid>::
+-u <key-id>::
+--local-user=<key-id>::
Make a GPG-signed tag, using the given key.
-f::
@@ -164,14 +164,14 @@ This option is only applicable when listing tags without annotation lines.
Use the given tag message (instead of prompting).
If multiple `-m` options are given, their values are
concatenated as separate paragraphs.
- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
-F <file>::
--file=<file>::
Take the tag message from the given file. Use '-' to
read the message from the standard input.
- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
-e::
@@ -220,7 +220,7 @@ it in the repository configuration as follows:
-------------------------------------
[user]
- signingKey = <gpg-keyid>
+ signingKey = <gpg-key_id>
-------------------------------------
`pager.tag` is only respected when listing tags, i.e., when `-l` is
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 5ea2f2c..f4bb9c5 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -420,7 +420,7 @@ as `switch`, `pull`, `merge`) will avoid writing these files.
However, these commands will sometimes write these files anyway in
important cases such as conflicts during a merge or rebase. Git
commands will also avoid treating the lack of such files as an
-intentional deletion; for example `git add -u` will not not stage a
+intentional deletion; for example `git add -u` will not stage a
deletion for these files and `git commit -a` will not make a commit
deleting them either.
diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
index 969bb2e..17e429d 100644
--- a/Documentation/git-update-server-info.txt
+++ b/Documentation/git-update-server-info.txt
@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers
SYNOPSIS
--------
[verse]
-'git update-server-info'
+'git update-server-info' [-f | --force]
DESCRIPTION
-----------
@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover
what references and packs the server has. This command
generates such auxiliary files.
+OPTIONS
+-------
+-f::
+--force::
+ update the info files from scratch.
+
OUTPUT
------
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
index fba0f1c..e8eb10b 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.txt
@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive
SYNOPSIS
--------
[verse]
-'git upload-archive' <directory>
+'git upload-archive' <repository>
DESCRIPTION
-----------
@@ -54,7 +54,7 @@ access via non-smart-http.
OPTIONS
-------
-<directory>::
+<repository>::
The repository to get a tar archive from.
GIT
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 8f87b23..b656b47 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -39,10 +39,9 @@ OPTIONS
--http-backend-info-refs::
Used by linkgit:git-http-backend[1] to serve up
`$GIT_URL/info/refs?service=git-upload-pack` requests. See
- "Smart Clients" in link:technical/http-protocol.html[the HTTP
- transfer protocols] documentation and "HTTP Transport" in
- link:technical/protocol-v2.html[the Git Wire Protocol, Version
- 2] documentation. Also understood by
+ "Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP
+ Transport" in the linkgit:gitprotocol-v2[5]
+ documentation. Also understood by
linkgit:git-receive-pack[1].
<directory>::
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 387cc1b..6aa521f 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -9,7 +9,7 @@ git-var - Show a Git logical variable
SYNOPSIS
--------
[verse]
-'git var' ( -l | <variable> )
+'git var' (-l | <variable>)
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt
index 92097f6..aee4c40 100644
--- a/Documentation/git-verify-commit.txt
+++ b/Documentation/git-verify-commit.txt
@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits
SYNOPSIS
--------
[verse]
-'git verify-commit' <commit>...
+'git verify-commit' [-v | --verbose] [--raw] <commit>...
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index 61ca6d0..b8720dc 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files
SYNOPSIS
--------
[verse]
-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...
+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
DESCRIPTION
diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt
index 0b8075d..81d50ec 100644
--- a/Documentation/git-verify-tag.txt
+++ b/Documentation/git-verify-tag.txt
@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags
SYNOPSIS
--------
[verse]
-'git verify-tag' [--format=<format>] <tag>...
+'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
DESCRIPTION
-----------
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index ada30c8..063d6ee 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees
SYNOPSIS
--------
[verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+ [-b <new-branch>] <path> [<commit-ish>]
'git worktree list' [-v | --porcelain [-z]]
'git worktree lock' [--reason <string>] <worktree>
'git worktree move' <worktree> <new-path>
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 47a6095..1d33e08 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -339,6 +339,23 @@ The following documentation pages are guides about Git concepts.
include::cmds-guide.txt[]
+Repository, command and file interfaces
+---------------------------------------
+
+This documentation discusses repository and command interfaces which
+users are expected to interact with directly. See `--user-formats` in
+linkgit:git-help[1] for more details on the criteria.
+
+include::cmds-userinterfaces.txt[]
+
+File formats, protocols and other developer interfaces
+------------------------------------------------------
+
+This documentation discusses file formats, over-the-wire protocols and
+other git developer interfaces. See `--developer-interfaces` in
+linkgit:git-help[1].
+
+include::cmds-developerinterfaces.txt[]
Configuration Mechanism
-----------------------
@@ -441,7 +458,12 @@ Please see linkgit:gitglossary[7].
Environment Variables
---------------------
-Various Git commands use the following environment variables:
+Various Git commands pay attention to environment variables and change
+their behavior. The environment variables marked as "Boolean" take
+their values the same way as Boolean valued configuration variables, e.g.
+"true", "yes", "on" and positive numbers are taken as "yes".
+
+Here are the variables:
The Git Repository
~~~~~~~~~~~~~~~~~~
@@ -450,13 +472,13 @@ is worth noting that they may be used/overridden by SCMS sitting above
Git so take care if using a foreign front-end.
`GIT_INDEX_FILE`::
- This environment allows the specification of an alternate
+ This environment variable specifies an alternate
index file. If not specified, the default of `$GIT_DIR/index`
is used.
`GIT_INDEX_VERSION`::
- This environment variable allows the specification of an index
- version for new repositories. It won't affect existing index
+ This environment variable specifies what index version is used
+ when writing the index file out. It won't affect existing index
files. By default index file version 2 or 3 is used. See
linkgit:git-update-index[1] for more information.
@@ -513,7 +535,7 @@ double-quotes and respecting backslash escapes. E.g., the value
When run in a directory that does not have ".git" repository
directory, Git tries to find such a directory in the parent
directories to find the top of the working tree, but by default it
- does not cross filesystem boundaries. This environment variable
+ does not cross filesystem boundaries. This Boolean environment variable
can be set to true to tell Git not to stop at filesystem
boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
an explicit repository directory set via `GIT_DIR` or on the
@@ -665,6 +687,11 @@ for further details.
plink or tortoiseplink. This variable overrides the config setting
`ssh.variant` that serves the same purpose.
+`GIT_SSL_NO_VERIFY`::
+ Setting and exporting this environment variable to any value
+ tells Git not to verify the SSL certificate when fetching or
+ pushing over HTTPS.
+
`GIT_ASKPASS`::
If this environment variable is set, then Git commands which need to
acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
@@ -673,7 +700,7 @@ for further details.
option in linkgit:git-config[1].
`GIT_TERMINAL_PROMPT`::
- If this environment variable is set to `0`, git will not prompt
+ If this Boolean environment variable is set to false, git will not prompt
on the terminal (e.g., when asking for HTTP authentication).
`GIT_CONFIG_GLOBAL`::
@@ -688,13 +715,14 @@ for further details.
`GIT_CONFIG_NOSYSTEM`::
Whether to skip reading settings from the system-wide
- `$(prefix)/etc/gitconfig` file. This environment variable can
+ `$(prefix)/etc/gitconfig` file. This Boolean environment variable can
be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
predictable environment for a picky script, or you can set it
- temporarily to avoid using a buggy `/etc/gitconfig` file while
+ to true to temporarily avoid using a buggy `/etc/gitconfig` file while
waiting for someone with sufficient permissions to fix it.
`GIT_FLUSH`::
+// NEEDSWORK: make it into a usual Boolean environment variable
If this environment variable is set to "1", then commands such
as 'git blame' (in incremental mode), 'git rev-list', 'git log',
'git check-attr' and 'git check-ignore' will
@@ -835,11 +863,11 @@ for full details.
`GIT_TRACE_REDACT`::
By default, when tracing is activated, Git redacts the values of
cookies, the "Authorization:" header, the "Proxy-Authorization:"
- header and packfile URIs. Set this variable to `0` to prevent this
+ header and packfile URIs. Set this Boolean environment variable to false to prevent this
redaction.
`GIT_LITERAL_PATHSPECS`::
- Setting this variable to `1` will cause Git to treat all
+ Setting this Boolean environment variable to true will cause Git to treat all
pathspecs literally, rather than as glob patterns. For example,
running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
for commits that touch the path `*.c`, not any paths that the
@@ -848,15 +876,15 @@ for full details.
`git ls-tree`, `--raw` diff output, etc).
`GIT_GLOB_PATHSPECS`::
- Setting this variable to `1` will cause Git to treat all
+ Setting this Boolean environment variable to true will cause Git to treat all
pathspecs as glob patterns (aka "glob" magic).
`GIT_NOGLOB_PATHSPECS`::
- Setting this variable to `1` will cause Git to treat all
+ Setting this Boolean environment variable to true will cause Git to treat all
pathspecs as literal (aka "literal" magic).
`GIT_ICASE_PATHSPECS`::
- Setting this variable to `1` will cause Git to treat all
+ Setting this Boolean environment variable to true will cause Git to treat all
pathspecs as case-insensitive.
`GIT_REFLOG_ACTION`::
@@ -870,7 +898,7 @@ for full details.
end user, to be recorded in the body of the reflog.
`GIT_REF_PARANOIA`::
- If set to `0`, ignore broken or badly named refs when iterating
+ If this Boolean environment variable is set to false, ignore broken or badly named refs when iterating
over lists of refs. Normally Git will try to include any such
refs, which may cause some operations to fail. This is usually
preferable, as potentially destructive operations (e.g.,
@@ -889,7 +917,7 @@ for full details.
`protocol.allow` in linkgit:git-config[1] for more details.
`GIT_PROTOCOL_FROM_USER`::
- Set to 0 to prevent protocols used by fetch/push/clone which are
+ Set this Boolean environment variable to false to prevent protocols used by fetch/push/clone which are
configured to the `user` state. This is useful to restrict recursive
submodule initialization from an untrusted repository or for programs
which feed potentially-untrusted URLS to git commands. See
@@ -917,7 +945,7 @@ only affects clones and fetches; it is not yet used for pushes (but may
be in the future).
`GIT_OPTIONAL_LOCKS`::
- If set to `0`, Git will complete any requested operation without
+ If this Boolean environment variable is set to false, Git will complete any requested operation without
performing any optional sub-operations that require taking a lock.
For example, this will prevent `git status` from refreshing the
index as a side effect. This is useful for processes running in
diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 80517b4..4522471 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -17,9 +17,10 @@ DESCRIPTION
Git will sometimes need credentials from the user in order to perform
operations; for example, it may need to ask for a username and password
-in order to access a remote repository over HTTP. This manual describes
-the mechanisms Git uses to request these credentials, as well as some
-features to avoid inputting these credentials repeatedly.
+in order to access a remote repository over HTTP. Some remotes accept
+a personal access token or OAuth access token as a password. This
+manual describes the mechanisms Git uses to request these credentials,
+as well as some features to avoid inputting these credentials repeatedly.
REQUESTING CREDENTIALS
----------------------
@@ -61,7 +62,9 @@ for a password. It is generally configured by adding this to your config:
Credential helpers, on the other hand, are external programs from which Git can
request both usernames and passwords; they typically interface with secure
-storage provided by the OS or other programs.
+storage provided by the OS or other programs. Alternatively, a
+credential-generating helper might generate credentials for certain servers via
+some API.
To use a helper, you must first select one to use. Git currently
includes the following helpers:
@@ -269,6 +272,7 @@ stdout in the same format (see linkgit:git-credential[1] for common
attributes). A helper is free to produce a subset, or even no values at
all if it has nothing useful to provide. Any provided attributes will
overwrite those already known about by Git's credential subsystem.
+Unrecognised attributes are silently discarded.
While it is possible to override all attributes, well behaving helpers
should refrain from doing so for any attribute other than username and
@@ -286,8 +290,8 @@ For a `store` or `erase` operation, the helper's output is ignored.
If a helper fails to perform the requested operation or needs to notify
the user of a potential issue, it may write to stderr.
-If it does not support the requested operation (e.g., a read-only store),
-it should silently ignore the request.
+If it does not support the requested operation (e.g., a read-only store
+or generator), it should silently ignore the request.
If a helper receives any other operation, it should silently ignore the
request. This leaves room for future operations to be added (older
diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt
index b9be864..00e0a20 100644
--- a/Documentation/technical/bundle-format.txt
+++ b/Documentation/gitformat-bundle.txt
@@ -1,11 +1,33 @@
-= Git bundle v2 format
+gitformat-bundle(5)
+===================
-The Git bundle format is a format that represents both refs and Git objects.
+NAME
+----
+gitformat-bundle - The bundle file format
+
+
+SYNOPSIS
+--------
+[verse]
+*.bundle
+*.bdl
+
+DESCRIPTION
+-----------
+
+The Git bundle format is a format that represents both refs and Git
+objects. A bundle is a header in a format similar to
+linkgit:git-show-ref[1] followed by a pack in *.pack format.
-== Format
+The format is created and read by the linkgit:git-bundle[1] command,
+and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
+
+
+FORMAT
+------
We will use ABNF notation to define the Git bundle format. See
-protocol-common.txt for the details.
+linkgit:gitprotocol-common[5] for the details.
A v2 bundle looks like this:
@@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)
pack = ... ; packfile
----
-== Semantics
+
+SEMANTICS
+---------
A Git bundle consists of several parts.
@@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
This is a comment and it has no specific meaning. The writer of the bundle MAY
put any string here. The reader of the bundle MUST ignore the comment.
-=== Note on the shallow clone and a Git bundle
+Note on the shallow clone and a Git bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that the prerequisites does not represent a shallow-clone boundary. The
semantics of the prerequisites and the shallow-clone boundaries are different,
and the Git bundle v2 format cannot represent a shallow clone repository.
-== Capabilities
+CAPABILITIES
+------------
Because there is no opportunity for negotiation, unknown capabilities cause 'git
bundle' to abort.
@@ -79,3 +105,7 @@ bundle' to abort.
* `filter` specifies an object filter as in the `--filter` option in
linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
`.promisor` pack-file after it is unbundled.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt
index 593614f..57202ed 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -1,12 +1,25 @@
-Chunk-based file formats
-========================
+gitformat-chunk(5)
+==================
+
+NAME
+----
+gitformat-chunk - Chunk-based file formats
+
+SYNOPSIS
+--------
+
+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
+the pack format documentation in linkgit:gitformat-pack[5]).
+
+DESCRIPTION
+-----------
Some file formats in Git use a common concept of "chunks" to describe
sections of the file. This allows structured access to a large file by
scanning a small "table of contents" for the remaining data. This common
format is used by the `commit-graph` and `multi-pack-index` files. See
-link:technical/pack-format.html[the `multi-pack-index` format] and
-link:technical/commit-graph-format.html[the `commit-graph` format] for
+the `multi-pack-index` format in linkgit:gitformat-pack[5] and
+the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
how they use the chunks to describe structured data.
A chunk-based file format begins with some header information custom to
@@ -108,9 +121,13 @@ for future formats:
* *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()`
in `commit-graph.c` for how the chunk-format API is used to write and
parse the commit-graph file format documented in
- link:technical/commit-graph-format.html[the commit-graph file format].
+ the commit-graph file format in linkgit:gitformat-commit-graph[5].
* *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
in `midx.c` for how the chunk-format API is used to write and
parse the multi-pack-index file format documented in
- link:technical/pack-format.html[the multi-pack-index file format].
+ the multi-pack-index file format section of linkgit:gitformat-pack[5].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt
index 484b185..31cad58 100644
--- a/Documentation/technical/commit-graph-format.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -1,7 +1,20 @@
-Git commit graph format
-=======================
+gitformat-commit-graph(5)
+=========================
-The Git commit graph stores a list of commit OIDs and some associated
+NAME
+----
+gitformat-commit-graph - Git commit-graph format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/info/commit-graph
+$GIT_DIR/objects/info/commit-graphs/*
+
+DESCRIPTION
+-----------
+
+The Git commit-graph stores a list of commit OIDs and some associated
metadata, including:
- The generation number of the commit.
@@ -21,7 +34,7 @@ corresponding to the array position within the list of commit OIDs. Due
to some special constants we use to track parents, we can store at most
(1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits.
-== Commit graph files have the following format:
+== Commit-graph files have the following format:
In order to allow extensions that add extra data to the graph, we organize
the body into "chunks" and provide a binary lookup table at the beginning
@@ -30,7 +43,7 @@ and hash type.
All multi-byte numbers are in network byte order.
-HEADER:
+=== HEADER:
4-byte signature:
The signature is: {'C', 'G', 'P', 'H'}
@@ -52,7 +65,7 @@ HEADER:
We infer the length (H*B) of the Base Graphs chunk
from this value.
-CHUNK LOOKUP:
+=== CHUNK LOOKUP:
(C + 1) * 12 bytes listing the table of contents for the chunks:
First 4 bytes describe the chunk id. Value 0 is a terminating label.
@@ -62,23 +75,23 @@ CHUNK LOOKUP:
ID appears at most once.
The CHUNK LOOKUP matches the table of contents from
- link:technical/chunk-format.html[the chunk-based file format].
+ the chunk-based file format, see linkgit:gitformat-chunk[5]
The remaining data in the body is described one chunk at a time, and
these chunks may be given in any order. Chunks are required unless
otherwise specified.
-CHUNK DATA:
+=== CHUNK DATA:
- OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
+==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
The ith entry, F[i], stores the number of OIDs with first
byte at most i. Thus F[255] stores the total
number of commits (N).
- OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
+==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
The OIDs for all commits in the graph, sorted in ascending order.
- Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
+==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
* The first H bytes are for the OID of the root tree.
* The next 8 bytes are for the positions of the first two parents
of the ith commit. Stores value 0x70000000 if no parent in that
@@ -93,7 +106,7 @@ CHUNK DATA:
2 bits of the lowest byte, storing the 33rd and 34th bit of the
commit time.
- Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
+==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional]
* This list of 4-byte values store corrected commit date offsets for the
commits, arranged in the same order as commit data chunk.
* If the corrected commit date offset cannot be stored within 31 bits,
@@ -104,7 +117,7 @@ CHUNK DATA:
by compatible versions of Git and in case of split commit-graph chains,
the topmost layer also has Generation Data chunk.
- Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
+==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional]
* This list of 8-byte values stores the corrected commit date offsets
for commits with corrected commit date offsets that cannot be
stored within 31 bits.
@@ -112,7 +125,7 @@ CHUNK DATA:
chunk is present and atleast one corrected commit date offset cannot
be stored within 31 bits.
- Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
+==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
This list of 4-byte values store the second through nth parents for
all octopus merges. The second parent value in the commit data stores
an array position within this list along with the most-significant bit
@@ -120,14 +133,14 @@ CHUNK DATA:
positions for the parents until reaching a value with the most-significant
bit on. The other bits correspond to the position of the last parent.
- Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
+==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional]
* The ith entry, BIDX[i], stores the number of bytes in all Bloom filters
from commit 0 to commit i (inclusive) in lexicographic order. The Bloom
filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header
length), where BIDX[-1] is 0.
* The BIDX chunk is ignored if the BDAT chunk is not present.
- Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
+==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional]
* It starts with header consisting of three unsigned 32-bit integers:
- Version of the hash algorithm being used. We currently only support
value 1 which corresponds to the 32-bit version of the murmur3 hash
@@ -147,13 +160,13 @@ CHUNK DATA:
of length one, with either all bits set to zero or one respectively.
* The BDAT chunk is present if and only if BIDX is present.
- Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
+==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional]
This list of H-byte hashes describe a set of B commit-graph files that
form a commit-graph chain. The graph position for the ith commit in this
file's OID Lookup chunk is equal to i plus the number of commits in all
base graphs. If B is non-zero, this chunk must exist.
-TRAILER:
+=== TRAILER:
H-byte HASH-checksum of all of the above.
@@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote
possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By
changing the IDs, newer versions of Git will silently ignore those older
chunks and write the new information without trusting the incorrect data.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt
index f691c20..015cb21 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/gitformat-index.txt
@@ -1,5 +1,19 @@
+gitformat-index(5)
+==================
+
+NAME
+----
+gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/index
+
+DESCRIPTION
+-----------
+
Git index format
-================
== The Git index file has the following format
@@ -125,7 +139,7 @@ Git index format
entry is encoded as if the path name for the previous entry is an
empty string). At the beginning of an entry, an integer N in the
variable width encoding (the same encoding as the offset is encoded
- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed
+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
by a NUL-terminated string S. Removing N bytes from the end of the
path name for the previous entry, and replacing it with the string S
yields the path name for this entry.
@@ -402,3 +416,7 @@ The remaining data of each directory block is grouped by type:
with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
tools should avoid interacting with a sparse index unless they understand
this extension.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt
index b520aa9..e06af02 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/gitformat-pack.txt
@@ -1,5 +1,30 @@
-Git pack format
-===============
+gitformat-pack(5)
+=================
+
+NAME
+----
+gitformat-pack - Git pack format
+
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/pack-*.{pack,idx}
+$GIT_DIR/objects/pack/pack-*.rev
+$GIT_DIR/objects/pack/pack-*.mtimes
+$GIT_DIR/objects/pack/multi-pack-index
+
+DESCRIPTION
+-----------
+
+The Git pack format is now Git stores most of its primary repository
+data. Over the lietime af a repository loose objects (if any) and
+smaller packs are consolidated into larger pack(s). See
+linkgit:git-gc[1] and linkgit:git-pack-objects[1].
+
+The pack format is also used over-the-wire, see
+e.g. linkgit:gitprotocol-v2[5], as well as being a part of
+other container formats in the case of linkgit:gitformat-bundle[5].
== Checksums and object IDs
@@ -356,7 +381,7 @@ CHUNK LOOKUP:
using the next chunk position if necessary.)
The CHUNK LOOKUP matches the table of contents from
- link:technical/chunk-format.html[the chunk-based file format].
+ the chunk-based file format, see linkgit:gitformat-chunk[5].
The remaining data in the body is described one chunk at a time, and
these chunks may be given in any order. Chunks are required unless
@@ -482,3 +507,132 @@ packs arranged in MIDX order (with the preferred pack coming first).
The MIDX's reverse index is stored in the optional 'RIDX' chunk within
the MIDX itself.
+
+== cruft packs
+
+The cruft packs feature offer an alternative to Git's traditional mechanism of
+removing unreachable objects. This document provides an overview of Git's
+pruning mechanism, and how a cruft pack can be used instead to accomplish the
+same.
+
+=== Background
+
+To remove unreachable objects from your repository, Git offers `git repack -Ad`
+(see linkgit:git-repack[1]). Quoting from the documentation:
+
+----
+[...] unreachable objects in a previous pack become loose, unpacked objects,
+instead of being left in the old pack. [...] loose unreachable objects will be
+pruned according to normal expiry rules with the next 'git gc' invocation.
+----
+
+Unreachable objects aren't removed immediately, since doing so could race with
+an incoming push which may reference an object which is about to be deleted.
+Instead, those unreachable objects are stored as loose objects and stay that way
+until they are older than the expiration window, at which point they are removed
+by linkgit:git-prune[1].
+
+Git must store these unreachable objects loose in order to keep track of their
+per-object mtimes. If these unreachable objects were written into one big pack,
+then either freshening that pack (because an object contained within it was
+re-written) or creating a new pack of unreachable objects would cause the pack's
+mtime to get updated, and the objects within it would never leave the expiration
+window. Instead, objects are stored loose in order to keep track of the
+individual object mtimes and avoid a situation where all cruft objects are
+freshened at once.
+
+This can lead to undesirable situations when a repository contains many
+unreachable objects which have not yet left the grace period. Having large
+directories in the shards of `.git/objects` can lead to decreased performance in
+the repository. But given enough unreachable objects, this can lead to inode
+starvation and degrade the performance of the whole system. Since we
+can never pack those objects, these repositories often take up a large amount of
+disk space, since we can only zlib compress them, but not store them in delta
+chains.
+
+=== Cruft packs
+
+A cruft pack eliminates the need for storing unreachable objects in a loose
+state by including the per-object mtimes in a separate file alongside a single
+pack containing all loose objects.
+
+A cruft pack is written by `git repack --cruft` when generating a new pack.
+linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`
+is a classic all-into-one repack, meaning that everything in the resulting pack is
+reachable, and everything else is unreachable. Once written, the `--cruft`
+option instructs `git repack` to generate another pack containing only objects
+not packed in the previous step (which equates to packing all unreachable
+objects together). This progresses as follows:
+
+ 1. Enumerate every object, marking any object which is (a) not contained in a
+ kept-pack, and (b) whose mtime is within the grace period as a traversal
+ tip.
+
+ 2. Perform a reachability traversal based on the tips gathered in the previous
+ step, adding every object along the way to the pack.
+
+ 3. Write the pack out, along with a `.mtimes` file that records the per-object
+ timestamps.
+
+This mode is invoked internally by linkgit:git-repack[1] when instructed to
+write a cruft pack. Crucially, the set of in-core kept packs is exactly the set
+of packs which will not be deleted by the repack; in other words, they contain
+all of the repository's reachable objects.
+
+When a repository already has a cruft pack, `git repack --cruft` typically only
+adds objects to it. An exception to this is when `git repack` is given the
+`--cruft-expiration` option, which allows the generated cruft pack to omit
+expired objects instead of waiting for linkgit:git-gc[1] to expire those objects
+later on.
+
+It is linkgit:git-gc[1] that is typically responsible for removing expired
+unreachable objects.
+
+=== Caution for mixed-version environments
+
+Repositories that have cruft packs in them will continue to work with any older
+version of Git. Note, however, that previous versions of Git which do not
+understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
+all of the objects in it. In other words, do not expect older (pre-cruft pack)
+versions of Git to interpret or even read the contents of the `.mtimes` file.
+
+Note that having mixed versions of Git GC-ing the same repository can lead to
+unreachable objects never being completely pruned. This can happen under the
+following circumstances:
+
+ - An older version of Git running GC explodes the contents of an existing
+ cruft pack loose, using the cruft pack's mtime.
+ - A newer version running GC collects those loose objects into a cruft pack,
+ where the .mtime file reflects the loose object's actual mtimes, but the
+ cruft pack mtime is "now".
+
+Repeating this process will lead to unreachable objects not getting pruned as a
+result of repeatedly resetting the objects' mtimes to the present time.
+
+If you are GC-ing repositories in a mixed version environment, consider omitting
+the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
+leaving the `gc.cruftPacks` configuration unset until all writers understand
+cruft packs.
+
+=== Alternatives
+
+Notable alternatives to this design include:
+
+ - The location of the per-object mtime data, and
+ - Storing unreachable objects in multiple cruft packs.
+
+On the location of mtime data, a new auxiliary file tied to the pack was chosen
+to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
+support for optional chunks of data, it may make sense to consolidate the
+`.mtimes` format into the `.idx` itself.
+
+Storing unreachable objects among multiple cruft packs (e.g., creating a new
+cruft pack during each repacking operation including only unreachable objects
+which aren't already stored in an earlier cruft pack) is significantly more
+complicated to construct, and so aren't pursued here. The obvious drawback to
+the current implementation is that the entire cruft pack must be re-written from
+scratch.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt
index 166721b..a249869 100644
--- a/Documentation/technical/signature-format.txt
+++ b/Documentation/gitformat-signature.txt
@@ -1,7 +1,18 @@
-Git signature format
-====================
+gitformat-signature(5)
+======================
-== Overview
+NAME
+----
+gitformat-signature - Git cryptographic signature formats
+
+SYNOPSIS
+--------
+[verse]
+<[tag|commit] object header(s)>
+<over-the-wire protocol>
+
+DESCRIPTION
+-----------
Git uses cryptographic signatures in various places, currently objects (tags,
commits, mergetags) and transactions (pushes). In every case, the command which
@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt
index 9dfade9..0fb5ea0 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/gitprotocol-capabilities.txt
@@ -1,8 +1,20 @@
-Git Protocol Capabilities
-=========================
+gitprotocol-capabilities(5)
+===========================
+
+NAME
+----
+gitprotocol-capabilities - Protocol v0 and v1 capabilities
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
NOTE: this document describes capabilities for versions 0 and 1 of the pack
-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
+protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]
doc.
Servers SHOULD support all capabilities defined in this document.
@@ -77,7 +89,7 @@ interleaved with S-R-Q.
multi_ack_detailed
------------------
This is an extension of multi_ack that permits client to better
-understand the server's in-memory state. See pack-protocol.txt,
+understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
section "Packfile Negotiation" for more information.
no-done
@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests
this capability, after unpacking and updating references the server
will respond with whether the packfile unpacked successfully and if
each reference was updated successfully. If any of those were not
-successful, it will send back an error message. See pack-protocol.txt
+successful, it will send back an error message. See linkgit:gitprotocol-pack[5]
for example messages.
report-status-v2
@@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
the "proc-receive" hook. The "proc-receive" hook may handle a command
for a pseudo-reference which may create or update a reference with
different name, new-oid, and old-oid. While the capability
-'report-status' cannot report for such case. See pack-protocol.txt
+'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]
for details.
delete-refs
@@ -376,5 +388,9 @@ the server as well.
Session IDs should be unique to a given process. They must fit within a
packet-line, and must not contain non-printable or whitespace characters. The
current implementation uses trace2 session IDs (see
-link:api-trace2.html[api-trace2] for details), but this may change and users of
-the session ID should not rely on this fact.
+link:technical/api-trace2.html[api-trace2] for details), but this may change
+and users of the session ID should not rely on this fact.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt
index ecedb34..1486651 100644
--- a/Documentation/technical/protocol-common.txt
+++ b/Documentation/gitprotocol-common.txt
@@ -1,5 +1,20 @@
-Documentation Common to Pack and Http Protocols
-===============================================
+gitprotocol-common(5)
+=====================
+
+NAME
+----
+gitprotocol-common - Things common to various protocols
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
+
+This document sets defines things common to various over-the-wire
+protocols and file formats used in Git.
ABNF Notation
-------------
@@ -97,3 +112,7 @@ Examples (as C-style strings):
"000bfoobar\n" "foobar\n"
"0004" ""
----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt
index cc5126c..ccc13f0 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/gitprotocol-http.txt
@@ -1,5 +1,19 @@
-HTTP transfer protocols
-=======================
+gitprotocol-http(5)
+===================
+
+NAME
+----
+gitprotocol-http - Git HTTP-based protocols
+
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+
+DESCRIPTION
+-----------
Git supports two HTTP based transfer protocols. A "dumb" protocol
which requires only a standard HTTP server on the server end of the
@@ -222,7 +236,7 @@ smart server reply:
S: 0000
The client may send Extra Parameters (see
-Documentation/technical/pack-protocol.txt) as a colon-separated string
+linkgit:gitprotocol-pack[5]) as a colon-separated string
in the Git-Protocol HTTP header.
Uses the `--http-backend-info-refs` option to
@@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.
TODO: Document this further.
-
-References
+REFERENCES
----------
http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
-link:technical/pack-protocol.html
-link:technical/protocol-capabilities.html
+
+SEE ALSO
+--------
+
+linkgit:gitprotocol-pack[5]
+linkgit:gitprotocol-capabilities[5]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt
index e13a2c0..dd4108b 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/gitprotocol-pack.txt
@@ -1,11 +1,23 @@
-Packfile transfer protocols
-===========================
+gitprotocol-pack(5)
+===================
+
+NAME
+----
+gitprotocol-pack - How packs are transferred over-the-wire
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
Git supports transferring data in packfiles over the ssh://, git://, http:// and
file:// transports. There exist two sets of protocols, one for pushing
data from a client to a server and another for fetching data from a
server to a client. The three transports (ssh, git, file) use the same
-protocol to transfer data. http is documented in http-protocol.txt.
+protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].
The processes invoked in the canonical Git implementation are 'upload-pack'
on the server side and 'fetch-pack' on the client side for fetching data;
@@ -18,7 +30,7 @@ pkt-line Format
---------------
The descriptions below build on the pkt-line format described in
-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
+linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
include a LF, but the receiver MUST NOT complain if it is not present.
@@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
Servers that receive any such Extra Parameters MUST ignore all
unrecognized keys. Currently, the only Extra Parameter recognized is
-"version" with a value of '1' or '2'. See protocol-v2.txt for more
+"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more
information on protocol version 2.
Git Transport
@@ -455,7 +467,7 @@ Now that the client and server have finished negotiation about what
the minimal amount of data that needs to be sent to the client is, the server
will construct and send the required data in packfile format.
-See pack-format.txt for what the packfile itself actually looks like.
+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.
If 'side-band' or 'side-band-64k' capabilities have been specified by
the client, the server will send the packfile data multiplexed.
@@ -707,3 +719,7 @@ An example client/server communication might look like this:
S: 0018ok refs/heads/debug\n
S: 002ang refs/heads/master non-fast-forward\n
----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt
index 8a877d2..59bf41c 100644
--- a/Documentation/technical/protocol-v2.txt
+++ b/Documentation/gitprotocol-v2.txt
@@ -1,5 +1,17 @@
-Git Wire Protocol, Version 2
-============================
+gitprotocol-v2(5)
+=================
+
+NAME
+----
+gitprotocol-v2 - Git Wire Protocol, Version 2
+
+SYNOPSIS
+--------
+[verse]
+<over-the-wire-protocol>
+
+DESCRIPTION
+-----------
This document presents a specification for a version 2 of Git's wire
protocol. Protocol v2 will improve upon v1 in the following ways:
@@ -26,8 +38,7 @@ Packet-Line Framing
-------------------
All communication is done using packet-line framing, just as in v1. See
-`Documentation/technical/pack-protocol.txt` and
-`Documentation/technical/protocol-common.txt` for more information.
+linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.
In protocol v2 these special packets will have the following semantics:
@@ -42,7 +53,7 @@ Initial Client Request
In general a client can request to speak protocol v2 by sending
`version=2` through the respective side-channel for the transport being
used which inevitably sets `GIT_PROTOCOL`. More information can be
-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
+found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the
`GIT_PROTOCOL` definition in `git.txt`. In all cases the
response from the server is the capability advertisement.
@@ -66,7 +77,7 @@ HTTP Transport
~~~~~~~~~~~~~~
When using the http:// or https:// transport a client makes a "smart"
-info/refs request as described in `http-protocol.txt` and requests that
+info/refs request as described in linkgit:gitprotocol-http[5] and requests that
v2 be used by supplying "version=2" in the `Git-Protocol` header.
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
@@ -533,8 +544,8 @@ the server as well.
Session IDs should be unique to a given process. They must fit within a
packet-line, and must not contain non-printable or whitespace characters. The
current implementation uses trace2 session IDs (see
-link:api-trace2.html[api-trace2] for details), but this may change and users of
-the session ID should not rely on this fact.
+link:technical/api-trace2.html[api-trace2] for details), but this may change
+and users of the session ID should not rely on this fact.
object-info
~~~~~~~~~~~
@@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.
attr = "size"
obj-info = obj-id SP obj-size
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 6f1e269..ed8da42 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -168,6 +168,9 @@ Supported commands: 'list', 'import'.
Can guarantee that when a clone is requested, the received
pack is self contained and is connected.
+'get'::
+ Can use the 'get' command to download a file from a given URI.
+
If a helper advertises 'connect', Git will use it if possible and
fall back to another capability if the helper requests so when
connecting (see the 'connect' command under COMMANDS).
@@ -418,6 +421,12 @@ Supported if the helper has the "connect" capability.
+
Supported if the helper has the "stateless-connect" capability.
+'get' <uri> <path>::
+ Downloads the file from the given `<uri>` to the given `<path>`. If
+ `<path>.temp` exists, then Git assumes that the `.temp` file is a
+ partial download from a previous attempt and will resume the
+ download from that position.
+
If a fatal error occurs, the program writes the error message to
stderr and exits. The caller should expect that a suitable error
message has been printed if the child closes the connection without
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index aa2f41f..5a53726 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -20,7 +20,7 @@
[[def_branch]]branch::
A "branch" is a line of development. The most recent
<<def_commit,commit>> on a branch is referred to as the tip of
- that branch. The tip of the branch is referenced by a branch
+ that branch. The tip of the branch is <<def_ref,referenced>> by a branch
<<def_head,head>>, which moves forward as additional development
is done on the branch. A single Git
<<def_repository,repository>> can track an arbitrary number of
@@ -75,6 +75,21 @@ state in the Git history, by creating a new commit representing the current
state of the <<def_index,index>> and advancing <<def_HEAD,HEAD>>
to point at the new commit.
+[[def_commit_graph_general]]commit graph concept, representations and usage::
+ A synonym for the <<def_DAG,DAG>> structure formed by the commits
+ in the object database, <<def_ref,referenced>> by branch tips,
+ using their <<def_chain,chain>> of linked commits.
+ This structure is the definitive commit graph. The
+ graph can be represented in other ways, e.g. the
+ <<def_commit_graph_file,"commit-graph" file>>.
+
+[[def_commit_graph_file]]commit-graph file::
+ The "commit-graph" (normally hyphenated) file is a supplemental
+ representation of the <<def_commit_graph_general,commit graph>>
+ which accelerates commit graph walks. The "commit-graph" file is
+ stored either in the .git/objects/info directory or in the info
+ directory of an alternate object database.
+
[[def_commit_object]]commit object::
An <<def_object,object>> which contains the information about a
particular <<def_revision,revision>>, such as <<def_parent,parents>>, committer,
@@ -262,7 +277,7 @@ This commit is referred to as a "merge commit", or sometimes just a
identified by its <<def_object_name,object name>>. The objects usually
live in `$GIT_DIR/objects/`.
-[[def_object_identifier]]object identifier::
+[[def_object_identifier]]object identifier (oid)::
Synonym for <<def_object_name,object name>>.
[[def_object_name]]object name::
@@ -493,6 +508,14 @@ exclude;;
<<def_tree_object,trees>> to the trees or <<def_blob_object,blobs>>
that they contain.
+[[def_reachability_bitmap]]reachability bitmaps::
+ Reachability bitmaps store information about the
+ <<def_reachable,reachability>> of a selected set of commits in
+ a packfile, or a multi-pack index (MIDX), to speed up object search.
+ The bitmaps are stored in a ".bitmap" file. A repository may have at
+ most one bitmap file in use. The bitmap file may belong to either one
+ pack, or the repository's multi-pack index (if it exists).
+
[[def_rebase]]rebase::
To reapply a series of changes from a <<def_branch,branch>> to a
different base, and reset the <<def_head,head>> of that branch
diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 601aae8..e653775 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -1,9 +1,10 @@
Content-type: text/asciidoc
-Abstract: When a critical vulnerability is discovered and fixed, we follow this
- script to coordinate a public release.
+Abstract: When a vulnerability is reported, we follow these guidelines to
+ assess the vulnerability, create and review a fix, and coordinate embargoed
+ security releases.
How we coordinate embargoed releases
-====================================
+------------------------------------
To protect Git users from critical vulnerabilities, we do not just release
fixed versions like regular maintenance releases. Instead, we coordinate
@@ -11,33 +12,147 @@ releases with packagers, keeping the fixes under an embargo until the release
date. That way, users will have a chance to upgrade on that date, no matter
what Operating System or distribution they run.
-Open a Security Advisory draft
-------------------------------
+The `git-security` mailing list
+-------------------------------
+
+Responsible disclosures of vulnerabilities, analysis, proposed fixes as
+well as the orchestration of coordinated embargoed releases all happen on the
+`git-security` mailing list at <git-security@googlegroups.com>.
+
+In this context, the term "embargo" refers to the time period that information
+about a vulnerability is kept under wraps and only shared on a need-to-know
+basis. This is necessary to protect Git's users from bad actors who would
+otherwise be made aware of attack vectors that could be exploited. "Lifting the
+embargo" refers to publishing the version that fixes the vulnerabilities.
+
+Audience of the `git-security` mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Anybody may contact the `git-security` mailing list by sending an email
+to <git-security@googlegroups.com>, though the archive is closed to the
+public and only accessible to subscribed members.
+
+There are a few dozen subscribed members: core Git developers who are trusted
+with addressing vulnerabilities, and stakeholders (i.e. owners of products
+affected by security vulnerabilities in Git).
+
+Most of the discussions revolve around assessing the severity of the reported
+issue (including the decision whether the report is security-relevant or can be
+redirected to the public mailing list), how to remediate the issue, determining
+the timeline of the disclosure as well as aligning priorities and
+requirements.
-The first step is to https://github.com/git/git/security/advisories/new[open an
-advisory]. Technically, it is not necessary, but it is convenient and saves a
-bit of hassle. This advisory can also be used to obtain the CVE number and it
-will give us a private fork associated with it that can be used to collaborate
-on a fix.
+Communications
+~~~~~~~~~~~~~~
-Release date of the embargoed version
--------------------------------------
+If you are a stakeholder, it is a good idea to pay close attention to the
+discussions, as pertinent information may be buried in the middle of a lively
+conversation that might not look relevant to your interests. For example, the
+tentative timeline might be agreed upon in the middle of discussing code
+comment formatting in one of the patches and whether or not to combine fixes
+for multiple, separate vulnerabilities into the same embargoed release. Most
+mail threads are not usually structured specifically to communicate
+agreements, assessments or timelines.
-If the vulnerability affects Windows users, we want to have our friends over at
-Visual Studio on board. This means we need to target a "Patch Tuesday" (i.e. a
-second Tuesday of the month), at the minimum three weeks from heads-up to
-coordinated release.
+Typical timeline
+----------------
-If the vulnerability affects the server side, or can benefit from scans on the
-server side (i.e. if `git fsck` can detect an attack), it is important to give
-all involved Git repository hosting sites enough time to scan all of those
-repositories.
+- A potential vulnerability is reported to the `git-security` mailing list.
+
+- The members of the git-security list start a discussion to give an initial
+ assessment of the severity of the reported potential vulnerability.
+ We aspire to do so within a few days.
+
+- After discussion, if consensus is reached that it is not critical enough
+ to warrant any embargo, the reporter is redirected to the public Git mailing
+ list. This ends the reporter's interaction with the `git-security` list.
+
+- If it is deemed critical enough for an embargo, ideas are presented on how to
+ address the vulnerability.
+
+- Usually around that time, the Git maintainer or their delegate(s) open a draft
+ security advisory in the `git/git` repository on GitHub (see below for more
+ details).
+
+- Code review can take place in a variety of different locations,
+ depending on context. These are: patches sent inline on the git-security list,
+ a private fork on GitHub associated with the draft security advisory, or the
+ git/cabal repository.
+
+- Contributors working on a fix should consider beginning by sending
+ patches to the git-security list (inline with the original thread), since they
+ are accessible to all subscribers, along with the original reporter.
+
+- Once the review has settled and everyone involved in the review agrees that
+ the patches are nearing the finish line, the Git maintainer, and others
+ determine a release date as well as the release trains that are serviced. The
+ decision regarding which versions need a backported fix is based on input from
+ the reporter, the contributor who worked on the patches, and from
+ stakeholders. Operators of hosting sites who may want to analyze whether the
+ given issue is exploited via any of the repositories they host, and binary
+ packagers who want to make sure their product gets patched adequately against
+ the vulnerability, for example, may want to give their input at this stage.
+
+- While the Git community does its best to accommodate the specific timeline
+ requests of the various binary packagers, the nature of the issue may preclude
+ a prolonged release schedule. For fixes deemed urgent, it may be in the best
+ interest of the Git users community to shorten the disclosure and release
+ timeline, and packagers may need to adapt accordingly.
+
+- Subsequently, branches with the fixes are pushed to the git/cabal repository.
+
+- The tags are created by the Git maintainer and pushed to the same repository.
+
+- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepare the
+ corresponding release artifacts, based on the tags created that have been
+ prepared by the Git maintainer.
+
+- The release artifacts prepared by various binary packagers can be
+ made available to stakeholders under embargo via a mail to the
+ `git-security` list.
+
+- Less than a week before the release, a mail with the relevant information is
+ sent to <distros@vs.openwall.org> (see below), a list used to pre-announce
+ embargoed releases of open source projects to the stakeholders of all major
+ distributions of Linux as well as other OSes.
+
+- Public communication is then prepared in advance of the release date. This
+ includes blog posts and mails to the Git and Git for Windows mailing lists.
+
+- On the day of the release, at around 10am Pacific Time, the Git maintainer
+ pushes the tag and the `master` branch to the public repository, then sends
+ out an announcement mail.
+
+- Once the tag is pushed, the Git for Windows maintainer publishes the
+ corresponding tag and creates a GitHub Release with the associated release
+ artifacts (Git for Windows installer, Portable Git, MinGit, etc).
+
+- Git for Windows release is then announced via a mail to the public Git and
+ Git for Windows mailing lists as well as via a tweet.
+
+- Ditto for distribution packagers for Linux and other platforms:
+ their releases are announced via their preferred channels.
+
+- A mail to <oss-security@lists.openwall.org> (see below for details) is sent
+ as a follow-up to the <distros@vs.openwall.org> one, describing the
+ vulnerability in detail, often including a proof of concept of an exploit.
+
+Note: The Git project makes no guarantees about timelines, but aims to keep
+embargoes reasonably short in the interest of keeping Git's users safe.
+
+Opening a Security Advisory draft
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first step is to https://github.com/git/git/security/advisories/new[open
+an advisory]. Technically, this is not necessary. However, it is the most
+convenient way to obtain the CVE number and it give us a private repository
+associated with it that can be used to collaborate on a fix.
Notifying the Linux distributions
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At most two weeks before release date, we need to send a notification to
-distros@vs.openwall.org, preferably less than 7 days before the release date.
+<distros@vs.openwall.org>, preferably less than 7 days before the release date.
This will reach most (all?) Linux distributions. See an example below, and the
guidelines for this mailing list at
https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists[here].
@@ -65,7 +180,7 @@ created using a command like this:
tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
Example mail to distros@vs.openwall.org
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
To: distros@vs.openwall.org
@@ -101,7 +216,7 @@ Thanks,
....
Example mail to oss-security@lists.openwall.com
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
To: oss-security@lists.openwall.com
@@ -128,4 +243,4 @@ it goes to <developer>.
Thanks,
<name>
-....
+.... \ No newline at end of file
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index a67130d..d07c6d4 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -231,7 +231,7 @@ by doing the following:
- Prepare 'jch' branch, which is used to represent somewhere
between 'master' and 'seen' and often is slightly ahead of 'next'.
- $ Meta/Reintegrate master..seen >Meta/redo-jch.sh
+ $ Meta/Reintegrate master..jch >Meta/redo-jch.sh
The result is a script that lists topics to be merged in order to
rebuild 'seen' as the input to Meta/Reintegrate script. Remove
@@ -256,7 +256,7 @@ by doing the following:
merged to 'next', add it at the end of the list. Then:
$ git checkout -B jch master
- $ Meta/redo-jch.sh -c1
+ $ sh Meta/redo-jch.sh -c1
to rebuild the 'jch' branch from scratch. "-c1" tells the script
to stop merging at the first line that begins with '###'
@@ -283,6 +283,11 @@ by doing the following:
$ git diff jch next
+ Then build the rest of 'jch':
+
+ $ git checkout jch
+ $ sh Meta/redo-jch.sh
+
When all is well, clean up the redo-jch.sh script with
$ sh Meta/redo-jch.sh -u
@@ -293,7 +298,7 @@ by doing the following:
- Rebuild 'seen'.
- $ Meta/Reintegrate master..seen >Meta/redo-seen.sh
+ $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh
Edit the result by adding new topics that are not still in 'seen'
in the script. Then
diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt
index 8994e25..5efb4fe 100644
--- a/Documentation/howto/recover-corrupted-object-harder.txt
+++ b/Documentation/howto/recover-corrupted-object-harder.txt
@@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it
has the git packed object header, which is variable-length. We want to
strip that off so we can start playing with the zlib data directly. You
can either work your way through it manually (the format is described in
-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),
+linkgit:gitformat-pack[5]),
or you can walk through it in a debugger. I did the latter, creating a
valid pack like:
diff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.txt
new file mode 100644
index 0000000..296a239
--- /dev/null
+++ b/Documentation/includes/cmd-config-section-all.txt
@@ -0,0 +1,3 @@
+Everything below this line in this section is selectively included
+from the linkgit:git-config[1] documentation. The content is the same
+as what's found there:
diff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.txt
new file mode 100644
index 0000000..b1e7682
--- /dev/null
+++ b/Documentation/includes/cmd-config-section-rest.txt
@@ -0,0 +1,3 @@
+Everything above this line in this section isn't included from the
+linkgit:git-config[1] documentation. The content that follows is the
+same as what's found there:
diff --git a/Documentation/lint-fsck-msgids.perl b/Documentation/lint-fsck-msgids.perl
new file mode 100755
index 0000000..1233ffe
--- /dev/null
+++ b/Documentation/lint-fsck-msgids.perl
@@ -0,0 +1,70 @@
+#!/usr/bin/perl
+
+my ($fsck_h, $fsck_msgids_txt, $okfile) = @ARGV;
+
+my (%in_fsck_h, $fh, $bad);
+
+open($fh, "<", "$fsck_h") or die;
+while (<$fh>) {
+ if (/^\s+FUNC\(([0-9A-Z_]+), ([A-Z]+)\)/) {
+ my ($name, $severity) = ($1, $2);
+ my ($first) = 1;
+ $name = join('',
+ map {
+ y/A-Z/a-z/;
+ if (!$first) {
+ s/^(.)/uc($1)/e;
+ } else {
+ $first = 0;
+ }
+ $_;
+ }
+ split(/_/, $name));
+ $in_fsck_h{$name} = $severity;
+ }
+}
+close($fh);
+
+open($fh, "<", "$fsck_msgids_txt") or die;
+my ($previous, $current);
+while (<$fh>) {
+ if (!defined $current) {
+ if (/^\`([a-zA-Z0-9]*)\`::/) {
+ $current = $1;
+ if ((defined $previous) &&
+ ($current le $previous)) {
+ print STDERR "$previous >= $current in doc\n";
+ $bad = 1;
+ }
+ }
+ } elsif (/^\s+\(([A-Z]+)\) /) {
+ my ($level) = $1;
+ if (!exists $in_fsck_h{$current}) {
+ print STDERR "$current does not exist in fsck.h\n";
+ $bad = 1;
+ } elsif ($in_fsck_h{$current} eq "") {
+ print STDERR "$current defined twice\n";
+ $bad = 1;
+ } elsif ($in_fsck_h{$current} ne $level) {
+ print STDERR "$current severity $level != $in_fsck_h{$current}\n";
+ $bad = 1;
+ }
+ $previous = $current;
+ $in_fsck_h{$current} = ""; # mark as seen.
+ undef $current;
+ }
+}
+close($fh);
+
+for my $key (keys %in_fsck_h) {
+ if ($in_fsck_h{$key} ne "") {
+ print STDERR "$key not explained in doc.\n";
+ $bad = 1;
+ }
+}
+
+die if ($bad);
+
+open($fh, ">", "$okfile");
+print $fh "good\n";
+close($fh);
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 425377d..02408a0 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -32,6 +32,9 @@ my %SECTIONS;
'SEE ALSO' => {
order => $order++,
},
+ 'FILE FORMAT' => {
+ order => $order++,
+ },
'GIT' => {
required => 1,
order => $order++,
diff --git a/Documentation/rerere-options.txt b/Documentation/rerere-options.txt
new file mode 100644
index 0000000..c3321dd
--- /dev/null
+++ b/Documentation/rerere-options.txt
@@ -0,0 +1,9 @@
+--rerere-autoupdate::
+--no-rerere-autoupdate::
+ After the rerere mechanism reuses a recorded resolution on
+ the current conflict to update the files in the working
+ tree, allow it to also update the index with the result of
+ resolution. `--no-rerere-autoupdate` is a good way to
+ double-check what `rerere` did and catch potential
+ mismerges, before committing the result to the index with a
+ separate `git add`.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 195e74e..ff68e48 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -195,6 +195,13 @@ respectively, and they must begin with `refs/` when applied to `--glob`
or `--all`. If a trailing '/{asterisk}' is intended, it must be given
explicitly.
+--exclude-hidden=[receive|uploadpack]::
+ Do not include refs that would be hidden by `git-receive-pack` or
+ `git-upload-pack` by consulting the appropriate `receive.hideRefs` or
+ `uploadpack.hideRefs` configuration along with `transfer.hideRefs` (see
+ linkgit:git-config[1]). This option affects the next pseudo-ref option
+ `--all` or `--glob` and is cleared after processing them.
+
--reflog::
Pretend as if all objects mentioned by reflogs are listed on the
command line as `<commit>`.
@@ -242,6 +249,7 @@ ifdef::git-rev-list[]
to `/dev/null` as the output does not have to be formatted.
--disk-usage::
+--disk-usage=human::
Suppress normal output; instead, print the sum of the bytes used
for on-disk storage by the selected commits or objects. This is
equivalent to piping the output into `git cat-file
@@ -249,6 +257,8 @@ ifdef::git-rev-list[]
faster (especially with `--use-bitmap-index`). See the `CAVEATS`
section in linkgit:git-cat-file[1] for the limitations of what
"on-disk storage" means.
+ With the optional value `human`, on-disk storage size is shown
+ in human-readable string(e.g. 12.24 Kib, 3.50 Mib).
endif::git-rev-list[]
--cherry-mark::
@@ -389,12 +399,14 @@ Default mode::
merges from the resulting history, as there are no selected
commits contributing to this merge.
---ancestry-path::
+--ancestry-path[=<commit>]::
When given a range of commits to display (e.g. 'commit1..commit2'
- or 'commit2 {caret}commit1'), only display commits that exist
- directly on the ancestry chain between the 'commit1' and
- 'commit2', i.e. commits that are both descendants of 'commit1',
- and ancestors of 'commit2'.
+ or 'commit2 {caret}commit1'), only display commits in that range
+ that are ancestors of <commit>, descendants of <commit>, or
+ <commit> itself. If no commit is specified, use 'commit1' (the
+ excluded part of the range) as <commit>. Can be passed multiple
+ times; if so, a commit is included if it is any of the commits
+ given or if it is an ancestor or descendant of one of them.
A more detailed explanation follows.
@@ -568,11 +580,10 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`:
There is another simplification mode available:
---ancestry-path::
- Limit the displayed commits to those directly on the ancestry
- chain between the ``from'' and ``to'' commits in the given commit
- range. I.e. only display commits that are ancestor of the ``to''
- commit and descendants of the ``from'' commit.
+--ancestry-path[=<commit>]::
+ Limit the displayed commits to those which are an ancestor of
+ <commit>, or which are a descendant of <commit>, or are <commit>
+ itself.
+
As an example use case, consider the following commit history:
+
@@ -604,6 +615,29 @@ option does. Applied to the 'D..M' range, it results in:
\
L--M
-----------------------------------------------------------------------
++
+We can also use `--ancestry-path=D` instead of `--ancestry-path` which
+means the same thing when applied to the 'D..M' range but is just more
+explicit.
++
+If we instead are interested in a given topic within this range, and all
+commits affected by that topic, we may only want to view the subset of
+`D..M` which contain that topic in their ancestry path. So, using
+`--ancestry-path=H D..M` for example would result in:
++
+-----------------------------------------------------------------------
+ E
+ \
+ G---H---I---J
+ \
+ L--M
+-----------------------------------------------------------------------
++
+Whereas `--ancestry-path=K D..M` would result in
++
+-----------------------------------------------------------------------
+ K---------------L--M
+-----------------------------------------------------------------------
Before discussing another option, `--show-pulls`, we need to
create a new example history.
@@ -659,7 +693,7 @@ Here, the merge commits `O` and `P` contribute extra noise, as they did
not actually contribute a change to `file.txt`. They only merged a topic
that was based on an older version of `file.txt`. This is a common
issue in repositories using a workflow where many contributors work in
-parallel and merge their topic branches along a single trunk: manu
+parallel and merge their topic branches along a single trunk: many
unrelated merges appear in the `--full-history` results.
When using the `--simplify-merges` option, the commits `O` and `P`
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index e3e3501..0d2e55d 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -363,7 +363,7 @@ Revision Range Summary
'<rev>{caret}!', e.g. 'HEAD{caret}!'::
A suffix '{caret}' followed by an exclamation mark is the same
- as giving commit '<rev>' and then all its parents prefixed with
+ as giving commit '<rev>' and all its parents prefixed with
'{caret}' to exclude them (and their ancestors).
'<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2'::
diff --git a/Documentation/scalar.txt b/Documentation/scalar.txt
new file mode 100644
index 0000000..f33436c
--- /dev/null
+++ b/Documentation/scalar.txt
@@ -0,0 +1,166 @@
+scalar(1)
+=========
+
+NAME
+----
+scalar - A tool for managing large Git repositories
+
+SYNOPSIS
+--------
+[verse]
+scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>]
+scalar list
+scalar register [<enlistment>]
+scalar unregister [<enlistment>]
+scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]
+scalar reconfigure [ --all | <enlistment> ]
+scalar diagnose [<enlistment>]
+scalar delete <enlistment>
+
+DESCRIPTION
+-----------
+
+Scalar is a repository management tool that optimizes Git for use in large
+repositories. Scalar improves performance by configuring advanced Git settings,
+maintaining repositories in the background, and helping to reduce data sent
+across the network.
+
+An important Scalar concept is the enlistment: this is the top-level directory
+of the project. It usually contains the subdirectory `src/` which is a Git
+worktree. This encourages the separation between tracked files (inside `src/`)
+and untracked files, such as build artifacts (outside `src/`). When registering
+an existing Git worktree with Scalar whose name is not `src`, the enlistment
+will be identical to the worktree.
+
+The `scalar` command implements various subcommands, and different options
+depending on the subcommand. With the exception of `clone`, `list` and
+`reconfigure --all`, all subcommands expect to be run in an enlistment.
+
+The following options can be specified _before_ the subcommand:
+
+-C <directory>::
+ Before running the subcommand, change the working directory. This
+ option imitates the same option of linkgit:git[1].
+
+-c <key>=<value>::
+ For the duration of running the specified subcommand, configure this
+ setting. This option imitates the same option of linkgit:git[1].
+
+COMMANDS
+--------
+
+Clone
+~~~~~
+
+clone [<options>] <url> [<enlistment>]::
+ Clones the specified repository, similar to linkgit:git-clone[1]. By
+ default, only commit and tree objects are cloned. Once finished, the
+ worktree is located at `<enlistment>/src`.
++
+The sparse-checkout feature is enabled (except when run with `--full-clone`)
+and the only files present are those in the top-level directory. Use
+`git sparse-checkout set` to expand the set of directories you want to see,
+or `git sparse-checkout disable` to expand to all files (see
+linkgit:git-sparse-checkout[1] for more details). You can explore the
+subdirectories outside your sparse-checkout by using `git ls-tree
+HEAD[:<directory>]`.
+
+-b <name>::
+--branch <name>::
+ Instead of checking out the branch pointed to by the cloned
+ repository's HEAD, check out the `<name>` branch instead.
+
+--[no-]single-branch::
+ Clone only the history leading to the tip of a single branch, either
+ specified by the `--branch` option or the primary branch remote's
+ `HEAD` points at.
++
+Further fetches into the resulting repository will only update the
+remote-tracking branch for the branch this option was used for the initial
+cloning. If the HEAD at the remote did not point at any branch when
+`--single-branch` clone was made, no remote-tracking branch is created.
+
+--[no-]full-clone::
+ A sparse-checkout is initialized by default. This behavior can be
+ turned off via `--full-clone`.
+
+List
+~~~~
+
+list::
+ List enlistments that are currently registered by Scalar. This
+ subcommand does not need to be run inside an enlistment.
+
+Register
+~~~~~~~~
+
+register [<enlistment>]::
+ Adds the enlistment's repository to the list of registered repositories
+ and starts background maintenance. If `<enlistment>` is not provided,
+ then the enlistment associated with the current working directory is
+ registered.
++
+Note: when this subcommand is called in a worktree that is called `src/`, its
+parent directory is considered to be the Scalar enlistment. If the worktree is
+_not_ called `src/`, it itself will be considered to be the Scalar enlistment.
+
+Unregister
+~~~~~~~~~~
+
+unregister [<enlistment>]::
+ Remove the specified repository from the list of repositories
+ registered with Scalar and stop the scheduled background maintenance.
+
+Run
+~~~
+
+scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]::
+ Run the given maintenance task (or all tasks, if `all` was specified).
+ Except for `all` and `config`, this subcommand simply hands off to
+ linkgit:git-maintenance[1] (mapping `fetch` to `prefetch` and
+ `pack-files` to `incremental-repack`).
++
+These tasks are run automatically as part of the scheduled maintenance,
+as soon as the repository is registered with Scalar. It should therefore
+not be necessary to run this subcommand manually.
++
+The `config` task is specific to Scalar and configures all those
+opinionated default settings that make Git work more efficiently with
+large repositories. As this task is run as part of `scalar clone`
+automatically, explicit invocations of this task are rarely needed.
+
+Reconfigure
+~~~~~~~~~~~
+
+After a Scalar upgrade, or when the configuration of a Scalar enlistment
+was somehow corrupted or changed by mistake, this subcommand allows to
+reconfigure the enlistment.
+
+With the `--all` option, all enlistments currently registered with Scalar
+will be reconfigured. Use this option after each Scalar upgrade.
+
+Diagnose
+~~~~~~~~
+
+diagnose [<enlistment>]::
+ When reporting issues with Scalar, it is often helpful to provide the
+ information gathered by this command, including logs and certain
+ statistics describing the data shape of the current enlistment.
++
+The output of this command is a `.zip` file that is written into
+a directory adjacent to the worktree in the `src` directory.
+
+Delete
+~~~~~~
+
+delete <enlistment>::
+ This subcommand lets you delete an existing Scalar enlistment from your
+ local file system, unregistering the repository.
+
+SEE ALSO
+--------
+linkgit:git-clone[1], linkgit:git-maintenance[1].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/api-error-handling.txt b/Documentation/technical/api-error-handling.txt
index 70bf1d3..665c496 100644
--- a/Documentation/technical/api-error-handling.txt
+++ b/Documentation/technical/api-error-handling.txt
@@ -46,7 +46,7 @@ parse-options.c.
returns -1 after reporting the situation to the caller.
These reports will be logged via the trace2 facility. See the "error"
-event in link:api-trace2.txt[trace2 API].
+event in link:api-trace2.html[trace2 API].
Customizable error handlers
---------------------------
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index acfd5dc..61fa6ee 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -8,7 +8,8 @@ Basics
------
The argument vector `argv[]` may usually contain mandatory or optional
-'non-option arguments', e.g. a filename or a branch, and 'options'.
+'non-option arguments', e.g. a filename or a branch, 'options', and
+'subcommands'.
Options are optional arguments that start with a dash and
that allow to change the behavior of a command.
@@ -48,6 +49,33 @@ The parse-options API allows:
option, e.g. `-a -b --option -- --this-is-a-file` indicates that
`--this-is-a-file` must not be processed as an option.
+Subcommands are special in a couple of ways:
+
+* Subcommands only have long form, and they have no double dash prefix, no
+ negated form, and no description, and they don't take any arguments, and
+ can't be abbreviated.
+
+* There must be exactly one subcommand among the arguments, or zero if the
+ command has a default operation mode.
+
+* All arguments following the subcommand are considered to be arguments of
+ the subcommand, and, conversely, arguments meant for the subcommand may
+ not precede the subcommand.
+
+Therefore, if the options array contains at least one subcommand and
+`parse_options()` encounters the first dashless argument, it will either:
+
+* stop and return, if that dashless argument is a known subcommand, setting
+ `value` to the function pointer associated with that subcommand, storing
+ the name of the subcommand in argv[0], and leaving the rest of the
+ arguments unprocessed, or
+
+* stop and return, if it was invoked with the `PARSE_OPT_SUBCOMMAND_OPTIONAL`
+ flag and that dashless argument doesn't match any subcommands, leaving
+ `value` unchanged and the rest of the arguments unprocessed, or
+
+* show error and usage, and abort.
+
Steps to parse options
----------------------
@@ -90,8 +118,8 @@ Flags are the bitwise-or of:
Keep the first argument, which contains the program name. It's
removed from argv[] by default.
-`PARSE_OPT_KEEP_UNKNOWN`::
- Keep unknown arguments instead of erroring out. This doesn't
+`PARSE_OPT_KEEP_UNKNOWN_OPT`::
+ Keep unknown options instead of erroring out. This doesn't
work for all combinations of arguments as users might expect
it to do. E.g. if the first argument in `--unknown --known`
takes a value (which we can't know), the second one is
@@ -101,6 +129,8 @@ Flags are the bitwise-or of:
non-option, not as a value belonging to the unknown option,
the parser early. That's why parse_options() errors out if
both options are set.
+ Note that non-option arguments are always kept, even without
+ this flag.
`PARSE_OPT_NO_INTERNAL_HELP`::
By default, parse_options() handles `-h`, `--help` and
@@ -108,6 +138,13 @@ Flags are the bitwise-or of:
turns it off and allows one to add custom handlers for these
options, or to just leave them unknown.
+`PARSE_OPT_SUBCOMMAND_OPTIONAL`::
+ Don't error out when no subcommand is specified.
+
+Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands;
+while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be
+used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`.
+
Data Structure
--------------
@@ -236,10 +273,14 @@ There are some macros to easily define options:
`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
Define an "operation mode" option, only one of which in the same
group of "operating mode" options that share the same `int_var`
- can be given by the user. `enum_val` is set to `int_var` when the
+ can be given by the user. `int_var` is set to `enum_val` when the
option is used, but an error is reported if other "operating mode"
option has already set its value to the same `int_var`.
+ In new commands consider using subcommands instead.
+`OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::
+ Define a subcommand. `subcommand_fn` is put into `fn_ptr` when
+ this subcommand is used.
The last element of the array must be `OPT_END()`.
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt
index d79ad32..d44ada9 100644
--- a/Documentation/technical/api-simple-ipc.txt
+++ b/Documentation/technical/api-simple-ipc.txt
@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the
client and server messages are unlimited in length and are terminated
with a flush packet.
-The pkt-line routines (Documentation/technical/protocol-common.txt)
+The pkt-line routines (linkgit:gitprotocol-common[5])
are used to simplify buffer management during message generation,
transmission, and reception. A flush packet is used to mark the end
of the message. This allows the sender to incrementally generate and
diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
index 77a150b..de5fc25 100644
--- a/Documentation/technical/api-trace2.txt
+++ b/Documentation/technical/api-trace2.txt
@@ -148,20 +148,18 @@ filename collisions).
== Trace2 API
-All public Trace2 functions and macros are defined in `trace2.h` and
-`trace2.c`. All public symbols are prefixed with `trace2_`.
+The Trace2 public API is defined and documented in `trace2.h`; refer to it for
+more information. All public functions and macros are prefixed
+with `trace2_` and are implemented in `trace2.c`.
There are no public Trace2 data structures.
The Trace2 code also defines a set of private functions and data types
in the `trace2/` directory. These symbols are prefixed with `tr2_`
-and should only be used by functions in `trace2.c`.
+and should only be used by functions in `trace2.c` (or other private
+source files in `trace2/`).
-== Conventions for Public Functions and Macros
-
-The functions defined by the Trace2 API are declared and documented
-in `trace2.h`. It defines the API functions and wrapper macros for
-Trace2.
+=== Conventions for Public Functions and Macros
Some functions have a `_fl()` suffix to indicate that they take `file`
and `line-number` arguments.
@@ -172,52 +170,7 @@ take a `va_list` argument.
Some functions have a `_printf_fl()` suffix to indicate that they also
take a `printf()` style format with a variable number of arguments.
-There are CPP wrapper macros and `#ifdef`s to hide most of these details.
-See `trace2.h` for more details. The following discussion will only
-describe the simplified forms.
-
-== Public API
-
-All Trace2 API functions send a message to all of the active
-Trace2 Targets. This section describes the set of available
-messages.
-
-It helps to divide these functions into groups for discussion
-purposes.
-
-=== Basic Command Messages
-
-These are concerned with the lifetime of the overall git process.
-e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`,
-`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`.
-
-=== Command Detail Messages
-
-These are concerned with describing the specific Git command
-after the command line, config, and environment are inspected.
-e.g: `void trace2_cmd_name(const char *name)`,
-`void trace2_cmd_mode(const char *mode)`.
-
-=== Child Process Messages
-
-These are concerned with the various spawned child processes,
-including shell scripts, git commands, editors, pagers, and hooks.
-
-e.g: `void trace2_child_start(struct child_process *cmd)`.
-
-=== Git Thread Messages
-
-These messages are concerned with Git thread usage.
-
-e.g: `void trace2_thread_start(const char *thread_name)`.
-
-=== Region and Data Messages
-
-These are concerned with recording performance data
-over regions or spans of code. e.g:
-`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`.
-
-Refer to trace2.h for details about all trace2 functions.
+CPP wrapper macros are defined to hide most of these details.
== Trace2 Target Formats
@@ -685,8 +638,8 @@ The "exec_id" field is a command-unique id and is only useful if the
`"thread_start"`::
This event is generated when a thread is started. It is
- generated from *within* the new thread's thread-proc (for TLS
- reasons).
+ generated from *within* the new thread's thread-proc (because
+ it needs to access data in the thread's thread-local storage).
+
------------
{
@@ -698,7 +651,7 @@ The "exec_id" field is a command-unique id and is only useful if the
`"thread_exit"`::
This event is generated when a thread exits. It is generated
- from *within* the thread's thread-proc (for TLS reasons).
+ from *within* the thread's thread-proc.
+
------------
{
@@ -717,6 +670,7 @@ The "exec_id" field is a command-unique id and is only useful if the
{
"event":"def_param",
...
+ "scope":"global",
"param":"core.abbrev",
"value":"7"
}
@@ -815,6 +769,73 @@ The "value" field may be an integer or a string.
}
------------
+`"th_timer"`::
+ This event logs the amount of time that a stopwatch timer was
+ running in the thread. This event is generated when a thread
+ exits for timers that requested per-thread events.
++
+------------
+{
+ "event":"th_timer",
+ ...
+ "category":"my_category",
+ "name":"my_timer",
+ "intervals":5, # number of time it was started/stopped
+ "t_total":0.052741, # total time in seconds it was running
+ "t_min":0.010061, # shortest interval
+ "t_max":0.011648 # longest interval
+}
+------------
+
+`"timer"`::
+ This event logs the amount of time that a stopwatch timer was
+ running aggregated across all threads. This event is generated
+ when the process exits.
++
+------------
+{
+ "event":"timer",
+ ...
+ "category":"my_category",
+ "name":"my_timer",
+ "intervals":5, # number of time it was started/stopped
+ "t_total":0.052741, # total time in seconds it was running
+ "t_min":0.010061, # shortest interval
+ "t_max":0.011648 # longest interval
+}
+------------
+
+`"th_counter"`::
+ This event logs the value of a counter variable in a thread.
+ This event is generated when a thread exits for counters that
+ requested per-thread events.
++
+------------
+{
+ "event":"th_counter",
+ ...
+ "category":"my_category",
+ "name":"my_counter",
+ "count":23
+}
+------------
+
+`"counter"`::
+ This event logs the value of a counter variable across all threads.
+ This event is generated when the process exits. The total value
+ reported here is the sum across all threads.
++
+------------
+{
+ "event":"counter",
+ ...
+ "category":"my_category",
+ "name":"my_counter",
+ "count":23
+}
+------------
+
+
== Example Trace2 API Usage
Here is a hypothetical usage of the Trace2 API showing the intended
@@ -1205,7 +1226,100 @@ worked on 508 items at offset 2032. Thread "th04" worked on 508 items
at offset 508.
+
This example also shows that thread names are assigned in a racy manner
-as each thread starts and allocates TLS storage.
+as each thread starts.
+
+Config (def param) Events::
+
+ Dump "interesting" config values to trace2 log.
++
+We can optionally emit configuration events, see
+`trace2.configparams` in linkgit:git-config[1] for how to enable
+it.
++
+----------------
+$ git config --system color.ui never
+$ git config --global color.ui always
+$ git config --local color.ui auto
+$ git config --list --show-scope | grep 'color.ui'
+system color.ui=never
+global color.ui=always
+local color.ui=auto
+----------------
++
+Then, mark the config `color.ui` as "interesting" config with
+`GIT_TRACE2_CONFIG_PARAMS`:
++
+----------------
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
+$ export GIT_TRACE2_CONFIG_PARAMS=color.ui
+$ git version
+...
+$ cat ~/log.perf
+d0 | main | version | | | | | ...
+d0 | main | start | | 0.001642 | | | /usr/local/bin/git version
+d0 | main | cmd_name | | | | | version (version)
+d0 | main | def_param | | | | scope:system | color.ui:never
+d0 | main | def_param | | | | scope:global | color.ui:always
+d0 | main | def_param | | | | scope:local | color.ui:auto
+d0 | main | data | r0 | 0.002100 | 0.002100 | fsync | fsync/writeout-only:0
+d0 | main | data | r0 | 0.002126 | 0.002126 | fsync | fsync/hardware-flush:0
+d0 | main | exit | | 0.000470 | | | code:0
+d0 | main | atexit | | 0.000477 | | | code:0
+----------------
+
+Stopwatch Timer Events::
+
+ Measure the time spent in a function call or span of code
+ that might be called from many places within the code
+ throughout the life of the process.
++
+----------------
+static void expensive_function(void)
+{
+ trace2_timer_start(TRACE2_TIMER_ID_TEST1);
+ ...
+ sleep_millisec(1000); // Do something expensive
+ ...
+ trace2_timer_stop(TRACE2_TIMER_ID_TEST1);
+}
+
+static int ut_100timer(int argc, const char **argv)
+{
+ ...
+
+ expensive_function();
+
+ // Do something else 1...
+
+ expensive_function();
+
+ // Do something else 2...
+
+ expensive_function();
+
+ return 0;
+}
+----------------
++
+In this example, we measure the total time spent in
+`expensive_function()` regardless of when it is called
+in the overall flow of the program.
++
+----------------
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
+$ t/helper/test-tool trace2 100timer 3 1000
+...
+$ cat ~/log.perf
+d0 | main | version | | | | | ...
+d0 | main | start | | 0.001453 | | | t/helper/test-tool trace2 100timer 3 1000
+d0 | main | cmd_name | | | | | trace2 (trace2)
+d0 | main | exit | | 3.003667 | | | code:0
+d0 | main | timer | | | | test | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929
+d0 | main | atexit | | 3.003796 | | | code:0
+----------------
+
== Future Work
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt
index a85f58f..c2e652b 100644
--- a/Documentation/technical/bitmap-format.txt
+++ b/Documentation/technical/bitmap-format.txt
@@ -72,6 +72,17 @@ MIDXs, both the bit-cache and rev-cache extensions are required.
pack/MIDX. The format and meaning of the name-hash is
described below.
+ ** {empty}
+ BITMAP_OPT_LOOKUP_TABLE (0x10): :::
+ If present, the end of the bitmap file contains a table
+ containing a list of `N` <commit_pos, offset, xor_row>
+ triplets. The format and meaning of the table is described
+ below.
++
+NOTE: Unlike the xor_offset used to compress an individual bitmap,
+`xor_row` stores an *absolute* index into the lookup table, not a location
+relative to the current entry.
+
4-byte entry count (network byte order): ::
The total count of entries (bitmapped commits) in this bitmap index.
@@ -216,3 +227,31 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
If implementations want to choose a different hashing scheme, they are
free to do so, but MUST allocate a new header flag (because comparing
hashes made under two different schemes would be pointless).
+
+Commit lookup table
+-------------------
+
+If the BITMAP_OPT_LOOKUP_TABLE flag is set, the last `N * (4 + 8 + 4)`
+bytes (preceding the name-hash cache and trailing hash) of the `.bitmap`
+file contains a lookup table specifying the information needed to get
+the desired bitmap from the entries without parsing previous unnecessary
+bitmaps.
+
+For a `.bitmap` containing `nr_entries` reachability bitmaps, the table
+contains a list of `nr_entries` <commit_pos, offset, xor_row> triplets
+(sorted in the ascending order of `commit_pos`). The content of i'th
+triplet is -
+
+ * {empty}
+ commit_pos (4 byte integer, network byte order): ::
+ It stores the object position of a commit (in the midx or pack
+ index).
+
+ * {empty}
+ offset (8 byte integer, network byte order): ::
+ The offset from which that commit's bitmap can be read.
+
+ * {empty}
+ xor_row (4 byte integer, network byte order): ::
+ The position of the triplet whose bitmap is used to compress
+ this one, or `0xffffffff` if no such bitmap exists.
diff --git a/Documentation/technical/bundle-uri.txt b/Documentation/technical/bundle-uri.txt
new file mode 100644
index 0000000..b78d01d
--- /dev/null
+++ b/Documentation/technical/bundle-uri.txt
@@ -0,0 +1,572 @@
+Bundle URIs
+===========
+
+Git bundles are files that store a pack-file along with some extra metadata,
+including a set of refs and a (possibly empty) set of necessary commits. See
+linkgit:git-bundle[1] and linkgit:gitformat-bundle[5] for more information.
+
+Bundle URIs are locations where Git can download one or more bundles in
+order to bootstrap the object database in advance of fetching the remaining
+objects from a remote.
+
+One goal is to speed up clones and fetches for users with poor network
+connectivity to the origin server. Another benefit is to allow heavy users,
+such as CI build farms, to use local resources for the majority of Git data
+and thereby reducing the load on the origin server.
+
+To enable the bundle URI feature, users can specify a bundle URI using
+command-line options or the origin server can advertise one or more URIs
+via a protocol v2 capability.
+
+Design Goals
+------------
+
+The bundle URI standard aims to be flexible enough to satisfy multiple
+workloads. The bundle provider and the Git client have several choices in
+how they create and consume bundle URIs.
+
+* Bundles can have whatever name the server desires. This name could refer
+ to immutable data by using a hash of the bundle contents. However, this
+ means that a new URI will be needed after every update of the content.
+ This might be acceptable if the server is advertising the URI (and the
+ server is aware of new bundles being generated) but would not be
+ ergonomic for users using the command line option.
+
+* The bundles could be organized specifically for bootstrapping full
+ clones, but could also be organized with the intention of bootstrapping
+ incremental fetches. The bundle provider must decide on one of several
+ organization schemes to minimize client downloads during incremental
+ fetches, but the Git client can also choose whether to use bundles for
+ either of these operations.
+
+* The bundle provider can choose to support full clones, partial clones,
+ or both. The client can detect which bundles are appropriate for the
+ repository's partial clone filter, if any.
+
+* The bundle provider can use a single bundle (for clones only), or a
+ list of bundles. When using a list of bundles, the provider can specify
+ whether or not the client needs _all_ of the bundle URIs for a full
+ clone, or if _any_ one of the bundle URIs is sufficient. This allows the
+ bundle provider to use different URIs for different geographies.
+
+* The bundle provider can organize the bundles using heuristics, such as
+ creation tokens, to help the client prevent downloading bundles it does
+ not need. When the bundle provider does not provide these heuristics,
+ the client can use optimizations to minimize how much of the data is
+ downloaded.
+
+* The bundle provider does not need to be associated with the Git server.
+ The client can choose to use the bundle provider without it being
+ advertised by the Git server.
+
+* The client can choose to discover bundle providers that are advertised
+ by the Git server. This could happen during `git clone`, during
+ `git fetch`, both, or neither. The user can choose which combination
+ works best for them.
+
+* The client can choose to configure a bundle provider manually at any
+ time. The client can also choose to specify a bundle provider manually
+ as a command-line option to `git clone`.
+
+Each repository is different and every Git server has different needs.
+Hopefully the bundle URI feature is flexible enough to satisfy all needs.
+If not, then the feature can be extended through its versioning mechanism.
+
+Server requirements
+-------------------
+
+To provide a server-side implementation of bundle servers, no other parts
+of the Git protocol are required. This allows server maintainers to use
+static content solutions such as CDNs in order to serve the bundle files.
+
+At the current scope of the bundle URI feature, all URIs are expected to
+be HTTP(S) URLs where content is downloaded to a local file using a `GET`
+request to that URL. The server could include authentication requirements
+to those requests with the aim of triggering the configured credential
+helper for secure access. (Future extensions could use "file://" URIs or
+SSH URIs.)
+
+Assuming a `200 OK` response from the server, the content at the URL is
+inspected. First, Git attempts to parse the file as a bundle file of
+version 2 or higher. If the file is not a bundle, then the file is parsed
+as a plain-text file using Git's config parser. The key-value pairs in
+that config file are expected to describe a list of bundle URIs. If
+neither of these parse attempts succeed, then Git will report an error to
+the user that the bundle URI provided erroneous data.
+
+Any other data provided by the server is considered erroneous.
+
+Bundle Lists
+------------
+
+The Git server can advertise bundle URIs using a set of `key=value` pairs.
+A bundle URI can also serve a plain-text file in the Git config format
+containing these same `key=value` pairs. In both cases, we consider this
+to be a _bundle list_. The pairs specify information about the bundles
+that the client can use to make decisions for which bundles to download
+and which to ignore.
+
+A few keys focus on properties of the list itself.
+
+bundle.version::
+ (Required) This value provides a version number for the bundle
+ list. If a future Git change enables a feature that needs the Git
+ client to react to a new key in the bundle list file, then this version
+ will increment. The only current version number is 1, and if any other
+ value is specified then Git will fail to use this file.
+
+bundle.mode::
+ (Required) This value has one of two values: `all` and `any`. When `all`
+ is specified, then the client should expect to need all of the listed
+ bundle URIs that match their repository's requirements. When `any` is
+ specified, then the client should expect that any one of the bundle URIs
+ that match their repository's requirements will suffice. Typically, the
+ `any` option is used to list a number of different bundle servers
+ located in different geographies.
+
+bundle.heuristic::
+ If this string-valued key exists, then the bundle list is designed to
+ work well with incremental `git fetch` commands. The heuristic signals
+ that there are additional keys available for each bundle that help
+ determine which subset of bundles the client should download. The only
+ heuristic currently planned is `creationToken`.
+
+The remaining keys include an `<id>` segment which is a server-designated
+name for each available bundle. The `<id>` must contain only alphanumeric
+and `-` characters.
+
+bundle.<id>.uri::
+ (Required) This string value is the URI for downloading bundle `<id>`.
+ If the URI begins with a protocol (`http://` or `https://`) then the URI
+ is absolute. Otherwise, the URI is interpreted as relative to the URI
+ used for the bundle list. If the URI begins with `/`, then that relative
+ path is relative to the domain name used for the bundle list. (This use
+ of relative paths is intended to make it easier to distribute a set of
+ bundles across a large number of servers or CDNs with different domain
+ names.)
+
+bundle.<id>.filter::
+ This string value represents an object filter that should also appear in
+ the header of this bundle. The server uses this value to differentiate
+ different kinds of bundles from which the client can choose those that
+ match their object filters.
+
+bundle.<id>.creationToken::
+ This value is a nonnegative 64-bit integer used for sorting the bundles
+ list. This is used to download a subset of bundles during a fetch when
+ `bundle.heuristic=creationToken`.
+
+bundle.<id>.location::
+ This string value advertises a real-world location from where the bundle
+ URI is served. This can be used to present the user with an option for
+ which bundle URI to use or simply as an informative indicator of which
+ bundle URI was selected by Git. This is only valuable when
+ `bundle.mode` is `any`.
+
+Here is an example bundle list using the Git config format:
+
+ [bundle]
+ version = 1
+ mode = all
+ heuristic = creationToken
+
+ [bundle "2022-02-09-1644442601-daily"]
+ uri = https://bundles.example.com/git/git/2022-02-09-1644442601-daily.bundle
+ creationToken = 1644442601
+
+ [bundle "2022-02-02-1643842562"]
+ uri = https://bundles.example.com/git/git/2022-02-02-1643842562.bundle
+ creationToken = 1643842562
+
+ [bundle "2022-02-09-1644442631-daily-blobless"]
+ uri = 2022-02-09-1644442631-daily-blobless.bundle
+ creationToken = 1644442631
+ filter = blob:none
+
+ [bundle "2022-02-02-1643842568-blobless"]
+ uri = /git/git/2022-02-02-1643842568-blobless.bundle
+ creationToken = 1643842568
+ filter = blob:none
+
+This example uses `bundle.mode=all` as well as the
+`bundle.<id>.creationToken` heuristic. It also uses the `bundle.<id>.filter`
+options to present two parallel sets of bundles: one for full clones and
+another for blobless partial clones.
+
+Suppose that this bundle list was found at the URI
+`https://bundles.example.com/git/git/` and so the two blobless bundles have
+the following fully-expanded URIs:
+
+* `https://bundles.example.com/git/git/2022-02-09-1644442631-daily-blobless.bundle`
+* `https://bundles.example.com/git/git/2022-02-02-1643842568-blobless.bundle`
+
+Advertising Bundle URIs
+-----------------------
+
+If a user knows a bundle URI for the repository they are cloning, then
+they can specify that URI manually through a command-line option. However,
+a Git host may want to advertise bundle URIs during the clone operation,
+helping users unaware of the feature.
+
+The only thing required for this feature is that the server can advertise
+one or more bundle URIs. This advertisement takes the form of a new
+protocol v2 capability specifically for discovering bundle URIs.
+
+The client could choose an arbitrary bundle URI as an option _or_ select
+the URI with best performance by some exploratory checks. It is up to the
+bundle provider to decide if having multiple URIs is preferable to a
+single URI that is geodistributed through server-side infrastructure.
+
+Cloning with Bundle URIs
+------------------------
+
+The primary need for bundle URIs is to speed up clones. The Git client
+will interact with bundle URIs according to the following flow:
+
+1. The user specifies a bundle URI with the `--bundle-uri` command-line
+ option _or_ the client discovers a bundle list advertised by the
+ Git server.
+
+2. If the downloaded data from a bundle URI is a bundle, then the client
+ inspects the bundle headers to check that the prerequisite commit OIDs
+ are present in the client repository. If some are missing, then the
+ client delays unbundling until other bundles have been unbundled,
+ making those OIDs present. When all required OIDs are present, the
+ client unbundles that data using a refspec. The default refspec is
+ `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs
+ are stored so that later `git fetch` negotiations can communicate each
+ bundled ref as a `have`, reducing the size of the fetch over the Git
+ protocol. To allow pruning refs from this ref namespace, Git may
+ introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that
+ stale bundle refs can be deleted.
+
+3. If the file is instead a bundle list, then the client inspects the
+ `bundle.mode` to see if the list is of the `all` or `any` form.
+
+ a. If `bundle.mode=all`, then the client considers all bundle
+ URIs. The list is reduced based on the `bundle.<id>.filter` options
+ matching the client repository's partial clone filter. Then, all
+ bundle URIs are requested. If the `bundle.<id>.creationToken`
+ heuristic is provided, then the bundles are downloaded in decreasing
+ order by the creation token, stopping when a bundle has all required
+ OIDs. The bundles can then be unbundled in increasing creation token
+ order. The client stores the latest creation token as a heuristic
+ for avoiding future downloads if the bundle list does not advertise
+ bundles with larger creation tokens.
+
+ b. If `bundle.mode=any`, then the client can choose any one of the
+ bundle URIs to inspect. The client can use a variety of ways to
+ choose among these URIs. The client can also fallback to another URI
+ if the initial choice fails to return a result.
+
+Note that during a clone we expect that all bundles will be required, and
+heuristics such as `bundle.<uri>.creationToken` can be used to download
+bundles in chronological order or in parallel.
+
+If a given bundle URI is a bundle list with a `bundle.heuristic`
+value, then the client can choose to store that URI as its chosen bundle
+URI. The client can then navigate directly to that URI during later `git
+fetch` calls.
+
+When downloading bundle URIs, the client can choose to inspect the initial
+content before committing to downloading the entire content. This may
+provide enough information to determine if the URI is a bundle list or
+a bundle. In the case of a bundle, the client may inspect the bundle
+header to determine that all advertised tips are already in the client
+repository and cancel the remaining download.
+
+Fetching with Bundle URIs
+-------------------------
+
+When the client fetches new data, it can decide to fetch from bundle
+servers before fetching from the origin remote. This could be done via a
+command-line option, but it is more likely useful to use a config value
+such as the one specified during the clone.
+
+The fetch operation follows the same procedure to download bundles from a
+bundle list (although we do _not_ want to use parallel downloads here). We
+expect that the process will end when all prerequisite commit OIDs in a
+thin bundle are already in the object database.
+
+When using the `creationToken` heuristic, the client can avoid downloading
+any bundles if their creation tokens are not larger than the stored
+creation token. After fetching new bundles, Git updates this local
+creation token.
+
+If the bundle provider does not provide a heuristic, then the client
+should attempt to inspect the bundle headers before downloading the full
+bundle data in case the bundle tips already exist in the client
+repository.
+
+Error Conditions
+----------------
+
+If the Git client discovers something unexpected while downloading
+information according to a bundle URI or the bundle list found at that
+location, then Git can ignore that data and continue as if it was not
+given a bundle URI. The remote Git server is the ultimate source of truth,
+not the bundle URI.
+
+Here are a few example error conditions:
+
+* The client fails to connect with a server at the given URI or a connection
+ is lost without any chance to recover.
+
+* The client receives a 400-level response (such as `404 Not Found` or
+ `401 Not Authorized`). The client should use the credential helper to
+ find and provide a credential for the URI, but match the semantics of
+ Git's other HTTP protocols in terms of handling specific 400-level
+ errors.
+
+* The server reports any other failure response.
+
+* The client receives data that is not parsable as a bundle or bundle list.
+
+* A bundle includes a filter that does not match expectations.
+
+* The client cannot unbundle the bundles because the prerequisite commit OIDs
+ are not in the object database and there are no more bundles to download.
+
+There are also situations that could be seen as wasteful, but are not
+error conditions:
+
+* The downloaded bundles contain more information than is requested by
+ the clone or fetch request. A primary example is if the user requests
+ a clone with `--single-branch` but downloads bundles that store every
+ reachable commit from all `refs/heads/*` references. This might be
+ initially wasteful, but perhaps these objects will become reachable by
+ a later ref update that the client cares about.
+
+* A bundle download during a `git fetch` contains objects already in the
+ object database. This is probably unavoidable if we are using bundles
+ for fetches, since the client will almost always be slightly ahead of
+ the bundle servers after performing its "catch-up" fetch to the remote
+ server. This extra work is most wasteful when the client is fetching
+ much more frequently than the server is computing bundles, such as if
+ the client is using hourly prefetches with background maintenance, but
+ the server is computing bundles weekly. For this reason, the client
+ should not use bundle URIs for fetch unless the server has explicitly
+ recommended it through a `bundle.heuristic` value.
+
+Example Bundle Provider organization
+------------------------------------
+
+The bundle URI feature is intentionally designed to be flexible to
+different ways a bundle provider wants to organize the object data.
+However, it can be helpful to have a complete organization model described
+here so providers can start from that base.
+
+This example organization is a simplified model of what is used by the
+GVFS Cache Servers (see section near the end of this document) which have
+been beneficial in speeding up clones and fetches for very large
+repositories, although using extra software outside of Git.
+
+The bundle provider deploys servers across multiple geographies. Each
+server manages its own bundle set. The server can track a number of Git
+repositories, but provides a bundle list for each based on a pattern. For
+example, when mirroring a repository at `https://<domain>/<org>/<repo>`
+the bundle server could have its bundle list available at
+`https://<server-url>/<domain>/<org>/<repo>`. The origin Git server can
+list all of these servers under the "any" mode:
+
+ [bundle]
+ version = 1
+ mode = any
+
+ [bundle "eastus"]
+ uri = https://eastus.example.com/<domain>/<org>/<repo>
+
+ [bundle "europe"]
+ uri = https://europe.example.com/<domain>/<org>/<repo>
+
+ [bundle "apac"]
+ uri = https://apac.example.com/<domain>/<org>/<repo>
+
+This "list of lists" is static and only changes if a bundle server is
+added or removed.
+
+Each bundle server manages its own set of bundles. The initial bundle list
+contains only a single bundle, containing all of the objects received from
+cloning the repository from the origin server. The list uses the
+`creationToken` heuristic and a `creationToken` is made for the bundle
+based on the server's timestamp.
+
+The bundle server runs regularly-scheduled updates for the bundle list,
+such as once a day. During this task, the server fetches the latest
+contents from the origin server and generates a bundle containing the
+objects reachable from the latest origin refs, but not contained in a
+previously-computed bundle. This bundle is added to the list, with care
+that the `creationToken` is strictly greater than the previous maximum
+`creationToken`.
+
+When the bundle list grows too large, say more than 30 bundles, then the
+oldest "_N_ minus 30" bundles are combined into a single bundle. This
+bundle's `creationToken` is equal to the maximum `creationToken` among the
+merged bundles.
+
+An example bundle list is provided here, although it only has two daily
+bundles and not a full list of 30:
+
+ [bundle]
+ version = 1
+ mode = all
+ heuristic = creationToken
+
+ [bundle "2022-02-13-1644770820-daily"]
+ uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-09-1644770820-daily.bundle
+ creationToken = 1644770820
+
+ [bundle "2022-02-09-1644442601-daily"]
+ uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-09-1644442601-daily.bundle
+ creationToken = 1644442601
+
+ [bundle "2022-02-02-1643842562"]
+ uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-02-1643842562.bundle
+ creationToken = 1643842562
+
+To avoid storing and serving object data in perpetuity despite becoming
+unreachable in the origin server, this bundle merge can be more careful.
+Instead of taking an absolute union of the old bundles, instead the bundle
+can be created by looking at the newer bundles and ensuring that their
+necessary commits are all available in this merged bundle (or in another
+one of the newer bundles). This allows "expiring" object data that is not
+being used by new commits in this window of time. That data could be
+reintroduced by a later push.
+
+The intention of this data organization has two main goals. First, initial
+clones of the repository become faster by downloading precomputed object
+data from a closer source. Second, `git fetch` commands can be faster,
+especially if the client has not fetched for a few days. However, if a
+client does not fetch for 30 days, then the bundle list organization would
+cause redownloading a large amount of object data.
+
+One way to make this organization more useful to users who fetch frequently
+is to have more frequent bundle creation. For example, bundles could be
+created every hour, and then once a day those "hourly" bundles could be
+merged into a "daily" bundle. The daily bundles are merged into the
+oldest bundle after 30 days.
+
+It is recommended that this bundle strategy is repeated with the `blob:none`
+filter if clients of this repository are expecting to use blobless partial
+clones. This list of blobless bundles stays in the same list as the full
+bundles, but uses the `bundle.<id>.filter` key to separate the two groups.
+For very large repositories, the bundle provider may want to _only_ provide
+blobless bundles.
+
+Implementation Plan
+-------------------
+
+This design document is being submitted on its own as an aspirational
+document, with the goal of implementing all of the mentioned client
+features over the course of several patch series. Here is a potential
+outline for submitting these features:
+
+1. Integrate bundle URIs into `git clone` with a `--bundle-uri` option.
+ This will include a new `git fetch --bundle-uri` mode for use as the
+ implementation underneath `git clone`. The initial version here will
+ expect a single bundle at the given URI.
+
+2. Implement the ability to parse a bundle list from a bundle URI and
+ update the `git fetch --bundle-uri` logic to properly distinguish
+ between `bundle.mode` options. Specifically design the feature so
+ that the config format parsing feeds a list of key-value pairs into the
+ bundle list logic.
+
+3. Create the `bundle-uri` protocol v2 command so Git servers can advertise
+ bundle URIs using the key-value pairs. Plug into the existing key-value
+ input to the bundle list logic. Allow `git clone` to discover these
+ bundle URIs and bootstrap the client repository from the bundle data.
+ (This choice is an opt-in via a config option and a command-line
+ option.)
+
+4. Allow the client to understand the `bundle.flag=forFetch` configuration
+ and the `bundle.<id>.creationToken` heuristic. When `git clone`
+ discovers a bundle URI with `bundle.flag=forFetch`, it configures the
+ client repository to check that bundle URI during later `git fetch <remote>`
+ commands.
+
+5. Allow clients to discover bundle URIs during `git fetch` and configure
+ a bundle URI for later fetches if `bundle.flag=forFetch`.
+
+6. Implement the "inspect headers" heuristic to reduce data downloads when
+ the `bundle.<id>.creationToken` heuristic is not available.
+
+As these features are reviewed, this plan might be updated. We also expect
+that new designs will be discovered and implemented as this feature
+matures and becomes used in real-world scenarios.
+
+Related Work: Packfile URIs
+---------------------------
+
+The Git protocol already has a capability where the Git server can list
+a set of URLs along with the packfile response when serving a client
+request. The client is then expected to download the packfiles at those
+locations in order to have a complete understanding of the response.
+
+This mechanism is used by the Gerrit server (implemented with JGit) and
+has been effective at reducing CPU load and improving user performance for
+clones.
+
+A major downside to this mechanism is that the origin server needs to know
+_exactly_ what is in those packfiles, and the packfiles need to be available
+to the user for some time after the server has responded. This coupling
+between the origin and the packfile data is difficult to manage.
+
+Further, this implementation is extremely hard to make work with fetches.
+
+Related Work: GVFS Cache Servers
+--------------------------------
+
+The GVFS Protocol [2] is a set of HTTP endpoints designed independently of
+the Git project before Git's partial clone was created. One feature of this
+protocol is the idea of a "cache server" which can be colocated with build
+machines or developer offices to transfer Git data without overloading the
+central server.
+
+The endpoint that VFS for Git is famous for is the `GET /gvfs/objects/{oid}`
+endpoint, which allows downloading an object on-demand. This is a critical
+piece of the filesystem virtualization of that product.
+
+However, a more subtle need is the `GET /gvfs/prefetch?lastPackTimestamp=<t>`
+endpoint. Given an optional timestamp, the cache server responds with a list
+of precomputed packfiles containing the commits and trees that were introduced
+in those time intervals.
+
+The cache server computes these "prefetch" packfiles using the following
+strategy:
+
+1. Every hour, an "hourly" pack is generated with a given timestamp.
+2. Nightly, the previous 24 hourly packs are rolled up into a "daily" pack.
+3. Nightly, all prefetch packs more than 30 days old are rolled up into
+ one pack.
+
+When a user runs `gvfs clone` or `scalar clone` against a repo with cache
+servers, the client requests all prefetch packfiles, which is at most
+`24 + 30 + 1` packfiles downloading only commits and trees. The client
+then follows with a request to the origin server for the references, and
+attempts to checkout that tip reference. (There is an extra endpoint that
+helps get all reachable trees from a given commit, in case that commit
+was not already in a prefetch packfile.)
+
+During a `git fetch`, a hook requests the prefetch endpoint using the
+most-recent timestamp from a previously-downloaded prefetch packfile.
+Only the list of packfiles with later timestamps are downloaded. Most
+users fetch hourly, so they get at most one hourly prefetch pack. Users
+whose machines have been off or otherwise have not fetched in over 30 days
+might redownload all prefetch packfiles. This is rare.
+
+It is important to note that the clients always contact the origin server
+for the refs advertisement, so the refs are frequently "ahead" of the
+prefetched pack data. The missing objects are downloaded on-demand using
+the `GET gvfs/objects/{oid}` requests, when needed by a command such as
+`git checkout` or `git log`. Some Git optimizations disable checks that
+would cause these on-demand downloads to be too aggressive.
+
+See Also
+--------
+
+[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/
+ An earlier RFC for a bundle URI feature.
+
+[2] https://github.com/microsoft/VFSForGit/blob/master/Protocol.md
+ The GVFS Protocol
diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt
index f05e7bd..86fed0d 100644
--- a/Documentation/technical/commit-graph.txt
+++ b/Documentation/technical/commit-graph.txt
@@ -1,4 +1,4 @@
-Git Commit Graph Design Notes
+Git Commit-Graph Design Notes
=============================
Git walks the commit graph for many reasons, including:
@@ -17,7 +17,7 @@ There are two main costs here:
The commit-graph file is a supplemental data structure that accelerates
commit graph walks. If a user downgrades or disables the 'core.commitGraph'
-config setting, then the existing ODB is sufficient. The file is stored
+config setting, then the existing object database is sufficient. The file is stored
as "commit-graph" either in the .git/objects/info directory or in the info
directory of an alternate.
@@ -40,7 +40,7 @@ Values 1-4 satisfy the requirements of parse_commit_gently().
There are two definitions of generation number:
1. Corrected committer dates (generation number v2)
-2. Topological levels (generation nummber v1)
+2. Topological levels (generation number v1)
Define "corrected committer date" of a commit recursively as follows:
@@ -48,7 +48,7 @@ Define "corrected committer date" of a commit recursively as follows:
equal to its committer date.
* A commit with at least one parent has corrected committer date equal to
- the maximum of its commiter date and one more than the largest corrected
+ the maximum of its committer date and one more than the largest corrected
committer date among its parents.
* As a special case, a root commit with timestamp zero has corrected commit
@@ -95,7 +95,7 @@ with default order), but is not used when the topological order is
required (such as merge base calculations, "git log --graph").
In practice, we expect some commits to be created recently and not stored
-in the commit graph. We can treat these commits as having "infinite"
+in the commit-graph. We can treat these commits as having "infinite"
generation number and walk until reaching commits with known generation
number.
@@ -149,7 +149,7 @@ Design Details
helpful for these clones, anyway. The commit-graph will not be read or
written when shallow commits are present.
-Commit Graphs Chains
+Commit-Graphs Chains
--------------------
Typically, repos grow with near-constant velocity (commits per day). Over time,
diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/technical/cruft-packs.txt
deleted file mode 100644
index d81f3a8..0000000
--- a/Documentation/technical/cruft-packs.txt
+++ /dev/null
@@ -1,123 +0,0 @@
-= Cruft packs
-
-The cruft packs feature offer an alternative to Git's traditional mechanism of
-removing unreachable objects. This document provides an overview of Git's
-pruning mechanism, and how a cruft pack can be used instead to accomplish the
-same.
-
-== Background
-
-To remove unreachable objects from your repository, Git offers `git repack -Ad`
-(see linkgit:git-repack[1]). Quoting from the documentation:
-
-[quote]
-[...] unreachable objects in a previous pack become loose, unpacked objects,
-instead of being left in the old pack. [...] loose unreachable objects will be
-pruned according to normal expiry rules with the next 'git gc' invocation.
-
-Unreachable objects aren't removed immediately, since doing so could race with
-an incoming push which may reference an object which is about to be deleted.
-Instead, those unreachable objects are stored as loose objects and stay that way
-until they are older than the expiration window, at which point they are removed
-by linkgit:git-prune[1].
-
-Git must store these unreachable objects loose in order to keep track of their
-per-object mtimes. If these unreachable objects were written into one big pack,
-then either freshening that pack (because an object contained within it was
-re-written) or creating a new pack of unreachable objects would cause the pack's
-mtime to get updated, and the objects within it would never leave the expiration
-window. Instead, objects are stored loose in order to keep track of the
-individual object mtimes and avoid a situation where all cruft objects are
-freshened at once.
-
-This can lead to undesirable situations when a repository contains many
-unreachable objects which have not yet left the grace period. Having large
-directories in the shards of `.git/objects` can lead to decreased performance in
-the repository. But given enough unreachable objects, this can lead to inode
-starvation and degrade the performance of the whole system. Since we
-can never pack those objects, these repositories often take up a large amount of
-disk space, since we can only zlib compress them, but not store them in delta
-chains.
-
-== Cruft packs
-
-A cruft pack eliminates the need for storing unreachable objects in a loose
-state by including the per-object mtimes in a separate file alongside a single
-pack containing all loose objects.
-
-A cruft pack is written by `git repack --cruft` when generating a new pack.
-linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`
-is a classic all-into-one repack, meaning that everything in the resulting pack is
-reachable, and everything else is unreachable. Once written, the `--cruft`
-option instructs `git repack` to generate another pack containing only objects
-not packed in the previous step (which equates to packing all unreachable
-objects together). This progresses as follows:
-
- 1. Enumerate every object, marking any object which is (a) not contained in a
- kept-pack, and (b) whose mtime is within the grace period as a traversal
- tip.
-
- 2. Perform a reachability traversal based on the tips gathered in the previous
- step, adding every object along the way to the pack.
-
- 3. Write the pack out, along with a `.mtimes` file that records the per-object
- timestamps.
-
-This mode is invoked internally by linkgit:git-repack[1] when instructed to
-write a cruft pack. Crucially, the set of in-core kept packs is exactly the set
-of packs which will not be deleted by the repack; in other words, they contain
-all of the repository's reachable objects.
-
-When a repository already has a cruft pack, `git repack --cruft` typically only
-adds objects to it. An exception to this is when `git repack` is given the
-`--cruft-expiration` option, which allows the generated cruft pack to omit
-expired objects instead of waiting for linkgit:git-gc[1] to expire those objects
-later on.
-
-It is linkgit:git-gc[1] that is typically responsible for removing expired
-unreachable objects.
-
-== Caution for mixed-version environments
-
-Repositories that have cruft packs in them will continue to work with any older
-version of Git. Note, however, that previous versions of Git which do not
-understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
-all of the objects in it. In other words, do not expect older (pre-cruft pack)
-versions of Git to interpret or even read the contents of the `.mtimes` file.
-
-Note that having mixed versions of Git GC-ing the same repository can lead to
-unreachable objects never being completely pruned. This can happen under the
-following circumstances:
-
- - An older version of Git running GC explodes the contents of an existing
- cruft pack loose, using the cruft pack's mtime.
- - A newer version running GC collects those loose objects into a cruft pack,
- where the .mtime file reflects the loose object's actual mtimes, but the
- cruft pack mtime is "now".
-
-Repeating this process will lead to unreachable objects not getting pruned as a
-result of repeatedly resetting the objects' mtimes to the present time.
-
-If you are GC-ing repositories in a mixed version environment, consider omitting
-the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
-leaving the `gc.cruftPacks` configuration unset until all writers understand
-cruft packs.
-
-== Alternatives
-
-Notable alternatives to this design include:
-
- - The location of the per-object mtime data, and
- - Storing unreachable objects in multiple cruft packs.
-
-On the location of mtime data, a new auxiliary file tied to the pack was chosen
-to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
-support for optional chunks of data, it may make sense to consolidate the
-`.mtimes` format into the `.idx` itself.
-
-Storing unreachable objects among multiple cruft packs (e.g., creating a new
-cruft pack during each repacking operation including only unreachable objects
-which aren't already stored in an earlier cruft pack) is significantly more
-complicated to construct, and so aren't pursued here. The obvious drawback to
-the current implementation is that the entire cruft pack must be re-written from
-scratch.
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index 260224b..e2ac36d 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -205,7 +205,7 @@ SHA-1 content.
Object storage
~~~~~~~~~~~~~~
Loose objects use zlib compression and packed objects use the packed
-format described in Documentation/technical/pack-format.txt, just like
+format described in linkgit:gitformat-pack[5], just like
today. The content that is compressed and stored uses SHA-256 content
instead of SHA-1 content.
diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt
index aa0aa9a..6f33654 100644
--- a/Documentation/technical/long-running-process-protocol.txt
+++ b/Documentation/technical/long-running-process-protocol.txt
@@ -3,7 +3,7 @@ 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)
+communication is in pkt-line format (see linkgit:gitprotocol-common[5])
over standard input and standard output.
Handshake
diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt
index 1eb525f..9d453d4 100644
--- a/Documentation/technical/packfile-uri.txt
+++ b/Documentation/technical/packfile-uri.txt
@@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section
directly before the `packfile` section (right after `wanted-refs` if it is
sent) containing URIs of any of the given protocols. The URIs point to
packfiles that use only features that the client has declared that it supports
-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of
+(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of
this section.
Clients should then download and index all the given URIs (in addition to
diff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt
index e790258..47c9b61 100644
--- a/Documentation/technical/parallel-checkout.txt
+++ b/Documentation/technical/parallel-checkout.txt
@@ -56,7 +56,7 @@ Rejected Multi-Threaded Solution
The most "straightforward" implementation would be to spread the set of
to-be-updated cache entries across multiple threads. But due to the
-thread-unsafe functions in the ODB code, we would have to use locks to
+thread-unsafe functions in the object database code, we would have to use locks to
coordinate the parallel operation. An early prototype of this solution
showed that the multi-threaded checkout would bring performance
improvements over the sequential code, but there was still too much lock
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index 99f0eb3..92fcee2 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -79,7 +79,7 @@ Design Details
upload-pack negotiation.
+
This uses the existing capability discovery mechanism.
-See "filter" in Documentation/technical/pack-protocol.txt.
+See "filter" in linkgit:gitprotocol-pack[5].
- Clients pass a "filter-spec" to clone and fetch which is passed to the
server to request filtering during packfile construction.
diff --git a/Documentation/technical/remembering-renames.txt b/Documentation/technical/remembering-renames.txt
index 2fd5cc8..1e34d91 100644
--- a/Documentation/technical/remembering-renames.txt
+++ b/Documentation/technical/remembering-renames.txt
@@ -20,7 +20,7 @@ Outline:
3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also
a rename on MERGE_SIDE1 for the next pick
- 4. A detailed description of the the counter-examples to #3.
+ 4. A detailed description of the counter-examples to #3.
5. Why the special cases in #4 are still fully reasonable to use to pair
up files for three-way content merging in the merge machinery, and why
@@ -407,7 +407,7 @@ considered to be "irrelevant". See for example the following commits:
no longer relevant", 2021-03-13)
Relevance is always determined by what the _other_ side of history has
-done, in terms of modifing a file that our side renamed, or adding a
+done, in terms of modifying a file that our side renamed, or adding a
file to a directory which our side renamed. This means that a path
that is "irrelevant" when picking the first commit of a series in a
rebase or cherry-pick, may suddenly become "relevant" when picking the
diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt
index 7844ef3..8ef664b 100644
--- a/Documentation/technical/repository-version.txt
+++ b/Documentation/technical/repository-version.txt
@@ -82,9 +82,9 @@ When the config key `extensions.preciousObjects` is set to `true`,
objects in the repository MUST NOT be deleted (e.g., by `git-prune` or
`git repack -d`).
-==== `partialclone`
+==== `partialClone`
-When the config key `extensions.partialclone` is set, it indicates
+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"
diff --git a/Documentation/technical/scalar.txt b/Documentation/technical/scalar.txt
index 08bc09c..921cb10 100644
--- a/Documentation/technical/scalar.txt
+++ b/Documentation/technical/scalar.txt
@@ -64,64 +64,3 @@ some "global" `git` options (e.g., `-c` and `-C`).
Because `scalar` is not invoked as a Git subcommand (like `git scalar`), it is
built and installed as its own executable in the `bin/` directory, alongside
`git`, `git-gui`, etc.
-
-Roadmap
--------
-
-NOTE: this section will be removed once the remaining tasks outlined in this
-roadmap are complete.
-
-Scalar is a large enough project that it is being upstreamed incrementally,
-living in `contrib/` until it is feature-complete. So far, the following patch
-series have been accepted:
-
-- `scalar-the-beginning`: The initial patch series which sets up
- `contrib/scalar/` and populates it with a minimal `scalar` command that
- demonstrates the fundamental ideas.
-
-- `scalar-c-and-C`: The `scalar` command learns about two options that can be
- specified before the command, `-c <key>=<value>` and `-C <directory>`.
-
-- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand.
-
-Roughly speaking (and subject to change), the following series are needed to
-"finish" this initial version of Scalar:
-
-- Finish Scalar features: Enable the built-in FSMonitor in Scalar enlistments
- and implement `scalar help`. At the end of this series, Scalar should be
- feature-complete from the perspective of a user.
-
-- Generalize features not specific to Scalar: In the spirit of making Scalar
- configure only what is needed for large repo performance, move common
- utilities into other parts of Git. Some of this will be internal-only, but one
- major change will be generalizing `scalar diagnose` for use with any Git
- repository.
-
-- Move Scalar to toplevel: Move Scalar out of `contrib/` and into the root of
- `git`, including updates to build and install it with the rest of Git. This
- change will incorporate Scalar into the Git CI and test framework, as well as
- expand regression and performance testing to ensure the tool is stable.
-
-Finally, there are two additional patch series that exist in Microsoft's fork of
-Git, but there is no current plan to upstream them. There are some interesting
-ideas there, but the implementation is too specific to Azure Repos and/or VFS
-for Git to be of much help in general.
-
-These still exist mainly because the GVFS protocol is what Azure Repos has
-instead of partial clone, while Git is focused on improving partial clone:
-
-- `scalar-with-gvfs`: The primary purpose of this patch series is to support
- existing Scalar users whose repositories are hosted in Azure Repos (which does
- not support Git's partial clones, but supports its predecessor, the GVFS
- protocol, which is used by Scalar to emulate the partial clone).
-
- Since the GVFS protocol will never be supported by core Git, this patch series
- will remain in Microsoft's fork of Git.
-
-- `run-scalar-functional-tests`: The Scalar project developed a quite
- comprehensive set of integration tests (or, "Functional Tests"). They are the
- sole remaining part of the original C#-based Scalar project, and this patch
- adds a GitHub workflow that runs them all.
-
- Since the tests partially depend on features that are only provided in the
- `scalar-with-gvfs` patch series, this patch cannot be upstreamed.
diff --git a/Documentation/technical/sparse-checkout.txt b/Documentation/technical/sparse-checkout.txt
new file mode 100644
index 0000000..fa0d01c
--- /dev/null
+++ b/Documentation/technical/sparse-checkout.txt
@@ -0,0 +1,1103 @@
+Table of contents:
+
+ * Terminology
+ * Purpose of sparse-checkouts
+ * Usecases of primary concern
+ * Oversimplified mental models ("Cliff Notes" for this document!)
+ * Desired behavior
+ * Behavior classes
+ * Subcommand-dependent defaults
+ * Sparse specification vs. sparsity patterns
+ * Implementation Questions
+ * Implementation Goals/Plans
+ * Known bugs
+ * Reference Emails
+
+
+=== Terminology ===
+
+cone mode: one of two modes for specifying the desired subset of files
+ in a sparse-checkout. In cone-mode, the user specifies
+ directories (getting both everything under that directory as
+ well as everything in leading directories), while in non-cone
+ mode, the user specifies gitignore-style patterns. Controlled
+ by the --[no-]cone option to sparse-checkout init|set.
+
+SKIP_WORKTREE: When tracked files do not match the sparse specification and
+ are removed from the working tree, the file in the index is marked
+ with a SKIP_WORKTREE bit. Note that if a tracked file has the
+ SKIP_WORKTREE bit set but the file is later written by the user to
+ the working tree anyway, the SKIP_WORKTREE bit will be cleared at
+ the beginning of any subsequent Git operation.
+
+ Most sparse checkout users are unaware of this implementation
+ detail, and the term should generally be avoided in user-facing
+ descriptions and command flags. Unfortunately, prior to the
+ `sparse-checkout` subcommand this low-level detail was exposed,
+ and as of time of writing, is still exposed in various places.
+
+sparse-checkout: a subcommand in git used to reduce the files present in
+ the working tree to a subset of all tracked files. Also, the
+ name of the file in the $GIT_DIR/info directory used to track
+ the sparsity patterns corresponding to the user's desired
+ subset.
+
+sparse cone: see cone mode
+
+sparse directory: An entry in the index corresponding to a directory, which
+ appears in the index instead of all the files under that directory
+ that would normally appear. See also sparse-index. Something that
+ can cause confusion is that the "sparse directory" does NOT match
+ the sparse specification, i.e. the directory is NOT present in the
+ working tree. May be renamed in the future (e.g. to "skipped
+ directory").
+
+sparse index: A special mode for sparse-checkout that also makes the
+ index sparse by recording a directory entry in lieu of all the
+ files underneath that directory (thus making that a "skipped
+ directory" which unfortunately has also been called a "sparse
+ directory"), and does this for potentially multiple
+ directories. Controlled by the --[no-]sparse-index option to
+ init|set|reapply.
+
+sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to
+ define the set of files of interest. A warning: It is easy to
+ over-use this term (or the shortened "patterns" term), for two
+ reasons: (1) users in cone mode specify directories rather than
+ patterns (their directories are transformed into patterns, but
+ users may think you are talking about non-cone mode if you use the
+ word "patterns"), and (b) the sparse specification might
+ transiently differ in the working tree or index from the sparsity
+ patterns (see "Sparse specification vs. sparsity patterns").
+
+sparse specification: The set of paths in the user's area of focus. This
+ is typically just the tracked files that match the sparsity
+ patterns, but the sparse specification can temporarily differ and
+ include additional files. (See also "Sparse specification
+ vs. sparsity patterns")
+
+ * When working with history, the sparse specification is exactly
+ the set of files matching the sparsity patterns.
+ * When interacting with the working tree, the sparse specification
+ is the set of tracked files with a clear SKIP_WORKTREE bit or
+ tracked files present in the working copy.
+ * When modifying or showing results from the index, the sparse
+ specification is the set of files with a clear SKIP_WORKTREE bit
+ or that differ in the index from HEAD.
+ * If working with the index and the working copy, the sparse
+ specification is the union of the paths from above.
+
+vivifying: When a command restores a tracked file to the working tree (and
+ hopefully also clears the SKIP_WORKTREE bit in the index for that
+ file), this is referred to as "vivifying" the file.
+
+
+=== Purpose of sparse-checkouts ===
+
+sparse-checkouts exist to allow users to work with a subset of their
+files.
+
+You can think of sparse-checkouts as subdividing "tracked" files into two
+categories -- a sparse subset, and all the rest. Implementationally, we
+mark "all the rest" in the index with a SKIP_WORKTREE bit and leave them
+out of the working tree. The SKIP_WORKTREE files are still tracked, just
+not present in the working tree.
+
+In the past, sparse-checkouts were defined by "SKIP_WORKTREE means the file
+is missing from the working tree but pretend the file contents match HEAD".
+That was not only bogus (it actually meant the file missing from the
+working tree matched the index rather than HEAD), but it was also a
+low-level detail which only provided decent behavior for a few commands.
+There were a surprising number of ways in which that guiding principle gave
+command results that violated user expectations, and as such was a bad
+mental model. However, it persisted for many years and may still be found
+in some corners of the code base.
+
+Anyway, the idea of "working with a subset of files" is simple enough, but
+there are multiple different high-level usecases which affect how some Git
+subcommands should behave. Further, even if we only considered one of
+those usecases, sparse-checkouts can modify different subcommands in over a
+half dozen different ways. Let's start by considering the high level
+usecases:
+
+ A) Users are _only_ interested in the sparse portion of the repo
+
+ A*) Users are _only_ interested in the sparse portion of the repo
+ that they have downloaded so far
+
+ B) Users want a sparse working tree, but are working in a larger whole
+
+ C) sparse-checkout is a behind-the-scenes implementation detail allowing
+ Git to work with a specially crafted in-house virtual file system;
+ users are actually working with a "full" working tree that is
+ lazily populated, and sparse-checkout helps with the lazy population
+ piece.
+
+It may be worth explaining each of these in a bit more detail:
+
+
+ (Behavior A) Users are _only_ interested in the sparse portion of the repo
+
+These folks might know there are other things in the repository, but
+don't care. They are uninterested in other parts of the repository, and
+only want to know about changes within their area of interest. Showing
+them other files from history (e.g. from diff/log/grep/etc.) is a
+usability annoyance, potentially a huge one since other changes in
+history may dwarf the changes they are interested in.
+
+Some of these users also arrive at this usecase from wanting to use partial
+clones together with sparse checkouts (in a way where they have downloaded
+blobs within the sparse specification) and do disconnected development.
+Not only do these users generally not care about other parts of the
+repository, but consider it a blocker for Git commands to try to operate on
+those. If commands attempt to access paths in history outside the sparsity
+specification, then the partial clone will attempt to download additional
+blobs on demand, fail, and then fail the user's command. (This may be
+unavoidable in some cases, e.g. when `git merge` has non-trivial changes to
+reconcile outside the sparse specification, but we should limit how often
+users are forced to connect to the network.)
+
+Also, even for users using partial clones that do not mind being
+always connected to the network, the need to download blobs as
+side-effects of various other commands (such as the printed diffstat
+after a merge or pull) can lead to worries about local repository size
+growing unnecessarily[10].
+
+ (Behavior A*) Users are _only_ interested in the sparse portion of the repo
+ that they have downloaded so far (a variant on the first usecase)
+
+This variant is driven by folks who using partial clones together with
+sparse checkouts and do disconnected development (so far sounding like a
+subset of behavior A users) and doing so on very large repositories. The
+reason for yet another variant is that downloading even just the blobs
+through history within their sparse specification may be too much, so they
+only download some. They would still like operations to succeed without
+network connectivity, though, so things like `git log -S${SEARCH_TERM} -p`
+or `git grep ${SEARCH_TERM} OLDREV ` would need to be prepared to provide
+partial results that depend on what happens to have been downloaded.
+
+This variant could be viewed as Behavior A with the sparse specification
+for history querying operations modified from "sparsity patterns" to
+"sparsity patterns limited to the blobs we have already downloaded".
+
+ (Behavior B) Users want a sparse working tree, but are working in a
+ larger whole
+
+Stolee described this usecase this way[11]:
+
+"I'm also focused on users that know that they are a part of a larger
+whole. They know they are operating on a large repository but focus on
+what they need to contribute their part. I expect multiple "roles" to
+use very different, almost disjoint parts of the codebase. Some other
+"architect" users operate across the entire tree or hop between different
+sections of the codebase as necessary. In this situation, I'm wary of
+scoping too many features to the sparse-checkout definition, especially
+"git log," as it can be too confusing to have their view of the codebase
+depend on your "point of view."
+
+People might also end up wanting behavior B due to complex inter-project
+dependencies. The initial attempts to use sparse-checkouts usually involve
+the directories you are directly interested in plus what those directories
+depend upon within your repository. But there's a monkey wrench here: if
+you have integration tests, they invert the hierarchy: to run integration
+tests, you need not only what you are interested in and its in-tree
+dependencies, you also need everything that depends upon what you are
+interested in or that depends upon one of your dependencies...AND you need
+all the in-tree dependencies of that expanded group. That can easily
+change your sparse-checkout into a nearly dense one.
+
+Naturally, that tends to kill the benefits of sparse-checkouts. There are
+a couple solutions to this conundrum: either avoid grabbing in-repo
+dependencies (maybe have built versions of your in-repo dependencies pulled
+from a CI cache somewhere), or say that users shouldn't run integration
+tests directly and instead do it on the CI server when they submit a code
+review. Or do both. Regardless of whether you stub out your in-repo
+dependencies or stub out the things that depend upon you, there is
+certainly a reason to want to query and be aware of those other stubbed-out
+parts of the repository, particularly when the dependencies are complex or
+change relatively frequently. Thus, for such uses, sparse-checkouts can be
+used to limit what you directly build and modify, but these users do not
+necessarily want their sparse checkout paths to limit their queries of
+versions in history.
+
+Some people may also be interested in behavior B over behavior A simply as
+a performance workaround: if they are using non-cone mode, then they have
+to deal with its inherent quadratic performance problems. In that mode,
+every operation that checks whether paths match the sparsity specification
+can be expensive. As such, these users may only be willing to pay for
+those expensive checks when interacting with the working copy, and may
+prefer getting "unrelated" results from their history queries over having
+slow commands.
+
+ (Behavior C) sparse-checkout is an implementational detail supporting a
+ special VFS.
+
+This usecase goes slightly against the traditional definition of
+sparse-checkout in that it actually tries to present a full or dense
+checkout to the user. However, this usecase utilizes the same underlying
+technical underpinnings in a new way which does provide some performance
+advantages to users. The basic idea is that a company can have an in-house
+Git-aware Virtual File System which pretends all files are present in the
+working tree, by intercepting all file system accesses and using those to
+fetch and write accessed files on demand via partial clones. The VFS uses
+sparse-checkout to prevent Git from writing or paying attention to many
+files, and manually updates the sparse checkout patterns itself based on
+user access and modification of files in the working tree. See commit
+ecc7c8841d ("repo_read_index: add config to expect files outside sparse
+patterns", 2022-02-25) and the link at [17] for a more detailed description
+of such a VFS.
+
+The biggest difference here is that users are completely unaware that the
+sparse-checkout machinery is even in use. The sparse patterns are not
+specified by the user but rather are under the complete control of the VFS
+(and the patterns are updated frequently and dynamically by it). The user
+will perceive the checkout as dense, and commands should thus behave as if
+all files are present.
+
+
+=== Usecases of primary concern ===
+
+Most of the rest of this document will focus on Behavior A and Behavior
+B. Some notes about the other two cases and why we are not focusing on
+them:
+
+ (Behavior A*)
+
+Supporting this usecase is estimated to be difficult and a lot of work.
+There are no plans to implement it currently, but it may be a potential
+future alternative. Knowing about the existence of additional alternatives
+may affect our choice of command line flags (e.g. if we need tri-state or
+quad-state flags rather than just binary flags), so it was still important
+to at least note.
+
+Further, I believe the descriptions below for Behavior A are probably still
+valid for this usecase, with the only exception being that it redefines the
+sparse specification to restrict it to already-downloaded blobs. The hard
+part is in making commands capable of respecting that modified definition.
+
+ (Behavior C)
+
+This usecase violates some of the early sparse-checkout documented
+assumptions (since files marked as SKIP_WORKTREE will be displayed to users
+as present in the working tree). That violation may mean various
+sparse-checkout related behaviors are not well suited to this usecase and
+we may need tweaks -- to both documentation and code -- to handle it.
+However, this usecase is also perhaps the simplest model to support in that
+everything behaves like a dense checkout with a few exceptions (e.g. branch
+checkouts and switches write fewer things, knowing the VFS will lazily
+write the rest on an as-needed basis).
+
+Since there is no publically available VFS-related code for folks to try,
+the number of folks who can test such a usecase is limited.
+
+The primary reason to note the Behavior C usecase is that as we fix things
+to better support Behaviors A and B, there may be additional places where
+we need to make tweaks allowing folks in this usecase to get the original
+non-sparse treatment. For an example, see ecc7c8841d ("repo_read_index:
+add config to expect files outside sparse patterns", 2022-02-25). The
+secondary reason to note Behavior C, is so that folks taking advantage of
+Behavior C do not assume they are part of the Behavior B camp and propose
+patches that break things for the real Behavior B folks.
+
+
+=== Oversimplified mental models ===
+
+An oversimplification of the differences in the above behaviors is:
+
+ Behavior A: Restrict worktree and history operations to sparse specification
+ Behavior B: Restrict worktree operations to sparse specification; have any
+ history operations work across all files
+ Behavior C: Do not restrict either worktree or history operations to the
+ sparse specification...with the exception of branch checkouts or
+ switches which avoid writing files that will match the index so
+ they can later lazily be populated instead.
+
+
+=== Desired behavior ===
+
+As noted previously, despite the simple idea of just working with a subset
+of files, there are a range of different behavioral changes that need to be
+made to different subcommands to work well with such a feature. See
+[1,2,3,4,5,6,7,8,9,10] for various examples. In particular, at [2], we saw
+that mere composition of other commands that individually worked correctly
+in a sparse-checkout context did not imply that the higher level command
+would work correctly; it sometimes requires further tweaks. So,
+understanding these differences can be beneficial.
+
+* Commands behaving the same regardless of high-level use-case
+
+ * commands that only look at files within the sparsity specification
+
+ * diff (without --cached or REVISION arguments)
+ * grep (without --cached or REVISION arguments)
+ * diff-files
+
+ * commands that restore files to the working tree that match sparsity
+ patterns, and remove unmodified files that don't match those
+ patterns:
+
+ * switch
+ * checkout (the switch-like half)
+ * read-tree
+ * reset --hard
+
+ * commands that write conflicted files to the working tree, but otherwise
+ will omit writing files to the working tree that do not match the
+ sparsity patterns:
+
+ * merge
+ * rebase
+ * cherry-pick
+ * revert
+
+ * `am` and `apply --cached` should probably be in this section but
+ are buggy (see the "Known bugs" section below)
+
+ The behavior for these commands somewhat depends upon the merge
+ strategy being used:
+ * `ort` behaves as described above
+ * `recursive` tries to not vivify files unnecessarily, but does sometimes
+ vivify files without conflicts.
+ * `octopus` and `resolve` will always vivify any file changed in the merge
+ relative to the first parent, which is rather suboptimal.
+
+ It is also important to note that these commands WILL update the index
+ outside the sparse specification relative to when the operation began,
+ BUT these commands often make a commit just before or after such that
+ by the end of the operation there is no change to the index outside the
+ sparse specification. Of course, if the operation hits conflicts or
+ does not make a commit, then these operations clearly can modify the
+ index outside the sparse specification.
+
+ Finally, it is important to note that at least the first four of these
+ commands also try to remove differences between the sparse
+ specification and the sparsity patterns (much like the commands in the
+ previous section).
+
+ * commands that always ignore sparsity since commits must be full-tree
+
+ * archive
+ * bundle
+ * commit
+ * format-patch
+ * fast-export
+ * fast-import
+ * commit-tree
+
+ * commands that write any modified file to the working tree (conflicted
+ or not, and whether those paths match sparsity patterns or not):
+
+ * stash
+ * apply (without `--index` or `--cached`)
+
+* Commands that may slightly differ for behavior A vs. behavior B:
+
+ Commands in this category behave mostly the same between the two
+ behaviors, but may differ in verbosity and types of warning and error
+ messages.
+
+ * commands that make modifications to which files are tracked:
+ * add
+ * rm
+ * mv
+ * update-index
+
+ The fact that files can move between the 'tracked' and 'untracked'
+ categories means some commands will have to treat untracked files
+ differently. But if we have to treat untracked files differently,
+ then additional commands may also need changes:
+
+ * status
+ * clean
+
+ In particular, `status` may need to report any untracked files outside
+ the sparsity specification as an erroneous condition (especially to
+ avoid the user trying to `git add` them, forcing `git add` to display
+ an error).
+
+ It's not clear to me exactly how (or even if) `clean` would change,
+ but it's the other command that also affects untracked files.
+
+ `update-index` may be slightly special. Its --[no-]skip-worktree flag
+ may need to ignore the sparse specification by its nature. Also, its
+ current --[no-]ignore-skip-worktree-entries default is totally bogus.
+
+ * commands for manually tweaking paths in both the index and the working tree
+ * `restore`
+ * the restore-like half of `checkout`
+
+ These commands should be similar to add/rm/mv in that they should
+ only operate on the sparse specification by default, and require a
+ special flag to operate on all files.
+
+ Also, note that these commands currently have a number of issues (see
+ the "Known bugs" section below)
+
+* Commands that significantly differ for behavior A vs. behavior B:
+
+ * commands that query history
+ * diff (with --cached or REVISION arguments)
+ * grep (with --cached or REVISION arguments)
+ * show (when given commit arguments)
+ * blame (only matters when one or more -C flags are passed)
+ * and annotate
+ * log
+ * whatchanged
+ * ls-files
+ * diff-index
+ * diff-tree
+ * ls-tree
+
+ Note: for log and whatchanged, revision walking logic is unaffected
+ but displaying of patches is affected by scoping the command to the
+ sparse-checkout. (The fact that revision walking is unaffected is
+ why rev-list, shortlog, show-branch, and bisect are not in this
+ list.)
+
+ ls-files may be slightly special in that e.g. `git ls-files -t` is
+ often used to see what is sparse and what is not. Perhaps -t should
+ always work on the full tree?
+
+* Commands I don't know how to classify
+
+ * range-diff
+
+ Is this like `log` or `format-patch`?
+
+ * cherry
+
+ See range-diff
+
+* Commands unaffected by sparse-checkouts
+
+ * shortlog
+ * show-branch
+ * rev-list
+ * bisect
+
+ * branch
+ * describe
+ * fetch
+ * gc
+ * init
+ * maintenance
+ * notes
+ * pull (merge & rebase have the necessary changes)
+ * push
+ * submodule
+ * tag
+
+ * config
+ * filter-branch (works in separate checkout without sparse-checkout setup)
+ * pack-refs
+ * prune
+ * remote
+ * repack
+ * replace
+
+ * bugreport
+ * count-objects
+ * fsck
+ * gitweb
+ * help
+ * instaweb
+ * merge-tree (doesn't touch worktree or index, and merges always compute full-tree)
+ * rerere
+ * verify-commit
+ * verify-tag
+
+ * commit-graph
+ * hash-object
+ * index-pack
+ * mktag
+ * mktree
+ * multi-pack-index
+ * pack-objects
+ * prune-packed
+ * symbolic-ref
+ * unpack-objects
+ * update-ref
+ * write-tree (operates on index, possibly optimized to use sparse dir entries)
+
+ * for-each-ref
+ * get-tar-commit-id
+ * ls-remote
+ * merge-base (merges are computed full tree, so merge base should be too)
+ * name-rev
+ * pack-redundant
+ * rev-parse
+ * show-index
+ * show-ref
+ * unpack-file
+ * var
+ * verify-pack
+
+ * <Everything under 'Interacting with Others' in 'git help --all'>
+ * <Everything under 'Low-level...Syncing' in 'git help --all'>
+ * <Everything under 'Low-level...Internal Helpers' in 'git help --all'>
+ * <Everything under 'External commands' in 'git help --all'>
+
+* Commands that might be affected, but who cares?
+
+ * merge-file
+ * merge-index
+ * gitk?
+
+
+=== Behavior classes ===
+
+From the above there are a few classes of behavior:
+
+ * "restrict"
+
+ Commands in this class only read or write files in the working tree
+ within the sparse specification.
+
+ When moving to a new commit (e.g. switch, reset --hard), these commands
+ may update index files outside the sparse specification as of the start
+ of the operation, but by the end of the operation those index files
+ will match HEAD again and thus those files will again be outside the
+ sparse specification.
+
+ When paths are explicitly specified, these paths are intersected with
+ the sparse specification and will only operate on such paths.
+ (e.g. `git restore [--staged] -- '*.png'`, `git reset -p -- '*.md'`)
+
+ Some of these commands may also attempt, at the end of their operation,
+ to cull transient differences between the sparse specification and the
+ sparsity patterns (see "Sparse specification vs. sparsity patterns" for
+ details, but this basically means either removing unmodified files not
+ matching the sparsity patterns and marking those files as
+ SKIP_WORKTREE, or vivifying files that match the sparsity patterns and
+ marking those files as !SKIP_WORKTREE).
+
+ * "restrict modulo conflicts"
+
+ Commands in this class generally behave like the "restrict" class,
+ except that:
+ (1) they will ignore the sparse specification and write files with
+ conflicts to the working tree (thus temporarily expanding the
+ sparse specification to include such files.)
+ (2) they are grouped with commands which move to a new commit, since
+ they often create a commit and then move to it, even though we
+ know there are many exceptions to moving to the new commit. (For
+ example, the user may rebase a commit that becomes empty, or have
+ a cherry-pick which conflicts, or a user could run `merge
+ --no-commit`, and we also view `apply --index` kind of like `am
+ --no-commit`.) As such, these commands can make changes to index
+ files outside the sparse specification, though they'll mark such
+ files with SKIP_WORKTREE.
+
+ * "restrict also specially applied to untracked files"
+
+ Commands in this class generally behave like the "restrict" class,
+ except that they have to handle untracked files differently too, often
+ because these commands are dealing with files changing state between
+ 'tracked' and 'untracked'. Often, this may mean printing an error
+ message if the command had nothing to do, but the arguments may have
+ referred to files whose tracked-ness state could have changed were it
+ not for the sparsity patterns excluding them.
+
+ * "no restrict"
+
+ Commands in this class ignore the sparse specification entirely.
+
+ * "restrict or no restrict dependent upon behavior A vs. behavior B"
+
+ Commands in this class behave like "no restrict" for folks in the
+ behavior B camp, and like "restrict" for folks in the behavior A camp.
+ However, when behaving like "restrict" a warning of some sort might be
+ provided that history queries have been limited by the sparse-checkout
+ specification.
+
+
+=== Subcommand-dependent defaults ===
+
+Note that we have different defaults depending on the command for the
+desired behavior :
+
+ * Commands defaulting to "restrict":
+ * diff-files
+ * diff (without --cached or REVISION arguments)
+ * grep (without --cached or REVISION arguments)
+ * switch
+ * checkout (the switch-like half)
+ * reset (<commit>)
+
+ * restore
+ * checkout (the restore-like half)
+ * checkout-index
+ * reset (with pathspec)
+
+ This behavior makes sense; these interact with the working tree.
+
+ * Commands defaulting to "restrict modulo conflicts":
+ * merge
+ * rebase
+ * cherry-pick
+ * revert
+
+ * am
+ * apply --index (which is kind of like an `am --no-commit`)
+
+ * read-tree (especially with -m or -u; is kind of like a --no-commit merge)
+ * reset (<tree-ish>, due to similarity to read-tree)
+
+ These also interact with the working tree, but require slightly
+ different behavior either so that (a) conflicts can be resolved or (b)
+ because they are kind of like a merge-without-commit operation.
+
+ (See also the "Known bugs" section below regarding `am` and `apply`)
+
+ * Commands defaulting to "no restrict":
+ * archive
+ * bundle
+ * commit
+ * format-patch
+ * fast-export
+ * fast-import
+ * commit-tree
+
+ * stash
+ * apply (without `--index`)
+
+ These have completely different defaults and perhaps deserve the most
+ detailed explanation:
+
+ In the case of commands in the first group (format-patch,
+ fast-export, bundle, archive, etc.), these are commands for
+ communicating history, which will be broken if they restrict to a
+ subset of the repository. As such, they operate on full paths and
+ have no `--restrict` option for overriding. Some of these commands may
+ take paths for manually restricting what is exported, but it needs to
+ be very explicit.
+
+ In the case of stash, it needs to vivify files to avoid losing the
+ user's changes.
+
+ In the case of apply without `--index`, that command needs to update
+ the working tree without the index (or the index without the working
+ tree if `--cached` is passed), and if we restrict those updates to the
+ sparse specification then we'll lose changes from the user.
+
+ * Commands defaulting to "restrict also specially applied to untracked files":
+ * add
+ * rm
+ * mv
+ * update-index
+ * status
+ * clean (?)
+
+ Our original implementation for the first three of these commands was
+ "no restrict", but it had some severe usability issues:
+ * `git add <somefile>` if honored and outside the sparse
+ specification, can result in the file randomly disappearing later
+ when some subsequent command is run (since various commands
+ automatically clean up unmodified files outside the sparse
+ specification).
+ * `git rm '*.jpg'` could very negatively surprise users if it deletes
+ files outside the range of the user's interest.
+ * `git mv` has similar surprises when moving into or out of the cone,
+ so best to restrict by default
+
+ So, we switched `add` and `rm` to default to "restrict", which made
+ usability problems much less severe and less frequent, but we still got
+ complaints because commands like:
+ git add <file-outside-sparse-specification>
+ git rm <file-outside-sparse-specification>
+ would silently do nothing. We should instead print an error in those
+ cases to get usability right.
+
+ update-index needs to be updated to match, and status and maybe clean
+ also need to be updated to specially handle untracked paths.
+
+ There may be a difference in here between behavior A and behavior B in
+ terms of verboseness of errors or additional warnings.
+
+ * Commands falling under "restrict or no restrict dependent upon behavior
+ A vs. behavior B"
+
+ * diff (with --cached or REVISION arguments)
+ * grep (with --cached or REVISION arguments)
+ * show (when given commit arguments)
+ * blame (only matters when one or more -C flags passed)
+ * and annotate
+ * log
+ * and variants: shortlog, gitk, show-branch, whatchanged, rev-list
+ * ls-files
+ * diff-index
+ * diff-tree
+ * ls-tree
+
+ For now, we default to behavior B for these, which want a default of
+ "no restrict".
+
+ Note that two of these commands -- diff and grep -- also appeared in a
+ different list with a default of "restrict", but only when limited to
+ searching the working tree. The working tree vs. history distinction
+ is fundamental in how behavior B operates, so this is expected. Note,
+ though, that for diff and grep with --cached, when doing "restrict"
+ behavior, the difference between sparse specification and sparsity
+ patterns is important to handle.
+
+ "restrict" may make more sense as the long term default for these[12].
+ Also, supporting "restrict" for these commands might be a fair amount
+ of work to implement, meaning it might be implemented over multiple
+ releases. If that behavior were the default in the commands that
+ supported it, that would force behavior B users to need to learn to
+ slowly add additional flags to their commands, depending on git
+ version, to get the behavior they want. That gradual switchover would
+ be painful, so we should avoid it at least until it's fully
+ implemented.
+
+
+=== Sparse specification vs. sparsity patterns ===
+
+In a well-behaved situation, the sparse specification is given directly
+by the $GIT_DIR/info/sparse-checkout file. However, it can transiently
+diverge for a few reasons:
+
+ * needing to resolve conflicts (merging will vivify conflicted files)
+ * running Git commands that implicitly vivify files (e.g. "git stash apply")
+ * running Git commands that explicitly vivify files (e.g. "git checkout
+ --ignore-skip-worktree-bits FILENAME")
+ * other commands that write to these files (perhaps a user copies it
+ from elsewhere)
+
+For the last item, note that we do automatically clear the SKIP_WORKTREE
+bit for files that are present in the working tree. This has been true
+since 82386b4496 ("Merge branch 'en/present-despite-skipped'",
+2022-03-09)
+
+However, such a situation is transient because:
+
+ * Such transient differences can and will be automatically removed as
+ a side-effect of commands which call unpack_trees() (checkout,
+ merge, reset, etc.).
+ * Users can also request such transient differences be corrected via
+ running `git sparse-checkout reapply`. Various places recommend
+ running that command.
+ * Additional commands are also welcome to implicitly fix these
+ differences; we may add more in the future.
+
+While we avoid dropping unstaged changes or files which have conflicts,
+we otherwise aggressively try to fix these transient differences. If
+users want these differences to persist, they should run the `set` or
+`add` subcommands of `git sparse-checkout` to reflect their intended
+sparse specification.
+
+However, when we need to do a query on history restricted to the
+"relevant subset of files" such a transiently expanded sparse
+specification is ignored. There are a couple reasons for this:
+
+ * The behavior wanted when doing something like
+ git grep expression REVISION
+ is roughly what the users would expect from
+ git checkout REVISION && git grep expression
+ (modulo a "REVISION:" prefix), which has a couple ramifications:
+
+ * REVISION may have paths not in the current index, so there is no
+ path we can consult for a SKIP_WORKTREE setting for those paths.
+
+ * Since `checkout` is one of those commands that tries to remove
+ transient differences in the sparse specification, it makes sense
+ to use the corrected sparse specification
+ (i.e. $GIT_DIR/info/sparse-checkout) rather than attempting to
+ consult SKIP_WORKTREE anyway.
+
+So, a transiently expanded (or restricted) sparse specification applies to
+the working tree, but not to history queries where we always use the
+sparsity patterns. (See [16] for an early discussion of this.)
+
+Similar to a transiently expanded sparse specification of the working tree
+based on additional files being present in the working tree, we also need
+to consider additional files being modified in the index. In particular,
+if the user has staged changes to files (relative to HEAD) that do not
+match the sparsity patterns, and the file is not present in the working
+tree, we still want to consider the file part of the sparse specification
+if we are specifically performing a query related to the index (e.g. git
+diff --cached [REVISION], git diff-index [REVISION], git restore --staged
+--source=REVISION -- PATHS, etc.) Note that a transiently expanded sparse
+specification for the index usually only matters under behavior A, since
+under behavior B index operations are lumped with history and tend to
+operate full-tree.
+
+
+=== Implementation Questions ===
+
+ * Do the options --scope={sparse,all} sound good to others? Are there better
+ options?
+ * Names in use, or appearing in patches, or previously suggested:
+ * --sparse/--dense
+ * --ignore-skip-worktree-bits
+ * --ignore-skip-worktree-entries
+ * --ignore-sparsity
+ * --[no-]restrict-to-sparse-paths
+ * --full-tree/--sparse-tree
+ * --[no-]restrict
+ * --scope={sparse,all}
+ * --focus/--unfocus
+ * --limit/--unlimited
+ * Rationale making me lean slightly towards --scope={sparse,all}:
+ * We want a name that works for many commands, so we need a name that
+ does not conflict
+ * We know that we have more than two possible usecases, so it is best
+ to avoid a flag that appears to be binary.
+ * --scope={sparse,all} isn't overly long and seems relatively
+ explanatory
+ * `--sparse`, as used in add/rm/mv, is totally backwards for
+ grep/log/etc. Changing the meaning of `--sparse` for these
+ commands would fix the backwardness, but possibly break existing
+ scripts. Using a new name pairing would allow us to treat
+ `--sparse` in these commands as a deprecated alias.
+ * There is a different `--sparse`/`--dense` pair for commands using
+ revision machinery, so using that naming might cause confusion
+ * There is also a `--sparse` in both pack-objects and show-branch, which
+ don't conflict but do suggest that `--sparse` is overloaded
+ * The name --ignore-skip-worktree-bits is a double negative, is
+ quite a mouthful, refers to an implementation detail that many
+ users may not be familiar with, and we'd need a negation for it
+ which would probably be even more ridiculously long. (But we
+ can make --ignore-skip-worktree-bits a deprecated alias for
+ --no-restrict.)
+
+ * If a config option is added (sparse.scope?) what should the values and
+ description be? "sparse" (behavior A), "worktree-sparse-history-dense"
+ (behavior B), "dense" (behavior C)? There's a risk of confusion,
+ because even for Behaviors A and B we want some commands to be
+ full-tree and others to operate sparsely, so the wording may need to be
+ more tied to the usecases and somehow explain that. Also, right now,
+ the primary difference we are focusing is just the history-querying
+ commands (log/diff/grep). Previous config suggestion here: [13]
+
+ * Is `--no-expand` a good alias for ls-files's `--sparse` option?
+ (`--sparse` does not map to either `--scope=sparse` or `--scope=all`,
+ because in non-cone mode it does nothing and in cone-mode it shows the
+ sparse directory entries which are technically outside the sparse
+ specification)
+
+ * Under Behavior A:
+ * Does ls-files' `--no-expand` override the default `--scope=all`, or
+ does it need an extra flag?
+ * Does ls-files' `-t` option imply `--scope=all`?
+ * Does update-index's `--[no-]skip-worktree` option imply `--scope=all`?
+
+ * sparse-checkout: once behavior A is fully implemented, should we take
+ an interim measure to ease people into switching the default? Namely,
+ if folks are not already in a sparse checkout, then require
+ `sparse-checkout init/set` to take a
+ `--set-scope=(sparse|worktree-sparse-history-dense|dense)` flag (which
+ would set sparse.scope according to the setting given), and throw an
+ error if the flag is not provided? That error would be a great place
+ to warn folks that the default may change in the future, and get them
+ used to specifying what they want so that the eventual default switch
+ is seamless for them.
+
+
+=== Implementation Goals/Plans ===
+
+ * Get buy-in on this document in general.
+
+ * Figure out answers to the 'Implementation Questions' sections (above)
+
+ * Fix bugs in the 'Known bugs' section (below)
+
+ * Provide some kind of method for backfilling the blobs within the sparse
+ specification in a partial clone
+
+ [Below here is kind of spitballing since the first two haven't been resolved]
+
+ * update-index: flip the default to --no-ignore-skip-worktree-entries,
+ nuke this stupid "Oh, there's a bug? Let me add a flag to let users
+ request that they not trigger this bug." flag
+
+ * Flags & Config
+ * Make `--sparse` in add/rm/mv a deprecated alias for `--scope=all`
+ * Make `--ignore-skip-worktree-bits` in checkout-index/checkout/restore
+ a deprecated aliases for `--scope=all`
+ * Create config option (sparse.scope?), tie it to the "Cliff notes"
+ overview
+
+ * Add --scope=sparse (and --scope=all) flag to each of the history querying
+ commands. IMPORTANT: make sure diff machinery changes don't mess with
+ format-patch, fast-export, etc.
+
+=== Known bugs ===
+
+This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've
+been working on it.
+
+0. Behavior A is not well supported in Git. (Behavior B didn't used to
+ be either, but was the easier of the two to implement.)
+
+1. am and apply:
+
+ apply, without `--index` or `--cached`, relies on files being present
+ in the working copy, and also writes to them unconditionally. As
+ such, it should first check for the files' presence, and if found to
+ be SKIP_WORKTREE, then clear the bit and vivify the paths, then do
+ its work. Currently, it just throws an error.
+
+ apply, with either `--cached` or `--index`, will not preserve the
+ SKIP_WORKTREE bit. This is fine if the file has conflicts, but
+ otherwise SKIP_WORKTREE bits should be preserved for --cached and
+ probably also for --index.
+
+ am, if there are no conflicts, will vivify files and fail to preserve
+ the SKIP_WORKTREE bit. If there are conflicts and `-3` is not
+ specified, it will vivify files and then complain the patch doesn't
+ apply. If there are conflicts and `-3` is specified, it will vivify
+ files and then complain that those vivified files would be
+ overwritten by merge.
+
+2. reset --hard:
+
+ reset --hard provides confusing error message (works correctly, but
+ misleads the user into believing it didn't):
+
+ $ touch addme
+ $ git add addme
+ $ git ls-files -t
+ H addme
+ H tracked
+ S tracked-but-maybe-skipped
+ $ git reset --hard # usually works great
+ error: Path 'addme' not uptodate; will not remove from working tree.
+ HEAD is now at bdbbb6f third
+ $ git ls-files -t
+ H tracked
+ S tracked-but-maybe-skipped
+ $ ls -1
+ tracked
+
+ `git reset --hard` DID remove addme from the index and the working tree, contrary
+ to the error message, but in line with how reset --hard should behave.
+
+3. read-tree
+
+ `read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the
+ entries it reads into the index, resulting in all your files suddenly
+ appearing to be "deleted".
+
+4. Checkout, restore:
+
+ These command do not handle path & revision arguments appropriately:
+
+ $ ls
+ tracked
+ $ git ls-files -t
+ H tracked
+ S tracked-but-maybe-skipped
+ $ git status --porcelain
+ $ git checkout -- '*skipped'
+ error: pathspec '*skipped' did not match any file(s) known to git
+ $ git ls-files -- '*skipped'
+ tracked-but-maybe-skipped
+ $ git checkout HEAD -- '*skipped'
+ error: pathspec '*skipped' did not match any file(s) known to git
+ $ git ls-tree HEAD | grep skipped
+ 100644 blob 276f5a64354b791b13840f02047738c77ad0584f tracked-but-maybe-skipped
+ $ git status --porcelain
+ $ git checkout HEAD~1 -- '*skipped'
+ $ git ls-files -t
+ H tracked
+ H tracked-but-maybe-skipped
+ $ git status --porcelain
+ M tracked-but-maybe-skipped
+ $ git checkout HEAD -- '*skipped'
+ $ git status --porcelain
+ $
+
+ Note that checkout without a revision (or restore --staged) fails to
+ find a file to restore from the index, even though ls-files shows
+ such a file certainly exists.
+
+ Similar issues occur with HEAD (--source=HEAD in restore's case),
+ but suddenly works when HEAD~1 is specified. And then after that it
+ will work with HEAD specified, even though it didn't before.
+
+ Directories are also an issue:
+
+ $ git sparse-checkout set nomatches
+ $ git status
+ On branch main
+ You are in a sparse checkout with 0% of tracked files present.
+
+ nothing to commit, working tree clean
+ $ git checkout .
+ error: pathspec '.' did not match any file(s) known to git
+ $ git checkout HEAD~1 .
+ Updated 1 path from 58916d9
+ $ git ls-files -t
+ S tracked
+ H tracked-but-maybe-skipped
+
+5. checkout and restore --staged, continued:
+
+ These commands do not correctly scope operations to the sparse
+ specification, and make it worse by not setting important SKIP_WORKTREE
+ bits:
+
+ $ git restore --source OLDREV --staged outside-sparse-cone/
+ $ git status --porcelain
+ MD outside-sparse-cone/file1
+ MD outside-sparse-cone/file2
+ MD outside-sparse-cone/file3
+
+ We can add a --scope=all mode to `git restore` to let it operate outside
+ the sparse specification, but then it will be important to set the
+ SKIP_WORKTREE bits appropriately.
+
+6. Performance issues; see:
+ https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/
+
+
+=== Reference Emails ===
+
+Emails that detail various bugs we've had in sparse-checkout:
+
+[1] (Original descriptions of behavior A & behavior B)
+ https://lore.kernel.org/git/CABPp-BGJ_Nvi5TmgriD9Bh6eNXE2EDq2f8e8QKXAeYG3BxZafA@mail.gmail.com/
+[2] (Fix stash applications in sparse checkouts; bugs from behavioral differences)
+ https://lore.kernel.org/git/ccfedc7140dbf63ba26a15f93bd3885180b26517.1606861519.git.gitgitgadget@gmail.com/
+[3] (Present-despite-skipped entries)
+ https://lore.kernel.org/git/11d46a399d26c913787b704d2b7169cafc28d639.1642175983.git.gitgitgadget@gmail.com/
+[4] (Clone --no-checkout interaction)
+ https://lore.kernel.org/git/pull.801.v2.git.git.1591324899170.gitgitgadget@gmail.com/ (clone --no-checkout)
+[5] (The need for update_sparsity() and avoiding `read-tree -mu HEAD`)
+ https://lore.kernel.org/git/3a1f084641eb47515b5a41ed4409a36128913309.1585270142.git.gitgitgadget@gmail.com/
+[6] (SKIP_WORKTREE is advisory, not mandatory)
+ https://lore.kernel.org/git/844306c3e86ef67591cc086decb2b760e7d710a3.1585270142.git.gitgitgadget@gmail.com/
+[7] (`worktree add` should copy sparsity settings from current worktree)
+ https://lore.kernel.org/git/c51cb3714e7b1d2f8c9370fe87eca9984ff4859f.1644269584.git.gitgitgadget@gmail.com/
+[8] (Avoid negative surprises in add, rm, and mv)
+ https://lore.kernel.org/git/cover.1617914011.git.matheus.bernardino@usp.br/
+ https://lore.kernel.org/git/pull.1018.v4.git.1632497954.gitgitgadget@gmail.com/
+[9] (Move from out-of-cone to in-cone)
+ https://lore.kernel.org/git/20220630023737.473690-6-shaoxuan.yuan02@gmail.com/
+ https://lore.kernel.org/git/20220630023737.473690-4-shaoxuan.yuan02@gmail.com/
+[10] (Unnecessarily downloading objects outside sparse specification)
+ https://lore.kernel.org/git/CAOLTT8QfwOi9yx_qZZgyGa8iL8kHWutEED7ok_jxwTcYT_hf9Q@mail.gmail.com/
+
+[11] (Stolee's comments on high-level usecases)
+ https://lore.kernel.org/git/1a1e33f6-3514-9afc-0a28-5a6b85bd8014@gmail.com/
+
+[12] Others commenting on eventually switching default to behavior A:
+ * https://lore.kernel.org/git/xmqqh719pcoo.fsf@gitster.g/
+ * https://lore.kernel.org/git/xmqqzgeqw0sy.fsf@gitster.g/
+ * https://lore.kernel.org/git/a86af661-cf58-a4e5-0214-a67d3a794d7e@github.com/
+
+[13] Previous config name suggestion and description
+ * https://lore.kernel.org/git/CABPp-BE6zW0nJSStcVU=_DoDBnPgLqOR8pkTXK3dW11=T01OhA@mail.gmail.com/
+
+[14] Tangential issue: switch to cone mode as default sparse specification mechanism:
+ https://lore.kernel.org/git/a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com/
+
+[15] Lengthy email on grep behavior, covering what should be searched:
+ * https://lore.kernel.org/git/CABPp-BGVO3QdbfE84uF_3QDF0-y2iHHh6G5FAFzNRfeRitkuHw@mail.gmail.com/
+
+[16] Email explaining sparsity patterns vs. SKIP_WORKTREE and history operations,
+ search for the parenthetical comment starting "We do not check".
+ https://lore.kernel.org/git/CABPp-BFsCPPNOZ92JQRJeGyNd0e-TCW-LcLyr0i_+VSQJP+GCg@mail.gmail.com/
+
+[17] https://lore.kernel.org/git/20220207190320.2960362-1-jonathantanmy@google.com/
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 865074b..dc9c6a6 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3133,7 +3133,7 @@ those "loose" objects.
You can save space and make Git faster by moving these loose objects in
to a "pack file", which stores a group of objects in an efficient
compressed format; the details of how pack files are formatted can be
-found in link:technical/pack-format.html[pack format].
+found in linkgit:gitformat-pack[5].
To put the loose objects into a pack, just run git repack: