From cb582cab761661d1b94a09a4a78c20a3d29c9744 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 21 Nov 2022 15:55:27 +0900 Subject: Autogenerated HTML docs for v2.38.1-473-ga07895 --- MyFirstContribution.html | 2 +- MyFirstObjectWalk.html | 2 +- RelNotes/2.39.0.txt | 21 + ReviewingGuidelines.html | 2 +- SubmittingPatches.html | 2 +- ToolsForGit.html | 2 +- everyday.html | 2 +- git-add.html | 2 +- git-am.html | 2 +- git-annotate.html | 2 +- git-apply.html | 2 +- git-archimport.html | 2 +- git-archive.html | 2 +- git-bisect.html | 2 +- git-blame.html | 2 +- git-branch.html | 2 +- git-bugreport.html | 2 +- git-bundle.html | 2 +- git-cat-file.html | 2 +- git-check-attr.html | 2 +- git-check-ignore.html | 2 +- git-check-mailmap.html | 2 +- git-check-ref-format.html | 2 +- git-checkout-index.html | 2 +- git-checkout.html | 2 +- git-cherry-pick.html | 2 +- git-cherry.html | 2 +- git-citool.html | 2 +- git-clean.html | 2 +- git-clone.html | 2 +- git-column.html | 2 +- git-commit-graph.html | 2 +- git-commit-tree.html | 2 +- git-commit.html | 2 +- git-config.html | 2 +- git-count-objects.html | 2 +- git-credential-cache--daemon.html | 2 +- git-credential-cache.html | 6 +- git-credential-cache.txt | 4 +- git-credential-store.html | 2 +- git-credential.html | 3 +- git-credential.txt | 2 + git-cvsexportcommit.html | 2 +- git-cvsimport.html | 2 +- git-cvsserver.html | 2 +- git-daemon.html | 2 +- git-describe.html | 2 +- git-diagnose.html | 2 +- git-diff-files.html | 2 +- git-diff-index.html | 2 +- git-diff-tree.html | 2 +- git-diff.html | 2 +- git-difftool.html | 2 +- git-fast-export.html | 2 +- git-fast-import.html | 2 +- git-fetch-pack.html | 2 +- git-fetch.html | 2 +- git-filter-branch.html | 2 +- git-fmt-merge-msg.html | 2 +- git-for-each-ref.html | 2 +- git-for-each-repo.html | 2 +- git-format-patch.html | 2 +- git-fsck-objects.html | 2 +- git-fsck.html | 2 +- git-fsmonitor--daemon.html | 2 +- git-gc.html | 2 +- git-get-tar-commit-id.html | 2 +- git-grep.html | 2 +- git-gui.html | 2 +- git-hash-object.html | 2 +- git-help.html | 2 +- git-hook.html | 2 +- git-http-backend.html | 2 +- git-http-fetch.html | 2 +- git-http-push.html | 2 +- git-imap-send.html | 2 +- git-index-pack.html | 2 +- git-init-db.html | 2 +- git-init.html | 2 +- git-instaweb.html | 2 +- git-interpret-trailers.html | 2 +- git-log.html | 2 +- git-ls-files.html | 2 +- git-ls-remote.html | 2 +- git-ls-tree.html | 2 +- git-mailinfo.html | 2 +- git-mailsplit.html | 2 +- git-maintenance.html | 2 +- git-merge-base.html | 2 +- git-merge-file.html | 2 +- git-merge-index.html | 2 +- git-merge-one-file.html | 2 +- git-merge-tree.html | 2 +- git-merge.html | 2 +- git-mergetool--lib.html | 2 +- git-mergetool.html | 2 +- git-mktag.html | 2 +- git-mktree.html | 2 +- git-multi-pack-index.html | 2 +- git-mv.html | 2 +- git-name-rev.html | 2 +- git-notes.html | 2 +- git-p4.html | 2 +- git-pack-objects.html | 2 +- git-pack-redundant.html | 2 +- git-pack-refs.html | 2 +- git-patch-id.html | 2 +- git-prune-packed.html | 2 +- git-prune.html | 2 +- git-pull.html | 2 +- git-push.html | 2 +- git-quiltimport.html | 2 +- git-range-diff.html | 2 +- git-read-tree.html | 2 +- git-rebase.html | 2 +- git-receive-pack.html | 2 +- git-reflog.html | 2 +- git-remote-ext.html | 2 +- git-remote-fd.html | 2 +- git-remote-helpers.html | 2 +- git-remote.html | 2 +- git-repack.html | 13 +- git-repack.txt | 6 + git-replace.html | 2 +- git-request-pull.html | 2 +- git-rerere.html | 2 +- git-reset.html | 2 +- git-restore.html | 2 +- git-rev-list.html | 2 +- git-rev-parse.html | 2 +- git-revert.html | 2 +- git-rm.html | 2 +- git-send-email.html | 2 +- git-send-pack.html | 2 +- git-sh-i18n--envsubst.html | 2 +- git-sh-i18n.html | 2 +- git-sh-setup.html | 2 +- git-shell.html | 2 +- git-shortlog.html | 2 +- git-show-branch.html | 2 +- git-show-index.html | 2 +- git-show-ref.html | 2 +- git-show.html | 2 +- git-sparse-checkout.html | 2 +- git-stage.html | 2 +- git-stash.html | 2 +- git-status.html | 2 +- git-stripspace.html | 2 +- git-submodule.html | 2 +- git-svn.html | 2 +- git-switch.html | 2 +- git-symbolic-ref.html | 2 +- git-tag.html | 2 +- git-unpack-file.html | 2 +- git-unpack-objects.html | 2 +- git-update-index.html | 2 +- git-update-ref.html | 2 +- git-update-server-info.html | 2 +- git-upload-archive.html | 2 +- git-upload-pack.html | 2 +- git-var.html | 2 +- git-verify-commit.html | 2 +- git-verify-pack.html | 2 +- git-verify-tag.html | 2 +- git-version.html | 2 +- git-web--browse.html | 2 +- git-whatchanged.html | 2 +- git-worktree.html | 2 +- git-write-tree.html | 2 +- git.html | 2 +- gitattributes.html | 2 +- gitcli.html | 2 +- gitcore-tutorial.html | 2 +- gitcredentials.html | 5 +- gitcredentials.txt | 1 + gitcvs-migration.html | 2 +- gitdiffcore.html | 2 +- giteveryday.html | 2 +- gitfaq.html | 2 +- gitformat-bundle.html | 2 +- gitformat-chunk.html | 2 +- gitformat-commit-graph.html | 2 +- gitformat-index.html | 2 +- gitformat-pack.html | 2 +- gitformat-signature.html | 2 +- gitglossary.html | 2 +- githooks.html | 2 +- gitignore.html | 2 +- gitk.html | 2 +- gitmailmap.html | 2 +- gitmodules.html | 2 +- gitnamespaces.html | 2 +- gitprotocol-capabilities.html | 2 +- gitprotocol-common.html | 2 +- gitprotocol-http.html | 2 +- gitprotocol-pack.html | 2 +- gitprotocol-v2.html | 2 +- gitremote-helpers.html | 2 +- gitrepository-layout.html | 2 +- gitrevisions.html | 2 +- gitsubmodules.html | 2 +- gittutorial-2.html | 2 +- gittutorial.html | 2 +- gitweb.conf.html | 2 +- gitweb.html | 2 +- gitworkflows.html | 2 +- howto/coordinate-embargoed-releases.html | 2 +- howto/keep-canonical-history-correct.html | 2 +- howto/maintain-git.html | 2 +- howto/new-command.html | 2 +- howto/rebase-from-internal-branch.html | 2 +- howto/rebuild-from-update-hook.html | 2 +- howto/recover-corrupted-blob-object.html | 2 +- howto/recover-corrupted-object-harder.html | 2 +- howto/revert-a-faulty-merge.html | 2 +- howto/revert-branch-rebase.html | 2 +- howto/separating-topic-branches.html | 2 +- howto/setup-git-server-over-http.html | 2 +- howto/update-hook-example.html | 2 +- howto/use-git-daemon.html | 2 +- howto/using-merge-subtree.html | 2 +- howto/using-signed-tag-in-pull-request.html | 2 +- scalar.html | 2 +- technical/api-error-handling.html | 2 +- technical/api-index.html | 2 +- technical/api-merge.html | 2 +- technical/api-parse-options.html | 2 +- technical/api-simple-ipc.html | 2 +- technical/api-trace2.html | 2 +- technical/bitmap-format.html | 2 +- technical/bundle-uri.html | 2 +- technical/hash-function-transition.html | 2 +- technical/long-running-process-protocol.html | 2 +- technical/multi-pack-index.html | 2 +- technical/pack-heuristics.html | 2 +- technical/parallel-checkout.html | 2 +- technical/partial-clone.html | 2 +- technical/racy-git.html | 2 +- technical/reftable.html | 2 +- technical/scalar.html | 2 +- technical/send-pack-pipeline.html | 2 +- technical/shallow.html | 2 +- technical/sparse-checkout.txt | 1103 ++++++++++++++++++++++++++ technical/trivial-merge.html | 2 +- 244 files changed, 1389 insertions(+), 243 deletions(-) create mode 100644 technical/sparse-checkout.txt diff --git a/MyFirstContribution.html b/MyFirstContribution.html index dac53cf3a..0d0e10ac2 100644 --- a/MyFirstContribution.html +++ b/MyFirstContribution.html @@ -2060,7 +2060,7 @@ should generate your diffs from <topic>..<mybranch> and diff --git a/MyFirstObjectWalk.html b/MyFirstObjectWalk.html index 47f8daadb..514061a2a 100644 --- a/MyFirstObjectWalk.html +++ b/MyFirstObjectWalk.html @@ -1722,7 +1722,7 @@ Changed the display order of the filtered object walk diff --git a/RelNotes/2.39.0.txt b/RelNotes/2.39.0.txt index f9bc29f7d..153bf6d89 100644 --- a/RelNotes/2.39.0.txt +++ b/RelNotes/2.39.0.txt @@ -32,6 +32,9 @@ UI, Workflows & Features * 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. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -109,6 +112,18 @@ Performance, Internal Implementation, Development Support etc. * 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. + Fixes since v2.38 ----------------- @@ -250,6 +265,12 @@ Fixes since v2.38 * "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. + * Other code cleanup, docfix, build fix, etc. (merge 413bc6d20a ds/cmd-main-reorder later to maint). (merge 8d2863e4ed nw/t1002-cleanup later to maint). diff --git a/ReviewingGuidelines.html b/ReviewingGuidelines.html index cb827fdd7..2b6323b78 100644 --- a/ReviewingGuidelines.html +++ b/ReviewingGuidelines.html @@ -974,7 +974,7 @@ message (after the ---) and the beginning of the diff.

diff --git a/SubmittingPatches.html b/SubmittingPatches.html index 45510f0d1..b5d9ddae4 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html @@ -1446,7 +1446,7 @@ this problem around.

diff --git a/ToolsForGit.html b/ToolsForGit.html index b94addc5e..baf7c4513 100644 --- a/ToolsForGit.html +++ b/ToolsForGit.html @@ -805,7 +805,7 @@ document can be applied here too.

diff --git a/everyday.html b/everyday.html index 509c00374..151cccc33 100644 --- a/everyday.html +++ b/everyday.html @@ -750,7 +750,7 @@ link you clicked to get here.

diff --git a/git-add.html b/git-add.html index 2e57f689e..318a05b5c 100644 --- a/git-add.html +++ b/git-add.html @@ -1424,7 +1424,7 @@ add.interactive.useBuiltin diff --git a/git-am.html b/git-am.html index 452d93395..80b372af4 100644 --- a/git-am.html +++ b/git-am.html @@ -1273,7 +1273,7 @@ am.threeWay diff --git a/git-annotate.html b/git-annotate.html index 054cf1170..802ec6c4b 100644 --- a/git-annotate.html +++ b/git-annotate.html @@ -1091,7 +1091,7 @@ take effect.

diff --git a/git-apply.html b/git-apply.html index 189a2673c..63205cec8 100644 --- a/git-apply.html +++ b/git-apply.html @@ -1248,7 +1248,7 @@ subdirectory is checked and (if possible) updated.

diff --git a/git-archimport.html b/git-archimport.html index 488402165..74ae5b094 100644 --- a/git-archimport.html +++ b/git-archimport.html @@ -905,7 +905,7 @@ patches that have been traded out-of-sequence between the branches.

diff --git a/git-archive.html b/git-archive.html index 2055ac42f..97b674a62 100644 --- a/git-archive.html +++ b/git-archive.html @@ -1149,7 +1149,7 @@ while archiving any tree in your $GIT_DIR/info/attributes file.

diff --git a/git-bisect.html b/git-bisect.html index d52641774..f18a8a602 100644 --- a/git-bisect.html +++ b/git-bisect.html @@ -1240,7 +1240,7 @@ help or git bisect -h to get a long usage description.

Last updated - 2020-09-11 23:36:57 PDT + 2020-09-12 15:36:57 JST
diff --git a/git-blame.html b/git-blame.html index cb1eca644..4dfd22143 100644 --- a/git-blame.html +++ b/git-blame.html @@ -1500,7 +1500,7 @@ blame.markIgnoredLines diff --git a/git-branch.html b/git-branch.html index 7321da0be..a2f7dafbc 100644 --- a/git-branch.html +++ b/git-branch.html @@ -1580,7 +1580,7 @@ a branch?” in the Git User’s Manual.

diff --git a/git-bugreport.html b/git-bugreport.html index 4374c93c9..caeb37e33 100644 --- a/git-bugreport.html +++ b/git-bugreport.html @@ -879,7 +879,7 @@ about their usage.

diff --git a/git-bundle.html b/git-bundle.html index 21ebd6c89..14a0ecf71 100644 --- a/git-bundle.html +++ b/git-bundle.html @@ -1128,7 +1128,7 @@ references when fetching:

diff --git a/git-cat-file.html b/git-cat-file.html index bfc82bd13..3dc3cc4c2 100644 --- a/git-cat-file.html +++ b/git-cat-file.html @@ -1273,7 +1273,7 @@ will be reported.

diff --git a/git-check-attr.html b/git-check-attr.html index 5859d6cb1..20cb0159e 100644 --- a/git-check-attr.html +++ b/git-check-attr.html @@ -960,7 +960,7 @@ README: caveat: unspecified diff --git a/git-check-ignore.html b/git-check-ignore.html index 715633e71..3f60c4ea2 100644 --- a/git-check-ignore.html +++ b/git-check-ignore.html @@ -924,7 +924,7 @@ buffer.

diff --git a/git-check-mailmap.html b/git-check-mailmap.html index 421cbf80b..a45a0bf97 100644 --- a/git-check-mailmap.html +++ b/git-check-mailmap.html @@ -811,7 +811,7 @@ to specify a custom .mailmap target file or object.

diff --git a/git-check-ref-format.html b/git-check-ref-format.html index 639cb7ab0..e52a7bfb2 100644 --- a/git-check-ref-format.html +++ b/git-check-ref-format.html @@ -963,7 +963,7 @@ Determine the reference name to use for a new branch: diff --git a/git-checkout-index.html b/git-checkout-index.html index 3092e33bb..9da25285d 100644 --- a/git-checkout-index.html +++ b/git-checkout-index.html @@ -1020,7 +1020,7 @@ into the file .merged-Makefile.

diff --git a/git-checkout.html b/git-checkout.html index 397de991f..8f6e8a1cd 100644 --- a/git-checkout.html +++ b/git-checkout.html @@ -1633,7 +1633,7 @@ checkout.thresholdForParallelism diff --git a/git-cherry-pick.html b/git-cherry-pick.html index 2fbd7af8a..d1eb3c15c 100644 --- a/git-cherry-pick.html +++ b/git-cherry-pick.html @@ -1217,7 +1217,7 @@ try to apply the change introduced by topic^ again, diff --git a/git-cherry.html b/git-cherry.html index 2f5665147..6f997f85e 100644 --- a/git-cherry.html +++ b/git-cherry.html @@ -915,7 +915,7 @@ between base and topic:

diff --git a/git-citool.html b/git-citool.html index c7530ab18..2769f7805 100644 --- a/git-citool.html +++ b/git-citool.html @@ -776,7 +776,7 @@ See git-gui(1) for more details.

diff --git a/git-clean.html b/git-clean.html index fb95d958d..dd78b23bd 100644 --- a/git-clean.html +++ b/git-clean.html @@ -992,7 +992,7 @@ clean.requireForce diff --git a/git-clone.html b/git-clone.html index 8f6f3210e..627b82c1c 100644 --- a/git-clone.html +++ b/git-clone.html @@ -1509,7 +1509,7 @@ clone.filterSubmodules diff --git a/git-column.html b/git-column.html index 42b82bcce..69d5d1188 100644 --- a/git-column.html +++ b/git-column.html @@ -1015,7 +1015,7 @@ column.tag diff --git a/git-commit-graph.html b/git-commit-graph.html index c7e3188b9..a76d53e72 100644 --- a/git-commit-graph.html +++ b/git-commit-graph.html @@ -989,7 +989,7 @@ commitGraph.readChangedPaths diff --git a/git-commit-tree.html b/git-commit-tree.html index 30a01ca6a..a7aeb0a9c 100644 --- a/git-commit-tree.html +++ b/git-commit-tree.html @@ -1029,7 +1029,7 @@ reversible operation.

diff --git a/git-commit.html b/git-commit.html index db1e2e4a8..a13cdb07d 100644 --- a/git-commit.html +++ b/git-commit.html @@ -1840,7 +1840,7 @@ information.

diff --git a/git-config.html b/git-config.html index a497dbdf9..95dd88f29 100644 --- a/git-config.html +++ b/git-config.html @@ -11560,7 +11560,7 @@ looks like

diff --git a/git-count-objects.html b/git-count-objects.html index e13c6b1a2..d989883f7 100644 --- a/git-count-objects.html +++ b/git-count-objects.html @@ -815,7 +815,7 @@ Print sizes in human readable format diff --git a/git-credential-cache--daemon.html b/git-credential-cache--daemon.html index 0b7a87414..35672fcd5 100644 --- a/git-credential-cache--daemon.html +++ b/git-credential-cache--daemon.html @@ -786,7 +786,7 @@ begun listening for clients.

diff --git a/git-credential-cache.html b/git-credential-cache.html index 8cbf7fdaa..e87d4ec97 100644 --- a/git-credential-cache.html +++ b/git-credential-cache.html @@ -824,10 +824,10 @@ $ git push http://example.com/repo.git [your credentials are used automatically]

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'
@@ -842,7 +842,7 @@ variable (this example drops the cache time to 5 minutes):

diff --git a/git-credential-cache.txt b/git-credential-cache.txt index 0216c18ef..432e159d9 100644 --- a/git-credential-cache.txt +++ b/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/git-credential-store.html b/git-credential-store.html index 1bcd68344..bfb98cabd 100644 --- a/git-credential-store.html +++ b/git-credential-store.html @@ -882,7 +882,7 @@ for more information.

diff --git a/git-credential.html b/git-credential.html index 657e398f0..91134ad7e 100644 --- a/git-credential.html +++ b/git-credential.html @@ -933,6 +933,7 @@ empty string.

username in the example above) will be left unset.

+

Unrecognised attributes are silently discarded.

@@ -946,7 +947,7 @@ username in the example above) will be left unset.

diff --git a/git-credential.txt b/git-credential.txt index f18673017..ac2818b9f 100644 --- a/git-credential.txt +++ b/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/git-cvsexportcommit.html b/git-cvsexportcommit.html index 71f742872..5f2236503 100644 --- a/git-cvsexportcommit.html +++ b/git-cvsexportcommit.html @@ -951,7 +951,7 @@ $ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit diff --git a/git-cvsimport.html b/git-cvsimport.html index af3a9caee..83ecbbe0c 100644 --- a/git-cvsimport.html +++ b/git-cvsimport.html @@ -1107,7 +1107,7 @@ cvs2git (part of cvs2svn), http://subversion.apache.org/ diff --git a/git-cvsserver.html b/git-cvsserver.html index 023c14c75..38b958144 100644 --- a/git-cvsserver.html +++ b/git-cvsserver.html @@ -1327,7 +1327,7 @@ and gitcvs.allBinary to "guess".

diff --git a/git-daemon.html b/git-daemon.html index 11074ebda..2f3f792e5 100644 --- a/git-daemon.html +++ b/git-daemon.html @@ -1281,7 +1281,7 @@ services are performed.

diff --git a/git-describe.html b/git-describe.html index 865764356..baeb95d61 100644 --- a/git-describe.html +++ b/git-describe.html @@ -1042,7 +1042,7 @@ tag being favorable.

diff --git a/git-diagnose.html b/git-diagnose.html index 4fc838819..505b40e4c 100644 --- a/git-diagnose.html +++ b/git-diagnose.html @@ -858,7 +858,7 @@ Users should exercise caution when sharing an archive generated with diff --git a/git-diff-files.html b/git-diff-files.html index f26773dc2..873735cf4 100644 --- a/git-diff-files.html +++ b/git-diff-files.html @@ -2703,7 +2703,7 @@ the pathname, but if that is NUL, the record will show two paths.
Last updated - 2022-10-28 11:53:56 PDT + 2022-10-29 03:53:56 JST
diff --git a/git-diff-index.html b/git-diff-index.html index 8f20f8bb9..9ffdc7b72 100644 --- a/git-diff-index.html +++ b/git-diff-index.html @@ -2797,7 +2797,7 @@ always have the special all-zero sha1. diff --git a/git-diff-tree.html b/git-diff-tree.html index 99ebe987c..d0d99c792 100644 --- a/git-diff-tree.html +++ b/git-diff-tree.html @@ -3974,7 +3974,7 @@ the pathname, but if that is NUL, the record will show two paths.
Last updated - 2021-12-10 14:52:02 PST + 2021-12-11 07:52:02 JST
diff --git a/git-diff.html b/git-diff.html index 9a8fe99b5..19d75b12e 100644 --- a/git-diff.html +++ b/git-diff.html @@ -3646,7 +3646,7 @@ diff.colorMovedWS diff --git a/git-difftool.html b/git-difftool.html index 303d7d64c..e342935ad 100644 --- a/git-difftool.html +++ b/git-difftool.html @@ -1041,7 +1041,7 @@ difftool.prompt diff --git a/git-fast-export.html b/git-fast-export.html index fa7da2179..5de4830b3 100644 --- a/git-fast-export.html +++ b/git-fast-export.html @@ -1120,7 +1120,7 @@ a tag referencing a tree instead of a commit.

diff --git a/git-fast-import.html b/git-fast-import.html index db44a65ee..5b6a6461f 100644 --- a/git-fast-import.html +++ b/git-fast-import.html @@ -2640,7 +2640,7 @@ fastimport.unpackLimit diff --git a/git-fetch-pack.html b/git-fetch-pack.html index 91927de49..d4e373955 100644 --- a/git-fetch-pack.html +++ b/git-fetch-pack.html @@ -983,7 +983,7 @@ they may alternatively be 40-hex sha1s present on the remote.

diff --git a/git-fetch.html b/git-fetch.html index e4fc99601..d69e0368f 100644 --- a/git-fetch.html +++ b/git-fetch.html @@ -2184,7 +2184,7 @@ submodule update. This is expected to be fixed in a future Git version.
Last updated - 2022-09-14 13:23:11 PDT + 2022-09-15 05:23:11 JST
diff --git a/git-filter-branch.html b/git-filter-branch.html index 73d68b573..bb44565f2 100644 --- a/git-filter-branch.html +++ b/git-filter-branch.html @@ -1626,7 +1626,7 @@ To top it all off, even when users finally find working commands, diff --git a/git-fmt-merge-msg.html b/git-fmt-merge-msg.html index 6966f1e8b..448dc1fe7 100644 --- a/git-fmt-merge-msg.html +++ b/git-fmt-merge-msg.html @@ -917,7 +917,7 @@ the "origin" remote.

diff --git a/git-for-each-ref.html b/git-for-each-ref.html index 7dec9fd1a..70f65ef32 100644 --- a/git-for-each-ref.html +++ b/git-for-each-ref.html @@ -1338,7 +1338,7 @@ commits and from none of the --no-merged commits are shown.

Last updated - 2021-08-24 17:58:56 PDT + 2021-08-25 09:58:56 JST
diff --git a/git-for-each-repo.html b/git-for-each-repo.html index 1b269897a..4ee705935 100644 --- a/git-for-each-repo.html +++ b/git-for-each-repo.html @@ -812,7 +812,7 @@ descriptors stdin, stdout, and stderr.

Last updated - 2020-11-20 22:32:32 PST + 2020-11-21 15:32:32 JST
diff --git a/git-format-patch.html b/git-format-patch.html index 520db4fa4..9d4446540 100644 --- a/git-format-patch.html +++ b/git-format-patch.html @@ -2594,7 +2594,7 @@ merge commit.

diff --git a/git-fsck-objects.html b/git-fsck-objects.html index 661817647..61b56b38b 100644 --- a/git-fsck-objects.html +++ b/git-fsck-objects.html @@ -772,7 +772,7 @@ documentation of that command.

diff --git a/git-fsck.html b/git-fsck.html index b6bcbcf57..615d99f8c 100644 --- a/git-fsck.html +++ b/git-fsck.html @@ -1547,7 +1547,7 @@ GIT_ALTERNATE_OBJECT_DIRECTORIES diff --git a/git-fsmonitor--daemon.html b/git-fsmonitor--daemon.html index 80dcb9852..dddbbb356 100644 --- a/git-fsmonitor--daemon.html +++ b/git-fsmonitor--daemon.html @@ -900,7 +900,7 @@ fsmonitor.socketDir diff --git a/git-gc.html b/git-gc.html index 26e76f03c..b29efc9bf 100644 --- a/git-gc.html +++ b/git-gc.html @@ -1187,7 +1187,7 @@ seems to be low in practice).

diff --git a/git-get-tar-commit-id.html b/git-get-tar-commit-id.html index e63c21cf1..e5e6ef9ec 100644 --- a/git-get-tar-commit-id.html +++ b/git-get-tar-commit-id.html @@ -778,7 +778,7 @@ a tree ID instead of a commit ID or tag.

diff --git a/git-grep.html b/git-grep.html index cee178ff1..10734aa2f 100644 --- a/git-grep.html +++ b/git-grep.html @@ -1489,7 +1489,7 @@ grep.fallbackToNoIndex diff --git a/git-gui.html b/git-gui.html index d297f8836..fbaad6363 100644 --- a/git-gui.html +++ b/git-gui.html @@ -945,7 +945,7 @@ of end users.

diff --git a/git-hash-object.html b/git-hash-object.html index 40ee5e038..e43c4b079 100644 --- a/git-hash-object.html +++ b/git-hash-object.html @@ -854,7 +854,7 @@ When <type> is not specified, it defaults to "blob".

diff --git a/git-help.html b/git-help.html index 12a904cf6..591418695 100644 --- a/git-help.html +++ b/git-help.html @@ -1056,7 +1056,7 @@ See git-config(1) for more information about this. diff --git a/git-hook.html b/git-hook.html index 8b1bf6e0e..452e6fb01 100644 --- a/git-hook.html +++ b/git-hook.html @@ -814,7 +814,7 @@ mandatory -- (or --end-of-options, see
Last updated - 2022-02-16 17:29:08 PST + 2022-02-17 10:29:08 JST
diff --git a/git-http-backend.html b/git-http-backend.html index a9975459e..d95b82eb3 100644 --- a/git-http-backend.html +++ b/git-http-backend.html @@ -1102,7 +1102,7 @@ invoked by the git-receive-pack.

diff --git a/git-http-fetch.html b/git-http-fetch.html index fc1a54411..a2c0362fb 100644 --- a/git-http-fetch.html +++ b/git-http-fetch.html @@ -860,7 +860,7 @@ commit-id diff --git a/git-http-push.html b/git-http-push.html index 0b45400c0..9522c736e 100644 --- a/git-http-push.html +++ b/git-http-push.html @@ -908,7 +908,7 @@ to disable the fast-forward check only on that ref.

diff --git a/git-imap-send.html b/git-imap-send.html index f6c1f3b0e..7059f73f4 100644 --- a/git-imap-send.html +++ b/git-imap-send.html @@ -1028,7 +1028,7 @@ users may wish to visit this web page for more information: diff --git a/git-index-pack.html b/git-index-pack.html index 586407f01..f4e55e204 100644 --- a/git-index-pack.html +++ b/git-index-pack.html @@ -981,7 +981,7 @@ mentioned above.

diff --git a/git-init-db.html b/git-init-db.html index 407cb0782..a9ff2fc0a 100644 --- a/git-init-db.html +++ b/git-init-db.html @@ -772,7 +772,7 @@ documentation of that command.

diff --git a/git-init.html b/git-init.html index 743f0cf01..8829063ae 100644 --- a/git-init.html +++ b/git-init.html @@ -1034,7 +1034,7 @@ init.defaultBranch diff --git a/git-instaweb.html b/git-instaweb.html index 23f6e050a..f0e88934b 100644 --- a/git-instaweb.html +++ b/git-instaweb.html @@ -907,7 +907,7 @@ restart diff --git a/git-interpret-trailers.html b/git-interpret-trailers.html index 281a7f0c3..c85eff366 100644 --- a/git-interpret-trailers.html +++ b/git-interpret-trailers.html @@ -1330,7 +1330,7 @@ $ chmod +x .git/hooks/commit-msg diff --git a/git-log.html b/git-log.html index 843838c94..57d0b4ef2 100644 --- a/git-log.html +++ b/git-log.html @@ -5564,7 +5564,7 @@ See notes.rewrite.<command> above for a further description o diff --git a/git-ls-files.html b/git-ls-files.html index e81b784bf..5150c264a 100644 --- a/git-ls-files.html +++ b/git-ls-files.html @@ -1327,7 +1327,7 @@ pattern file appears in.

diff --git a/git-ls-remote.html b/git-ls-remote.html index 028cbc00f..c8bb98722 100644 --- a/git-ls-remote.html +++ b/git-ls-remote.html @@ -945,7 +945,7 @@ c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 diff --git a/git-ls-tree.html b/git-ls-tree.html index a330dd096..daa7b152a 100644 --- a/git-ls-tree.html +++ b/git-ls-tree.html @@ -1028,7 +1028,7 @@ path diff --git a/git-mailinfo.html b/git-mailinfo.html index 1daf955f3..c6581be19 100644 --- a/git-mailinfo.html +++ b/git-mailinfo.html @@ -972,7 +972,7 @@ mailinfo.scissors diff --git a/git-mailsplit.html b/git-mailsplit.html index cd57d9c38..9fd910dc5 100644 --- a/git-mailsplit.html +++ b/git-mailsplit.html @@ -860,7 +860,7 @@ patches in the correct order. diff --git a/git-maintenance.html b/git-maintenance.html index 9125e7aa8..156864ebd 100644 --- a/git-maintenance.html +++ b/git-maintenance.html @@ -1359,7 +1359,7 @@ maintenance.incremental-repack.auto diff --git a/git-merge-base.html b/git-merge-base.html index 2dd37db5a..f093175ed 100644 --- a/git-merge-base.html +++ b/git-merge-base.html @@ -1017,7 +1017,7 @@ commits that used to be at the tip of origin/master).

diff --git a/git-merge-file.html b/git-merge-file.html index f4e828267..9880a987c 100644 --- a/git-merge-file.html +++ b/git-merge-file.html @@ -894,7 +894,7 @@ implements all of RCS merge's functionality which is needed by diff --git a/git-merge-index.html b/git-merge-index.html index 2cedbc821..d4128b431 100644 --- a/git-merge-index.html +++ b/git-merge-index.html @@ -852,7 +852,7 @@ for the AA file, because it didn’t exist in the original, and thus diff --git a/git-merge-one-file.html b/git-merge-one-file.html index 1c961f491..907a4010f 100644 --- a/git-merge-one-file.html +++ b/git-merge-one-file.html @@ -772,7 +772,7 @@ to resolve a merge after the trivial merge done with git read-tree -m.< diff --git a/git-merge-tree.html b/git-merge-tree.html index b3ce21244..f729e2c94 100644 --- a/git-merge-tree.html +++ b/git-merge-tree.html @@ -1128,7 +1128,7 @@ large repositories).

diff --git a/git-merge.html b/git-merge.html index ef87f6c59..47911ada8 100644 --- a/git-merge.html +++ b/git-merge.html @@ -2326,7 +2326,7 @@ merge.<driver>.recursive diff --git a/git-mergetool--lib.html b/git-mergetool--lib.html index f69456238..be33b0579 100644 --- a/git-mergetool--lib.html +++ b/git-mergetool--lib.html @@ -832,7 +832,7 @@ run_merge_tool diff --git a/git-mergetool.html b/git-mergetool.html index dc6726b54..60925c288 100644 --- a/git-mergetool.html +++ b/git-mergetool.html @@ -1329,7 +1329,7 @@ MERGED and REMOTE).

diff --git a/git-mktag.html b/git-mktag.html index 4b3a9bc0e..c277b6b96 100644 --- a/git-mktag.html +++ b/git-mktag.html @@ -828,7 +828,7 @@ care about, but that can be verified with gpg.

diff --git a/git-mktree.html b/git-mktree.html index ec61aa492..cf200a547 100644 --- a/git-mktree.html +++ b/git-mktree.html @@ -811,7 +811,7 @@ built is written to the standard output.

diff --git a/git-multi-pack-index.html b/git-multi-pack-index.html index db7631bb8..8e0a906df 100644 --- a/git-multi-pack-index.html +++ b/git-multi-pack-index.html @@ -958,7 +958,7 @@ multi-pack-index feature and its file format.

diff --git a/git-mv.html b/git-mv.html index 71c0b6755..bd4e948e7 100644 --- a/git-mv.html +++ b/git-mv.html @@ -857,7 +857,7 @@ been implemented.

diff --git a/git-name-rev.html b/git-name-rev.html index 9e13d4ec3..4b1de4ed0 100644 --- a/git-name-rev.html +++ b/git-name-rev.html @@ -911,7 +911,7 @@ not the context.

diff --git a/git-notes.html b/git-notes.html index 230ed94ac..6decfb7ad 100644 --- a/git-notes.html +++ b/git-notes.html @@ -1362,7 +1362,7 @@ on the notes.rewrite.<command> and notes.rewriteRef
Last updated - 2022-09-14 13:23:11 PDT + 2022-09-15 05:23:11 JST
diff --git a/git-p4.html b/git-p4.html index ed16cfbd7..ee0d4df6e 100644 --- a/git-p4.html +++ b/git-p4.html @@ -1974,7 +1974,7 @@ Each commit imported by git p4 has a line at the end of the log diff --git a/git-pack-objects.html b/git-pack-objects.html index 4d806f2c2..d54febfbe 100644 --- a/git-pack-objects.html +++ b/git-pack-objects.html @@ -1390,7 +1390,7 @@ attribute delta set to false.

diff --git a/git-pack-redundant.html b/git-pack-redundant.html index 46a10b30e..6b60e3dbd 100644 --- a/git-pack-redundant.html +++ b/git-pack-redundant.html @@ -819,7 +819,7 @@ git pack-redundant --all | xargs rm

diff --git a/git-pack-refs.html b/git-pack-refs.html index 1ba32e6bc..160e4e64a 100644 --- a/git-pack-refs.html +++ b/git-pack-refs.html @@ -831,7 +831,7 @@ exists" when it means "branch <branch> exists".

diff --git a/git-patch-id.html b/git-patch-id.html index 2ce031a5b..47b008913 100644 --- a/git-patch-id.html +++ b/git-patch-id.html @@ -855,7 +855,7 @@ All whitespace within the patch is ignored and does not affect the id. diff --git a/git-prune-packed.html b/git-prune-packed.html index cdbe250da..f2a5d8888 100644 --- a/git-prune-packed.html +++ b/git-prune-packed.html @@ -814,7 +814,7 @@ disk storage, etc.

diff --git a/git-prune.html b/git-prune.html index 1ccb61fbc..646ce3f50 100644 --- a/git-prune.html +++ b/git-prune.html @@ -884,7 +884,7 @@ many other housekeeping tasks.

diff --git a/git-pull.html b/git-pull.html index dc4948811..b0aecad93 100644 --- a/git-pull.html +++ b/git-pull.html @@ -2301,7 +2301,7 @@ version.

diff --git a/git-push.html b/git-push.html index d32cbbf5e..8def1a6ac 100644 --- a/git-push.html +++ b/git-push.html @@ -2183,7 +2183,7 @@ push.useBitmaps diff --git a/git-quiltimport.html b/git-quiltimport.html index d17775bb8..d5af3f060 100644 --- a/git-quiltimport.html +++ b/git-quiltimport.html @@ -841,7 +841,7 @@ variable.

diff --git a/git-range-diff.html b/git-range-diff.html index 3a720e4d6..d157f6df1 100644 --- a/git-range-diff.html +++ b/git-range-diff.html @@ -1085,7 +1085,7 @@ found in this case will look like this:

diff --git a/git-read-tree.html b/git-read-tree.html index 3d0e35d03..7b01f129f 100644 --- a/git-read-tree.html +++ b/git-read-tree.html @@ -1294,7 +1294,7 @@ support.

diff --git a/git-rebase.html b/git-rebase.html index ef0720da0..9e3ec6d33 100644 --- a/git-rebase.html +++ b/git-rebase.html @@ -2765,7 +2765,7 @@ sequence.editor diff --git a/git-receive-pack.html b/git-receive-pack.html index dbdb992c9..6d6aa8708 100644 --- a/git-receive-pack.html +++ b/git-receive-pack.html @@ -1094,7 +1094,7 @@ The pre-receive hook MUST NOT update any refs to point to diff --git a/git-reflog.html b/git-reflog.html index a6265b239..82cafdf9a 100644 --- a/git-reflog.html +++ b/git-reflog.html @@ -925,7 +925,7 @@ used with expire.

diff --git a/git-remote-ext.html b/git-remote-ext.html index e81564705..84726c118 100644 --- a/git-remote-ext.html +++ b/git-remote-ext.html @@ -963,7 +963,7 @@ begins with ext::. Examples:

diff --git a/git-remote-fd.html b/git-remote-fd.html index 70a21290c..66f3c243f 100644 --- a/git-remote-fd.html +++ b/git-remote-fd.html @@ -843,7 +843,7 @@ GIT_TRANSLOOP_DEBUG diff --git a/git-remote-helpers.html b/git-remote-helpers.html index 59fab6fc6..7c58d5bf9 100644 --- a/git-remote-helpers.html +++ b/git-remote-helpers.html @@ -750,7 +750,7 @@ link you clicked to get here.

diff --git a/git-remote.html b/git-remote.html index 9f04749ff..dc22f9c8a 100644 --- a/git-remote.html +++ b/git-remote.html @@ -1057,7 +1057,7 @@ $ git merge origin diff --git a/git-repack.html b/git-repack.html index 3d48635c3..4af35d77a 100644 --- a/git-repack.html +++ b/git-repack.html @@ -841,6 +841,17 @@ to the new separate pack will be written.

+--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
@@ -1112,7 +1123,7 @@ attribute delta set to false.

diff --git a/git-repack.txt b/git-repack.txt index 0bf13893d..401715794 100644 --- a/git-repack.txt +++ b/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=:: + Write a cruft pack containing pruned objects (if any) to the + directory ``. 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/git-replace.html b/git-replace.html index edee34707..1cdbfae73 100644 --- a/git-replace.html +++ b/git-replace.html @@ -971,7 +971,7 @@ pending objects.

diff --git a/git-request-pull.html b/git-request-pull.html index 5a8efb8d4..33db0b53d 100644 --- a/git-request-pull.html +++ b/git-request-pull.html @@ -855,7 +855,7 @@ the one you have locally, e.g.

diff --git a/git-rerere.html b/git-rerere.html index 335515835..bd49b4712 100644 --- a/git-rerere.html +++ b/git-rerere.html @@ -990,7 +990,7 @@ setting in gitattributes(5) can be used.

Last updated - 2022-10-28 11:53:56 PDT + 2022-10-29 03:53:56 JST
diff --git a/git-reset.html b/git-reset.html index 1b555866b..2191d66ac 100644 --- a/git-reset.html +++ b/git-reset.html @@ -1506,7 +1506,7 @@ entries:

diff --git a/git-restore.html b/git-restore.html index 389d9784f..a76166c64 100644 --- a/git-restore.html +++ b/git-restore.html @@ -1073,7 +1073,7 @@ as using git-checkout(1))

diff --git a/git-rev-list.html b/git-rev-list.html index 810ef12e3..83a257ffe 100644 --- a/git-rev-list.html +++ b/git-rev-list.html @@ -3706,7 +3706,7 @@ Compare the on-disk size of branches in one group of refs, excluding diff --git a/git-rev-parse.html b/git-rev-parse.html index 300106a39..2b55c319e 100644 --- a/git-rev-parse.html +++ b/git-rev-parse.html @@ -2063,7 +2063,7 @@ Similar to above: diff --git a/git-revert.html b/git-revert.html index 35c9b38a0..8c5c24fc6 100644 --- a/git-revert.html +++ b/git-revert.html @@ -1059,7 +1059,7 @@ revert.reference diff --git a/git-rm.html b/git-rm.html index ee7d70018..6c2454070 100644 --- a/git-rm.html +++ b/git-rm.html @@ -1033,7 +1033,7 @@ obsolete when recursive submodule update has been implemented.

diff --git a/git-send-email.html b/git-send-email.html index cf0b8868b..ebf73f65c 100644 --- a/git-send-email.html +++ b/git-send-email.html @@ -1812,7 +1812,7 @@ Authen::SASL and Mail::Address.

diff --git a/git-send-pack.html b/git-send-pack.html index c4354c91c..df56e8c14 100644 --- a/git-send-pack.html +++ b/git-send-pack.html @@ -994,7 +994,7 @@ to disable the fast-forward check only on that ref.

diff --git a/git-sh-i18n--envsubst.html b/git-sh-i18n--envsubst.html index 1aefa501c..a5b9dc097 100644 --- a/git-sh-i18n--envsubst.html +++ b/git-sh-i18n--envsubst.html @@ -785,7 +785,7 @@ of Git. Don’t use it.

diff --git a/git-sh-i18n.html b/git-sh-i18n.html index b66da6e91..80a63de30 100644 --- a/git-sh-i18n.html +++ b/git-sh-i18n.html @@ -807,7 +807,7 @@ eval_gettext diff --git a/git-sh-setup.html b/git-sh-setup.html index 15f6c34f7..d12a58b22 100644 --- a/git-sh-setup.html +++ b/git-sh-setup.html @@ -902,7 +902,7 @@ create_virtual_base diff --git a/git-shell.html b/git-shell.html index 8f46133c2..675ea2d8f 100644 --- a/git-shell.html +++ b/git-shell.html @@ -873,7 +873,7 @@ contrib/git-shell-commands/README

diff --git a/git-shortlog.html b/git-shortlog.html index 28d23dc08..4d8bfb180 100644 --- a/git-shortlog.html +++ b/git-shortlog.html @@ -2017,7 +2017,7 @@ the current directory.

diff --git a/git-show-branch.html b/git-show-branch.html index c1a467504..4ca59ad4f 100644 --- a/git-show-branch.html +++ b/git-show-branch.html @@ -1066,7 +1066,7 @@ showBranch.default diff --git a/git-show-index.html b/git-show-index.html index 8fae1c11a..e7f9367d4 100644 --- a/git-show-index.html +++ b/git-show-index.html @@ -824,7 +824,7 @@ repositories may change in backwards-incompatible ways. Only use diff --git a/git-show-ref.html b/git-show-ref.html index 4fbb3d42a..d52485dc0 100644 --- a/git-show-ref.html +++ b/git-show-ref.html @@ -977,7 +977,7 @@ flag, so you can do

diff --git a/git-show.html b/git-show.html index e58cf6f28..22583535b 100644 --- a/git-show.html +++ b/git-show.html @@ -3738,7 +3738,7 @@ reversible operation.

diff --git a/git-sparse-checkout.html b/git-sparse-checkout.html index b89b100cf..c5200b9e2 100644 --- a/git-sparse-checkout.html +++ b/git-sparse-checkout.html @@ -1289,7 +1289,7 @@ of these restrictions.

diff --git a/git-stage.html b/git-stage.html index 204ae39df..e401cd67b 100644 --- a/git-stage.html +++ b/git-stage.html @@ -772,7 +772,7 @@ documentation of that command.

diff --git a/git-stash.html b/git-stash.html index dddd48949..b74eaf07f 100644 --- a/git-stash.html +++ b/git-stash.html @@ -1327,7 +1327,7 @@ stash.showStat diff --git a/git-status.html b/git-status.html index ec064b9ee..3804e58e9 100644 --- a/git-status.html +++ b/git-status.html @@ -1377,7 +1377,7 @@ using git --no-optional-locks status (see git(1) diff --git a/git-stripspace.html b/git-stripspace.html index 36c2cfe0d..aa65cf6cc 100644 --- a/git-stripspace.html +++ b/git-stripspace.html @@ -876,7 +876,7 @@ the repository.

diff --git a/git-submodule.html b/git-submodule.html index a1034c215..2f1d65e5e 100644 --- a/git-submodule.html +++ b/git-submodule.html @@ -1410,7 +1410,7 @@ for details.

diff --git a/git-svn.html b/git-svn.html index 26baae2bd..b52b294c8 100644 --- a/git-svn.html +++ b/git-svn.html @@ -2514,7 +2514,7 @@ and imports all SVN tags as branches, prefixing the tag name with tags/ diff --git a/git-switch.html b/git-switch.html index 6106d7415..bdbe81e45 100644 --- a/git-switch.html +++ b/git-switch.html @@ -1199,7 +1199,7 @@ checkout.thresholdForParallelism diff --git a/git-symbolic-ref.html b/git-symbolic-ref.html index 052bc45f4..87743c3e7 100644 --- a/git-symbolic-ref.html +++ b/git-symbolic-ref.html @@ -863,7 +863,7 @@ name is not a symbolic ref, or 128 if another error occurs.

diff --git a/git-tag.html b/git-tag.html index a85796d26..e4935e6e7 100644 --- a/git-tag.html +++ b/git-tag.html @@ -1339,7 +1339,7 @@ commits and from none of the --no-merged commits are shown.

Last updated - 2022-10-28 11:53:56 PDT + 2022-10-29 03:53:56 JST
diff --git a/git-unpack-file.html b/git-unpack-file.html index 4e058a94d..601312ad5 100644 --- a/git-unpack-file.html +++ b/git-unpack-file.html @@ -788,7 +788,7 @@ returns the name of the temporary file in the following format: diff --git a/git-unpack-objects.html b/git-unpack-objects.html index da0e9a997..c96452ff1 100644 --- a/git-unpack-objects.html +++ b/git-unpack-objects.html @@ -830,7 +830,7 @@ new packs and replace existing ones.

diff --git a/git-update-index.html b/git-update-index.html index 8997f1b40..ba5cf63b2 100644 --- a/git-update-index.html +++ b/git-update-index.html @@ -1546,7 +1546,7 @@ automatically.

diff --git a/git-update-ref.html b/git-update-ref.html index 4fd37bc7b..075a815b0 100644 --- a/git-update-ref.html +++ b/git-update-ref.html @@ -974,7 +974,7 @@ or does not have committer information available.

diff --git a/git-update-server-info.html b/git-update-server-info.html index 681a5082f..7ed30e46c 100644 --- a/git-update-server-info.html +++ b/git-update-server-info.html @@ -813,7 +813,7 @@ info/refs diff --git a/git-upload-archive.html b/git-upload-archive.html index c60273b05..7240ffbf7 100644 --- a/git-upload-archive.html +++ b/git-upload-archive.html @@ -832,7 +832,7 @@ access via non-smart-http.

diff --git a/git-upload-pack.html b/git-upload-pack.html index c12d89dc4..6fd17b46d 100644 --- a/git-upload-pack.html +++ b/git-upload-pack.html @@ -854,7 +854,7 @@ repository. For push operations, see git send-pack.

diff --git a/git-var.html b/git-var.html index d0d0b3a88..f7e1c3d1c 100644 --- a/git-var.html +++ b/git-var.html @@ -864,7 +864,7 @@ GIT_DEFAULT_BRANCH diff --git a/git-verify-commit.html b/git-verify-commit.html index 5d96af43f..6f5ace1bb 100644 --- a/git-verify-commit.html +++ b/git-verify-commit.html @@ -806,7 +806,7 @@ git-verify-commit(1) Manual Page diff --git a/git-verify-pack.html b/git-verify-pack.html index 3b18d241e..4e8b6da37 100644 --- a/git-verify-pack.html +++ b/git-verify-pack.html @@ -836,7 +836,7 @@ corresponding pack file.

diff --git a/git-verify-tag.html b/git-verify-tag.html index 3e1786e1c..c7985cc38 100644 --- a/git-verify-tag.html +++ b/git-verify-tag.html @@ -806,7 +806,7 @@ git-verify-tag(1) Manual Page diff --git a/git-version.html b/git-version.html index 689a0e37c..f0cd99551 100644 --- a/git-version.html +++ b/git-version.html @@ -789,7 +789,7 @@ former is internally converted into the latter.

diff --git a/git-web--browse.html b/git-web--browse.html index 60e675aaf..35c3a9152 100644 --- a/git-web--browse.html +++ b/git-web--browse.html @@ -964,7 +964,7 @@ See git-config(1) for more information about this. diff --git a/git-whatchanged.html b/git-whatchanged.html index 5f46b7839..8625a01b1 100644 --- a/git-whatchanged.html +++ b/git-whatchanged.html @@ -803,7 +803,7 @@ reading Linux kernel mailing list are trained to type it.

diff --git a/git-worktree.html b/git-worktree.html index 665388379..72bbb6a0f 100644 --- a/git-worktree.html +++ b/git-worktree.html @@ -1380,7 +1380,7 @@ checkouts of a superproject.

diff --git a/git-write-tree.html b/git-write-tree.html index 49ed13fcd..cd1d4499b 100644 --- a/git-write-tree.html +++ b/git-write-tree.html @@ -805,7 +805,7 @@ now, you need to have done a git update-index phase before you did the diff --git a/git.html b/git.html index 6cc9f13fb..8c94130fb 100644 --- a/git.html +++ b/git.html @@ -3807,7 +3807,7 @@ the Git Security mailing list <
Last updated - 2022-10-10 14:40:17 PDT + 2022-10-11 06:40:17 JST
diff --git a/gitattributes.html b/gitattributes.html index 3b19bfdd5..b428c6b8d 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -2202,7 +2202,7 @@ frotz unspecified diff --git a/gitcli.html b/gitcli.html index 63e928d3e..0d5500724 100644 --- a/gitcli.html +++ b/gitcli.html @@ -1052,7 +1052,7 @@ The two options can be specified together to ask a command to work diff --git a/gitcore-tutorial.html b/gitcore-tutorial.html index 8821f1d40..1f2c8b2b8 100644 --- a/gitcore-tutorial.html +++ b/gitcore-tutorial.html @@ -2458,7 +2458,7 @@ to follow, not easier.

diff --git a/gitcredentials.html b/gitcredentials.html index 41527658f..71737cd8a 100644 --- a/gitcredentials.html +++ b/gitcredentials.html @@ -1077,7 +1077,8 @@ FORMAT in git-credential(1) for a detai stdout in the same format (see 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.

+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 password.

@@ -1107,7 +1108,7 @@ helpers will just ignore the new requests).

diff --git a/gitcredentials.txt b/gitcredentials.txt index 6df50e8a1..d6665d2f3 100644 --- a/gitcredentials.txt +++ b/gitcredentials.txt @@ -270,6 +270,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 diff --git a/gitcvs-migration.html b/gitcvs-migration.html index 2018d1ab9..a4dbd62d6 100644 --- a/gitcvs-migration.html +++ b/gitcvs-migration.html @@ -957,7 +957,7 @@ repositories without the need for a central maintainer.

diff --git a/gitdiffcore.html b/gitdiffcore.html index 48120c50f..4078cfb4e 100644 --- a/gitdiffcore.html +++ b/gitdiffcore.html @@ -1108,7 +1108,7 @@ not sorted when diffcore-order is in effect.

diff --git a/giteveryday.html b/giteveryday.html index 6863bd515..be16520bc 100644 --- a/giteveryday.html +++ b/giteveryday.html @@ -1546,7 +1546,7 @@ create and push version tags. diff --git a/gitfaq.html b/gitfaq.html index 3ca5875c2..70aba080d 100644 --- a/gitfaq.html +++ b/gitfaq.html @@ -1262,7 +1262,7 @@ platform.

diff --git a/gitformat-bundle.html b/gitformat-bundle.html index 59269de6f..f3effc550 100644 --- a/gitformat-bundle.html +++ b/gitformat-bundle.html @@ -879,7 +879,7 @@ bundle to abort.

diff --git a/gitformat-chunk.html b/gitformat-chunk.html index a38231614..f88892183 100644 --- a/gitformat-chunk.html +++ b/gitformat-chunk.html @@ -888,7 +888,7 @@ for future formats:

diff --git a/gitformat-commit-graph.html b/gitformat-commit-graph.html index feaa323ed..48084b510 100644 --- a/gitformat-commit-graph.html +++ b/gitformat-commit-graph.html @@ -1076,7 +1076,7 @@ chunks and write the new information without trusting the incorrect data.

Last updated - 2022-11-11 23:55:30 PST + 2022-11-12 16:55:30 JST
diff --git a/gitformat-index.html b/gitformat-index.html index c8b0a684e..801dd92c9 100644 --- a/gitformat-index.html +++ b/gitformat-index.html @@ -1489,7 +1489,7 @@ this extension. diff --git a/gitformat-pack.html b/gitformat-pack.html index 9d5429b6e..a924e70ae 100644 --- a/gitformat-pack.html +++ b/gitformat-pack.html @@ -1595,7 +1595,7 @@ scratch.

diff --git a/gitformat-signature.html b/gitformat-signature.html index 27d7e5650..0e56adc6b 100644 --- a/gitformat-signature.html +++ b/gitformat-signature.html @@ -1035,7 +1035,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000 diff --git a/gitglossary.html b/gitglossary.html index 6d0632f87..7633c1eec 100644 --- a/gitglossary.html +++ b/gitglossary.html @@ -1973,7 +1973,7 @@ The most notable example is HEAD.

diff --git a/githooks.html b/githooks.html index ab7e1fb15..5b1737d3c 100644 --- a/githooks.html +++ b/githooks.html @@ -1383,7 +1383,7 @@ running passing "1", "1" should not be possible.

diff --git a/gitignore.html b/gitignore.html index 4252d5687..e30dcec23 100644 --- a/gitignore.html +++ b/gitignore.html @@ -1071,7 +1071,7 @@ everything within foo/bar):

diff --git a/gitk.html b/gitk.html index e185f8985..8078bbacc 100644 --- a/gitk.html +++ b/gitk.html @@ -1101,7 +1101,7 @@ of end users.

diff --git a/gitmailmap.html b/gitmailmap.html index 0e095185a..21e042161 100644 --- a/gitmailmap.html +++ b/gitmailmap.html @@ -892,7 +892,7 @@ Jane Doe <jane@example.com> Jane <bugs@example.com> diff --git a/gitmodules.html b/gitmodules.html index 810766457..2d9c2a9f0 100644 --- a/gitmodules.html +++ b/gitmodules.html @@ -948,7 +948,7 @@ submodules a URL is specified which can be used for cloning the submodules.

< diff --git a/gitnamespaces.html b/gitnamespaces.html index 5f21d87da..df10c2142 100644 --- a/gitnamespaces.html +++ b/gitnamespaces.html @@ -850,7 +850,7 @@ As in #1, the attacker chooses an object ID X to steal. The victim sends diff --git a/gitprotocol-capabilities.html b/gitprotocol-capabilities.html index e653f9321..de3e511f9 100644 --- a/gitprotocol-capabilities.html +++ b/gitprotocol-capabilities.html @@ -1154,7 +1154,7 @@ and users of the session ID should not rely on this fact.

diff --git a/gitprotocol-common.html b/gitprotocol-common.html index 3bfaab6a9..a69fb6c90 100644 --- a/gitprotocol-common.html +++ b/gitprotocol-common.html @@ -889,7 +889,7 @@ pkt-line ("0004").

diff --git a/gitprotocol-http.html b/gitprotocol-http.html index 62f55c8f2..1e6711aad 100644 --- a/gitprotocol-http.html +++ b/gitprotocol-http.html @@ -1279,7 +1279,7 @@ update = old_id SP new_id SP name diff --git a/gitprotocol-pack.html b/gitprotocol-pack.html index 0dfa78382..964e5991c 100644 --- a/gitprotocol-pack.html +++ b/gitprotocol-pack.html @@ -1494,7 +1494,7 @@ can be rejected.

diff --git a/gitprotocol-v2.html b/gitprotocol-v2.html index 11ed3aa23..a4ff6ee1f 100644 --- a/gitprotocol-v2.html +++ b/gitprotocol-v2.html @@ -1497,7 +1497,7 @@ and associated requested information, each separated by a single space.

Last updated - 2022-09-21 15:44:34 PDT + 2022-09-22 07:44:34 JST
diff --git a/gitremote-helpers.html b/gitremote-helpers.html index 57b295833..5181b9d62 100644 --- a/gitremote-helpers.html +++ b/gitremote-helpers.html @@ -1537,7 +1537,7 @@ the remote side using that algorithm.

diff --git a/gitrepository-layout.html b/gitrepository-layout.html index bd1714a54..498e6ed01 100644 --- a/gitrepository-layout.html +++ b/gitrepository-layout.html @@ -1372,7 +1372,7 @@ GIT_COMMON_DIR/worktrees/<id>/config.worktree)

diff --git a/gitrevisions.html b/gitrevisions.html index ff806000d..d14c7e17b 100644 --- a/gitrevisions.html +++ b/gitrevisions.html @@ -1342,7 +1342,7 @@ spelt out:

diff --git a/gitsubmodules.html b/gitsubmodules.html index c98b3c2e1..01fa73159 100644 --- a/gitsubmodules.html +++ b/gitsubmodules.html @@ -1113,7 +1113,7 @@ affects other Git commands, see git-config(1) for diff --git a/gittutorial-2.html b/gittutorial-2.html index 4be9cc51e..3f6717bad 100644 --- a/gittutorial-2.html +++ b/gittutorial-2.html @@ -1171,7 +1171,7 @@ example, creating a new commit.

diff --git a/gittutorial.html b/gittutorial.html index 7475771f4..169363367 100644 --- a/gittutorial.html +++ b/gittutorial.html @@ -1375,7 +1375,7 @@ digressions that may be interesting at this point are:

diff --git a/gitweb.conf.html b/gitweb.conf.html index 34a32cce9..d084c11b2 100644 --- a/gitweb.conf.html +++ b/gitweb.conf.html @@ -2015,7 +2015,7 @@ gitweb_config.perl diff --git a/gitweb.html b/gitweb.html index 0bd2ecb3c..946c9fd6d 100644 --- a/gitweb.html +++ b/gitweb.html @@ -1642,7 +1642,7 @@ putting "gitweb" in the subject of email.

diff --git a/gitworkflows.html b/gitworkflows.html index 4c63bc675..e68de91f5 100644 --- a/gitworkflows.html +++ b/gitworkflows.html @@ -1225,7 +1225,7 @@ other options.

diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html index 3dcdef9f9..df45d31e8 100644 --- a/howto/coordinate-embargoed-releases.html +++ b/howto/coordinate-embargoed-releases.html @@ -1038,7 +1038,7 @@ Thanks, diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 38f9074a3..5d37ed8d5 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html @@ -938,7 +938,7 @@ tip of your master again and redo the two merges:

diff --git a/howto/maintain-git.html b/howto/maintain-git.html index 140c2ffc1..283a192c3 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html @@ -1469,7 +1469,7 @@ $ git update-ref -d $mf/ai/topic diff --git a/howto/new-command.html b/howto/new-command.html index fa12bfaab..47a0bf388 100644 --- a/howto/new-command.html +++ b/howto/new-command.html @@ -863,7 +863,7 @@ letter [PATCH 0/n]. diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index fecce60c1..ff382b4e9 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html @@ -895,7 +895,7 @@ the #1' commit.

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index c8e359cdd..bc3026a1d 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html @@ -847,7 +847,7 @@ This is still crude and does not protect against simultaneous diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index 386eada60..0ca3d8e3f 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html @@ -880,7 +880,7 @@ thing.

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index 025c86519..16ba0b283 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html @@ -1189,7 +1189,7 @@ int main(int argc, char **argv) diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 718292b11..f55dc1daa 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html @@ -1025,7 +1025,7 @@ P---o---o---M---x---x---W---x---M2 diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index 75bcf23d8..6287c564c 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html @@ -907,7 +907,7 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index ab3060ab0..0c83c9cba 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html @@ -841,7 +841,7 @@ o---o"master" diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index 1d52cb10e..3e9b0bfbd 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html @@ -1071,7 +1071,7 @@ help diagnosing the problem, but removes security checks.

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index ad062b79c..464447fea 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html @@ -930,7 +930,7 @@ that JC can make non-fast-forward pushes on it.

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 43175953c..4676ce398 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html @@ -791,7 +791,7 @@ a good practice to put the paths after a "--" separator.

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index e0965fd85..bcf66b068 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html @@ -848,7 +848,7 @@ Please note that if the other project merges from you, then it will diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index 758ddc6d6..948a49380 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html @@ -952,7 +952,7 @@ as part of the merge commit.

diff --git a/scalar.html b/scalar.html index c47ab5e65..f65518f97 100644 --- a/scalar.html +++ b/scalar.html @@ -988,7 +988,7 @@ delete <enlistment> diff --git a/technical/api-error-handling.html b/technical/api-error-handling.html index 70dbbf693..8ac61624e 100644 --- a/technical/api-error-handling.html +++ b/technical/api-error-handling.html @@ -878,7 +878,7 @@ a message, pass a strbuf that is explicitly ignored:

diff --git a/technical/api-index.html b/technical/api-index.html index 5e55ee5ba..ece065f38 100644 --- a/technical/api-index.html +++ b/technical/api-index.html @@ -775,7 +775,7 @@ documents them.

diff --git a/technical/api-merge.html b/technical/api-merge.html index 3f7f49e5a..86078aab1 100644 --- a/technical/api-merge.html +++ b/technical/api-merge.html @@ -801,7 +801,7 @@ and diff.c for examples.

diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html index ed4a928a8..daadb3afa 100644 --- a/technical/api-parse-options.html +++ b/technical/api-parse-options.html @@ -1351,7 +1351,7 @@ for real-world examples.

diff --git a/technical/api-simple-ipc.html b/technical/api-simple-ipc.html index bd771786a..ed29134ab 100644 --- a/technical/api-simple-ipc.html +++ b/technical/api-simple-ipc.html @@ -840,7 +840,7 @@ layer to focus on the application at hand.

diff --git a/technical/api-trace2.html b/technical/api-trace2.html index e0ceee971..73f339d61 100644 --- a/technical/api-trace2.html +++ b/technical/api-trace2.html @@ -2354,7 +2354,7 @@ Trace2 targets (and convert <key> to a "category"). diff --git a/technical/bitmap-format.html b/technical/bitmap-format.html index 3a06697df..4245ec761 100644 --- a/technical/bitmap-format.html +++ b/technical/bitmap-format.html @@ -1208,7 +1208,7 @@ xor_row (4 byte integer, network byte order): diff --git a/technical/bundle-uri.html b/technical/bundle-uri.html index 10ee76499..bf7004393 100644 --- a/technical/bundle-uri.html +++ b/technical/bundle-uri.html @@ -1463,7 +1463,7 @@ would cause these on-demand downloads to be too aggressive.

diff --git a/technical/hash-function-transition.html b/technical/hash-function-transition.html index 1874731c0..eb8875e44 100644 --- a/technical/hash-function-transition.html +++ b/technical/hash-function-transition.html @@ -2087,7 +2087,7 @@ See the history of this file in git.git for the history of subsequent diff --git a/technical/long-running-process-protocol.html b/technical/long-running-process-protocol.html index 777db24f2..3f7a323c5 100644 --- a/technical/long-running-process-protocol.html +++ b/technical/long-running-process-protocol.html @@ -795,7 +795,7 @@ process has stopped.

diff --git a/technical/multi-pack-index.html b/technical/multi-pack-index.html index 2188c629b..a760eac89 100644 --- a/technical/multi-pack-index.html +++ b/technical/multi-pack-index.html @@ -912,7 +912,7 @@ Packfiles can be marked as "special" using empty files that share diff --git a/technical/pack-heuristics.html b/technical/pack-heuristics.html index 65a36f3a9..3ab961bc6 100644 --- a/technical/pack-heuristics.html +++ b/technical/pack-heuristics.html @@ -1343,7 +1343,7 @@ so obvious that they never go anywhere. diff --git a/technical/parallel-checkout.html b/technical/parallel-checkout.html index 7a2ae5e47..82327d072 100644 --- a/technical/parallel-checkout.html +++ b/technical/parallel-checkout.html @@ -1075,7 +1075,7 @@ err |= run_parallel_checkout(&state, pc_workers, pc_threshold, NULL, NULL);< diff --git a/technical/partial-clone.html b/technical/partial-clone.html index c0317939c..5cae78085 100644 --- a/technical/partial-clone.html +++ b/technical/partial-clone.html @@ -1213,7 +1213,7 @@ type of packfile that references it.

diff --git a/technical/racy-git.html b/technical/racy-git.html index cdc25021d..08bbee7bb 100644 --- a/technical/racy-git.html +++ b/technical/racy-git.html @@ -952,7 +952,7 @@ practice anymore. This was done with commit 0fc82cff on Aug 15, diff --git a/technical/reftable.html b/technical/reftable.html index 16c612f24..0b0183824 100644 --- a/technical/reftable.html +++ b/technical/reftable.html @@ -2056,7 +2056,7 @@ impossible.

diff --git a/technical/scalar.html b/technical/scalar.html index 12b4355d0..9589cd3d5 100644 --- a/technical/scalar.html +++ b/technical/scalar.html @@ -833,7 +833,7 @@ built and installed as its own executable in the bin/ directory, al diff --git a/technical/send-pack-pipeline.html b/technical/send-pack-pipeline.html index 18d17d7db..d05ab849d 100644 --- a/technical/send-pack-pipeline.html +++ b/technical/send-pack-pipeline.html @@ -827,7 +827,7 @@ closes the reading side of the pipe and fd to receive-pack.

diff --git a/technical/shallow.html b/technical/shallow.html index d3be7235e..81d7d7e5b 100644 --- a/technical/shallow.html +++ b/technical/shallow.html @@ -813,7 +813,7 @@ number a signed 32-bit integer can contain) means infinite depth.

diff --git a/technical/sparse-checkout.txt b/technical/sparse-checkout.txt new file mode 100644 index 000000000..fa0d01cbd --- /dev/null +++ b/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 + + * + * + * + * + +* 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 () + + * 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 (, 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 ` 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 + git rm + 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/technical/trivial-merge.html b/technical/trivial-merge.html index 5d7c6341b..b0ac6f4a4 100644 --- a/technical/trivial-merge.html +++ b/technical/trivial-merge.html @@ -856,7 +856,7 @@ the automatic merge will generally give this effect.

-- cgit 1.2.3-korg