From 9c919c74b7fda282913220a8f9af0f70d47a194c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 9 Dec 2023 17:43:11 -0800 Subject: [PATCH] Autogenerated HTML docs for v2.43.0-76-g1a87c --- MyFirstContribution.html | 4 +- MyFirstObjectWalk.html | 4 +- RelNotes/2.44.0.txt | 43 + ReviewingGuidelines.html | 4 +- SubmittingPatches.html | 4 +- ToolsForGit.html | 4 +- everyday.html | 4 +- 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 | 6 +- git-count-objects.html | 2 +- git-credential-cache--daemon.html | 2 +- git-credential-cache.html | 2 +- git-credential-store.html | 2 +- git-credential.html | 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 | 23 +- git-for-each-ref.txt | 23 +- 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 | 40 +- git-rebase.txt | 34 +- git-receive-pack.html | 2 +- git-reflog.html | 2 +- git-remote-ext.html | 2 +- git-remote-fd.html | 2 +- git-remote-helpers.html | 4 +- git-remote.html | 2 +- git-repack.html | 2 +- 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 | 2 +- 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 | 4 +- howto/maintain-git.html | 4 +- howto/new-command.html | 4 +- howto/rebase-from-internal-branch.html | 4 +- howto/rebuild-from-update-hook.html | 4 +- howto/recover-corrupted-blob-object.html | 4 +- howto/recover-corrupted-object-harder.html | 4 +- howto/revert-a-faulty-merge.html | 4 +- howto/revert-branch-rebase.html | 4 +- howto/separating-topic-branches.html | 4 +- howto/setup-git-server-over-http.html | 4 +- howto/update-hook-example.html | 4 +- howto/use-git-daemon.html | 4 +- howto/using-merge-subtree.html | 4 +- howto/using-signed-tag-in-pull-request.html | 4 +- scalar.html | 2 +- technical/api-error-handling.html | 4 +- technical/api-index.html | 4 +- technical/api-merge.html | 4 +- technical/api-parse-options.html | 4 +- technical/api-simple-ipc.html | 4 +- technical/api-trace2.html | 4 +- technical/bitmap-format.html | 4 +- technical/bundle-uri.html | 4 +- technical/hash-function-transition.html | 4 +- technical/long-running-process-protocol.html | 4 +- technical/multi-pack-index.html | 4 +- technical/pack-heuristics.html | 4 +- technical/parallel-checkout.html | 4 +- technical/partial-clone.html | 4 +- technical/racy-git.html | 4 +- technical/reftable.html | 2 +- technical/scalar.html | 4 +- technical/send-pack-pipeline.html | 4 +- technical/shallow.html | 4 +- technical/trivial-merge.html | 4 +- technical/unit-tests.html | 1216 ++++++++++++++++++ technical/unit-tests.txt | 240 ++++ user-manual.html | 2 +- 244 files changed, 1846 insertions(+), 333 deletions(-) create mode 100644 RelNotes/2.44.0.txt create mode 100644 technical/unit-tests.html create mode 100644 technical/unit-tests.txt diff --git a/MyFirstContribution.html b/MyFirstContribution.html index 343944b05..d8e32043a 100644 --- a/MyFirstContribution.html +++ b/MyFirstContribution.html @@ -735,7 +735,7 @@
@@ -2097,7 +2097,7 @@

After Review Approval

diff --git a/MyFirstObjectWalk.html b/MyFirstObjectWalk.html index ac258e167..1542cd608 100644 --- a/MyFirstObjectWalk.html +++ b/MyFirstObjectWalk.html @@ -735,7 +735,7 @@
@@ -1737,7 +1737,7 @@

Wrapping Up

diff --git a/RelNotes/2.44.0.txt b/RelNotes/2.44.0.txt new file mode 100644 index 000000000..6a2bd93c9 --- /dev/null +++ b/RelNotes/2.44.0.txt @@ -0,0 +1,43 @@ +Git v2.44 Release Notes +======================= + +UI, Workflows & Features + + * "git add" and "git stash" learned to support the ":(attr:...)" + magic pathspec. + + * "git rebase --autosquash" is now enabled for non-interactive rebase, + but it is still incompatible with the apply backend. + + +Performance, Internal Implementation, Development Support etc. + + * Process to add some form of low-level unit tests has started. + + * Add support for GitLab CI. + + * "git for-each-ref --no-sort" still sorted the refs alphabetically + which paid non-trivial cost. It has been redefined to show output + in an unspecified order, to allow certain optimizations to take + advantage of. + + +Fixes since v2.43 +----------------- + + * The way CI testing used "prove" could lead to running the test + suite twice needlessly, which has been corrected. + (merge e7e03ef995 js/ci-discard-prove-state later to maint). + + * Update ref-related tests. + + * "git format-patch --encode-email-headers" ignored the option when + preparing the cover letter, which has been corrected. + + * Newer versions of Getopt::Long started giving warnings against our + (ab)use of it in "git send-email". Bump the minimum version + requirement for Perl to 5.8.1 (from September 2002) to allow + simplifying our implementation. + (merge 6ff658cc78 tz/send-email-negatable-options later to maint). + + * Other code cleanup, docfix, build fix, etc. diff --git a/ReviewingGuidelines.html b/ReviewingGuidelines.html index 3a90dc2c8..a8a6d0e72 100644 --- a/ReviewingGuidelines.html +++ b/ReviewingGuidelines.html @@ -735,7 +735,7 @@
@@ -975,7 +975,7 @@

See Also

diff --git a/SubmittingPatches.html b/SubmittingPatches.html index b7f7c8cdd..e3ee3c4ea 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html @@ -735,7 +735,7 @@
@@ -1518,7 +1518,7 @@

Gnus

diff --git a/ToolsForGit.html b/ToolsForGit.html index 6e9b20708..192f53e6f 100644 --- a/ToolsForGit.html +++ b/ToolsForGit.html @@ -735,7 +735,7 @@
@@ -806,7 +806,7 @@

Last updated - 2023-10-24 06:43:46 JST + 2023-10-23 14:43:46 PDT

diff --git a/everyday.html b/everyday.html index 58e5f99e8..9d430f95b 100644 --- a/everyday.html +++ b/everyday.html @@ -735,7 +735,7 @@
@@ -751,7 +751,7 @@

Everyday Git With 20 Commands Or So

diff --git a/git-add.html b/git-add.html index 7e41b4abe..1514e39e9 100644 --- a/git-add.html +++ b/git-add.html @@ -1425,7 +1425,7 @@

GIT

diff --git a/git-am.html b/git-am.html index c38311c00..6546f3a80 100644 --- a/git-am.html +++ b/git-am.html @@ -1289,7 +1289,7 @@

GIT

diff --git a/git-annotate.html b/git-annotate.html index 3ce050a0c..d38dbe2a2 100644 --- a/git-annotate.html +++ b/git-annotate.html @@ -1089,7 +1089,7 @@

GIT

diff --git a/git-apply.html b/git-apply.html index 06b9dffe9..cf6d549c1 100644 --- a/git-apply.html +++ b/git-apply.html @@ -1248,7 +1248,7 @@

GIT

diff --git a/git-archimport.html b/git-archimport.html index 74ae5b094..488402165 100644 --- a/git-archimport.html +++ b/git-archimport.html @@ -905,7 +905,7 @@

GIT

diff --git a/git-archive.html b/git-archive.html index 7ad8d45f1..16a1105f9 100644 --- a/git-archive.html +++ b/git-archive.html @@ -1159,7 +1159,7 @@

GIT

diff --git a/git-bisect.html b/git-bisect.html index 4c30d2f5f..f4b649d1e 100644 --- a/git-bisect.html +++ b/git-bisect.html @@ -1244,7 +1244,7 @@

GIT

diff --git a/git-blame.html b/git-blame.html index af1e0706c..9c0a73b7a 100644 --- a/git-blame.html +++ b/git-blame.html @@ -1498,7 +1498,7 @@

GIT

diff --git a/git-branch.html b/git-branch.html index 33c7c65cc..35b0708ea 100644 --- a/git-branch.html +++ b/git-branch.html @@ -1592,7 +1592,7 @@

GIT

diff --git a/git-bugreport.html b/git-bugreport.html index 32141e732..280115b7c 100644 --- a/git-bugreport.html +++ b/git-bugreport.html @@ -880,7 +880,7 @@

GIT

diff --git a/git-bundle.html b/git-bundle.html index 696f2b00b..2c870b953 100644 --- a/git-bundle.html +++ b/git-bundle.html @@ -1104,7 +1104,7 @@

GIT

diff --git a/git-cat-file.html b/git-cat-file.html index e6bf311b5..21057aacf 100644 --- a/git-cat-file.html +++ b/git-cat-file.html @@ -1342,7 +1342,7 @@

GIT

diff --git a/git-check-attr.html b/git-check-attr.html index 04b989927..be89417ed 100644 --- a/git-check-attr.html +++ b/git-check-attr.html @@ -970,7 +970,7 @@

GIT

diff --git a/git-check-ignore.html b/git-check-ignore.html index 4d72e6dc9..344c29e0b 100644 --- a/git-check-ignore.html +++ b/git-check-ignore.html @@ -924,7 +924,7 @@

GIT

diff --git a/git-check-mailmap.html b/git-check-mailmap.html index a45a0bf97..421cbf80b 100644 --- a/git-check-mailmap.html +++ b/git-check-mailmap.html @@ -811,7 +811,7 @@

GIT

diff --git a/git-check-ref-format.html b/git-check-ref-format.html index 6c92aff00..abcf6ef65 100644 --- a/git-check-ref-format.html +++ b/git-check-ref-format.html @@ -963,7 +963,7 @@

GIT

diff --git a/git-checkout-index.html b/git-checkout-index.html index 313fc64e4..c4c0fd27d 100644 --- a/git-checkout-index.html +++ b/git-checkout-index.html @@ -1020,7 +1020,7 @@

GIT

diff --git a/git-checkout.html b/git-checkout.html index c9d94da28..d9e0cf9bb 100644 --- a/git-checkout.html +++ b/git-checkout.html @@ -1633,7 +1633,7 @@

GIT

diff --git a/git-cherry-pick.html b/git-cherry-pick.html index 3b421e89e..353bbfb4f 100644 --- a/git-cherry-pick.html +++ b/git-cherry-pick.html @@ -1217,7 +1217,7 @@

GIT

diff --git a/git-cherry.html b/git-cherry.html index 6f997f85e..2f5665147 100644 --- a/git-cherry.html +++ b/git-cherry.html @@ -915,7 +915,7 @@

GIT

diff --git a/git-citool.html b/git-citool.html index 2769f7805..c7530ab18 100644 --- a/git-citool.html +++ b/git-citool.html @@ -776,7 +776,7 @@

GIT

diff --git a/git-clean.html b/git-clean.html index 504cfc66f..0e947da77 100644 --- a/git-clean.html +++ b/git-clean.html @@ -992,7 +992,7 @@

GIT

diff --git a/git-clone.html b/git-clone.html index 67194bc86..39b3f6c92 100644 --- a/git-clone.html +++ b/git-clone.html @@ -1513,7 +1513,7 @@

GIT

diff --git a/git-column.html b/git-column.html index 812bc8d2a..bf89dcc59 100644 --- a/git-column.html +++ b/git-column.html @@ -1015,7 +1015,7 @@

GIT

diff --git a/git-commit-graph.html b/git-commit-graph.html index a76d53e72..c7e3188b9 100644 --- a/git-commit-graph.html +++ b/git-commit-graph.html @@ -989,7 +989,7 @@

GIT

diff --git a/git-commit-tree.html b/git-commit-tree.html index e88f69a9c..39a88be85 100644 --- a/git-commit-tree.html +++ b/git-commit-tree.html @@ -1029,7 +1029,7 @@

GIT

diff --git a/git-commit.html b/git-commit.html index e60c16063..539622ffc 100644 --- a/git-commit.html +++ b/git-commit.html @@ -1840,7 +1840,7 @@

GIT

diff --git a/git-config.html b/git-config.html index 217b78084..f79d468ec 100644 --- a/git-config.html +++ b/git-config.html @@ -9656,7 +9656,9 @@

Variables

- If set to true enable --autosquash option by default. + If set to true, enable the --autosquash option of + git-rebase(1) by default for interactive mode. + This can be overridden with the --no-autosquash option.

@@ -11845,7 +11847,7 @@

GIT

diff --git a/git-count-objects.html b/git-count-objects.html index 5cd64553d..d54a5c898 100644 --- a/git-count-objects.html +++ b/git-count-objects.html @@ -815,7 +815,7 @@

GIT

diff --git a/git-credential-cache--daemon.html b/git-credential-cache--daemon.html index 35672fcd5..0b7a87414 100644 --- a/git-credential-cache--daemon.html +++ b/git-credential-cache--daemon.html @@ -786,7 +786,7 @@

GIT

diff --git a/git-credential-cache.html b/git-credential-cache.html index 0ef9e6c77..bfe10c977 100644 --- a/git-credential-cache.html +++ b/git-credential-cache.html @@ -845,7 +845,7 @@

GIT

diff --git a/git-credential-store.html b/git-credential-store.html index 8b01eacd8..c64a1ae50 100644 --- a/git-credential-store.html +++ b/git-credential-store.html @@ -882,7 +882,7 @@

GIT

diff --git a/git-credential.html b/git-credential.html index 614f6b019..ce596fc64 100644 --- a/git-credential.html +++ b/git-credential.html @@ -986,7 +986,7 @@

GIT

diff --git a/git-cvsexportcommit.html b/git-cvsexportcommit.html index 5f2236503..71f742872 100644 --- a/git-cvsexportcommit.html +++ b/git-cvsexportcommit.html @@ -951,7 +951,7 @@

GIT

diff --git a/git-cvsimport.html b/git-cvsimport.html index 83ecbbe0c..af3a9caee 100644 --- a/git-cvsimport.html +++ b/git-cvsimport.html @@ -1107,7 +1107,7 @@

GIT

diff --git a/git-cvsserver.html b/git-cvsserver.html index a675dc4ca..a9f96a95b 100644 --- a/git-cvsserver.html +++ b/git-cvsserver.html @@ -1327,7 +1327,7 @@

GIT

diff --git a/git-daemon.html b/git-daemon.html index f30e5b9ff..5e2fa7ad5 100644 --- a/git-daemon.html +++ b/git-daemon.html @@ -1281,7 +1281,7 @@

GIT

diff --git a/git-describe.html b/git-describe.html index 144f232ae..43efd6c88 100644 --- a/git-describe.html +++ b/git-describe.html @@ -1042,7 +1042,7 @@

GIT

diff --git a/git-diagnose.html b/git-diagnose.html index 505b40e4c..4fc838819 100644 --- a/git-diagnose.html +++ b/git-diagnose.html @@ -858,7 +858,7 @@

GIT

diff --git a/git-diff-files.html b/git-diff-files.html index 9077941fe..2c512cf73 100644 --- a/git-diff-files.html +++ b/git-diff-files.html @@ -2716,7 +2716,7 @@

GIT

diff --git a/git-diff-index.html b/git-diff-index.html index 68865ed7b..238db47ca 100644 --- a/git-diff-index.html +++ b/git-diff-index.html @@ -2810,7 +2810,7 @@

GIT

diff --git a/git-diff-tree.html b/git-diff-tree.html index 1fed50f81..54ca361f9 100644 --- a/git-diff-tree.html +++ b/git-diff-tree.html @@ -4044,7 +4044,7 @@

GIT

diff --git a/git-diff.html b/git-diff.html index e81d8a1f3..34f703e50 100644 --- a/git-diff.html +++ b/git-diff.html @@ -3679,7 +3679,7 @@

GIT

diff --git a/git-difftool.html b/git-difftool.html index d55bfc48f..62858e6a9 100644 --- a/git-difftool.html +++ b/git-difftool.html @@ -1055,7 +1055,7 @@

GIT

diff --git a/git-fast-export.html b/git-fast-export.html index 5de4830b3..fa7da2179 100644 --- a/git-fast-export.html +++ b/git-fast-export.html @@ -1120,7 +1120,7 @@

GIT

diff --git a/git-fast-import.html b/git-fast-import.html index ee86b99c8..a7047a374 100644 --- a/git-fast-import.html +++ b/git-fast-import.html @@ -2640,7 +2640,7 @@

GIT

diff --git a/git-fetch-pack.html b/git-fetch-pack.html index ae0cb506b..95a4f984f 100644 --- a/git-fetch-pack.html +++ b/git-fetch-pack.html @@ -983,7 +983,7 @@

GIT

diff --git a/git-fetch.html b/git-fetch.html index 18406e8f2..1fdd6118b 100644 --- a/git-fetch.html +++ b/git-fetch.html @@ -2237,7 +2237,7 @@

GIT

diff --git a/git-filter-branch.html b/git-filter-branch.html index bb44565f2..73d68b573 100644 --- a/git-filter-branch.html +++ b/git-filter-branch.html @@ -1626,7 +1626,7 @@

GIT

diff --git a/git-fmt-merge-msg.html b/git-fmt-merge-msg.html index 448dc1fe7..6966f1e8b 100644 --- a/git-fmt-merge-msg.html +++ b/git-fmt-merge-msg.html @@ -917,7 +917,7 @@

GIT

diff --git a/git-for-each-ref.html b/git-for-each-ref.html index 6798e1129..a9d5256bc 100644 --- a/git-for-each-ref.html +++ b/git-for-each-ref.html @@ -822,18 +822,14 @@

OPTIONS

- A string that interpolates %(fieldname) from a ref being shown - and the object it points at. If fieldname - is prefixed with an asterisk (*) and the ref points - at a tag object, use the value for the field in the object - which the tag object refers to (instead of the field in the tag object). - When unspecified, <format> defaults to - %(objectname) SPC %(objecttype) TAB %(refname). - It also interpolates %% to %, and %xx where xx - are hex digits interpolates to character with hex code - xx; for example %00 interpolates to \0 (NUL), - %09 to \t (TAB) and %0a to \n (LF). + A string that interpolates %(fieldname) from a ref being shown and + the object it points at. In addition, the string literal %% + renders as % and %xx - where xx are hex digits - renders as + the character with hex code xx. For example, %00 interpolates to + \0 (NUL), %09 to \t (TAB), and %0a to \n (LF).

+

When unspecified, <format> defaults to %(objectname) SPC %(objecttype) +TAB %(refname).

--color[=<when>] @@ -1262,6 +1258,9 @@

FIELD NAMES

fields will correspond to the appropriate date or name-email-date tuple from the committer or tagger fields depending on the object type. These are intended for working on a mix of annotated and lightweight tags.

+

For tag objects, a fieldname prefixed with an asterisk (*) expands to +the fieldname value of the peeled object, rather than that of the tag +object itself.

Fields that have name-email-date tuple as its value (author, committer, and tagger) can be suffixed with name, email, and date to extract the named component. For email fields (authoremail, @@ -1498,7 +1497,7 @@

GIT

diff --git a/git-for-each-ref.txt b/git-for-each-ref.txt index e86d5700d..be9543f68 100644 --- a/git-for-each-ref.txt +++ b/git-for-each-ref.txt @@ -51,17 +51,14 @@ OPTIONS key. --format=:: - A string that interpolates `%(fieldname)` from a ref being shown - and the object it points at. If `fieldname` - is prefixed with an asterisk (`*`) and the ref points - at a tag object, use the value for the field in the object - which the tag object refers to (instead of the field in the tag object). - When unspecified, `` defaults to - `%(objectname) SPC %(objecttype) TAB %(refname)`. - It also interpolates `%%` to `%`, and `%xx` where `xx` - are hex digits interpolates to character with hex code - `xx`; for example `%00` interpolates to `\0` (NUL), - `%09` to `\t` (TAB) and `%0a` to `\n` (LF). + A string that interpolates `%(fieldname)` from a ref being shown and + the object it points at. In addition, the string literal `%%` + renders as `%` and `%xx` - where `xx` are hex digits - renders as + the character with hex code `xx`. For example, `%00` interpolates to + `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). ++ +When unspecified, `` defaults to `%(objectname) SPC %(objecttype) +TAB %(refname)`. --color[=]:: Respect any colors specified in the `--format` option. The @@ -298,6 +295,10 @@ fields will correspond to the appropriate date or name-email-date tuple from the `committer` or `tagger` fields depending on the object type. These are intended for working on a mix of annotated and lightweight tags. +For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to +the `fieldname` value of the peeled object, rather than that of the tag +object itself. + Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. For email fields (`authoremail`, diff --git a/git-for-each-repo.html b/git-for-each-repo.html index 4ee705935..1b269897a 100644 --- a/git-for-each-repo.html +++ b/git-for-each-repo.html @@ -812,7 +812,7 @@

GIT

diff --git a/git-format-patch.html b/git-format-patch.html index 01b19426c..d2e154ad0 100644 --- a/git-format-patch.html +++ b/git-format-patch.html @@ -2618,7 +2618,7 @@

GIT

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

GIT

diff --git a/git-fsck.html b/git-fsck.html index a7999a74b..148c3b9c8 100644 --- a/git-fsck.html +++ b/git-fsck.html @@ -1591,7 +1591,7 @@

GIT

diff --git a/git-fsmonitor--daemon.html b/git-fsmonitor--daemon.html index 7976b2624..d04cb8e67 100644 --- a/git-fsmonitor--daemon.html +++ b/git-fsmonitor--daemon.html @@ -900,7 +900,7 @@

GIT

diff --git a/git-gc.html b/git-gc.html index c22b1447e..cc259c1f9 100644 --- a/git-gc.html +++ b/git-gc.html @@ -1257,7 +1257,7 @@

GIT

diff --git a/git-get-tar-commit-id.html b/git-get-tar-commit-id.html index c79954be1..fe994802b 100644 --- a/git-get-tar-commit-id.html +++ b/git-get-tar-commit-id.html @@ -778,7 +778,7 @@

GIT

diff --git a/git-grep.html b/git-grep.html index ee052fc0d..7ab380ca1 100644 --- a/git-grep.html +++ b/git-grep.html @@ -1489,7 +1489,7 @@

GIT

diff --git a/git-gui.html b/git-gui.html index fbaad6363..d297f8836 100644 --- a/git-gui.html +++ b/git-gui.html @@ -945,7 +945,7 @@

GIT

diff --git a/git-hash-object.html b/git-hash-object.html index c5edeb14e..b55804565 100644 --- a/git-hash-object.html +++ b/git-hash-object.html @@ -855,7 +855,7 @@

GIT

diff --git a/git-help.html b/git-help.html index d2102ac14..1fd38ca06 100644 --- a/git-help.html +++ b/git-help.html @@ -1056,7 +1056,7 @@

GIT

diff --git a/git-hook.html b/git-hook.html index dae55250f..5068e5a84 100644 --- a/git-hook.html +++ b/git-hook.html @@ -824,7 +824,7 @@

GIT

diff --git a/git-http-backend.html b/git-http-backend.html index f020c8da9..a0fb2b867 100644 --- a/git-http-backend.html +++ b/git-http-backend.html @@ -1102,7 +1102,7 @@

GIT

diff --git a/git-http-fetch.html b/git-http-fetch.html index 273318021..0ab1d00fc 100644 --- a/git-http-fetch.html +++ b/git-http-fetch.html @@ -860,7 +860,7 @@

GIT

diff --git a/git-http-push.html b/git-http-push.html index 2e1f9f7df..cf2c85562 100644 --- a/git-http-push.html +++ b/git-http-push.html @@ -908,7 +908,7 @@

GIT

diff --git a/git-imap-send.html b/git-imap-send.html index 6611ce209..959a11ecc 100644 --- a/git-imap-send.html +++ b/git-imap-send.html @@ -1028,7 +1028,7 @@

GIT

diff --git a/git-index-pack.html b/git-index-pack.html index 2488ac732..5555f40fc 100644 --- a/git-index-pack.html +++ b/git-index-pack.html @@ -985,7 +985,7 @@

GIT

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

GIT

diff --git a/git-init.html b/git-init.html index e98713a34..976b0805c 100644 --- a/git-init.html +++ b/git-init.html @@ -1038,7 +1038,7 @@

GIT

diff --git a/git-instaweb.html b/git-instaweb.html index f0e88934b..23f6e050a 100644 --- a/git-instaweb.html +++ b/git-instaweb.html @@ -907,7 +907,7 @@

GIT

diff --git a/git-interpret-trailers.html b/git-interpret-trailers.html index 4b3fce64d..32ee9a6d0 100644 --- a/git-interpret-trailers.html +++ b/git-interpret-trailers.html @@ -1393,7 +1393,7 @@

GIT

diff --git a/git-log.html b/git-log.html index 7c4387939..bdf1a1aa2 100644 --- a/git-log.html +++ b/git-log.html @@ -5666,7 +5666,7 @@

GIT

diff --git a/git-ls-files.html b/git-ls-files.html index 9eeb49905..8c908bc5c 100644 --- a/git-ls-files.html +++ b/git-ls-files.html @@ -1382,7 +1382,7 @@

GIT

diff --git a/git-ls-remote.html b/git-ls-remote.html index 3391bd962..90781ddd3 100644 --- a/git-ls-remote.html +++ b/git-ls-remote.html @@ -987,7 +987,7 @@

GIT

diff --git a/git-ls-tree.html b/git-ls-tree.html index 5d8318607..e20b965a0 100644 --- a/git-ls-tree.html +++ b/git-ls-tree.html @@ -1028,7 +1028,7 @@

GIT

diff --git a/git-mailinfo.html b/git-mailinfo.html index 78995ecdd..749f046ff 100644 --- a/git-mailinfo.html +++ b/git-mailinfo.html @@ -972,7 +972,7 @@

GIT

diff --git a/git-mailsplit.html b/git-mailsplit.html index 939aaef0c..5f1c2dba5 100644 --- a/git-mailsplit.html +++ b/git-mailsplit.html @@ -860,7 +860,7 @@

GIT

diff --git a/git-maintenance.html b/git-maintenance.html index dfe43f1e0..5f0816780 100644 --- a/git-maintenance.html +++ b/git-maintenance.html @@ -1359,7 +1359,7 @@

GIT

diff --git a/git-merge-base.html b/git-merge-base.html index e2a1dc39b..e86337efa 100644 --- a/git-merge-base.html +++ b/git-merge-base.html @@ -1017,7 +1017,7 @@

GIT

diff --git a/git-merge-file.html b/git-merge-file.html index eb821bc5d..ab5fed58c 100644 --- a/git-merge-file.html +++ b/git-merge-file.html @@ -919,7 +919,7 @@

GIT

diff --git a/git-merge-index.html b/git-merge-index.html index d4128b431..2cedbc821 100644 --- a/git-merge-index.html +++ b/git-merge-index.html @@ -852,7 +852,7 @@

GIT

diff --git a/git-merge-one-file.html b/git-merge-one-file.html index 907a4010f..1c961f491 100644 --- a/git-merge-one-file.html +++ b/git-merge-one-file.html @@ -772,7 +772,7 @@

GIT

diff --git a/git-merge-tree.html b/git-merge-tree.html index b46a76301..a429f6aea 100644 --- a/git-merge-tree.html +++ b/git-merge-tree.html @@ -1152,7 +1152,7 @@

GIT

diff --git a/git-merge.html b/git-merge.html index f4d79c058..d5dda7ff8 100644 --- a/git-merge.html +++ b/git-merge.html @@ -2336,7 +2336,7 @@

GIT

diff --git a/git-mergetool--lib.html b/git-mergetool--lib.html index 7f04aab63..6f4780f83 100644 --- a/git-mergetool--lib.html +++ b/git-mergetool--lib.html @@ -832,7 +832,7 @@

GIT

diff --git a/git-mergetool.html b/git-mergetool.html index b1cffd26d..8c8886e54 100644 --- a/git-mergetool.html +++ b/git-mergetool.html @@ -1342,7 +1342,7 @@

GIT

diff --git a/git-mktag.html b/git-mktag.html index 2767aa6d2..037c05c81 100644 --- a/git-mktag.html +++ b/git-mktag.html @@ -828,7 +828,7 @@

GIT

diff --git a/git-mktree.html b/git-mktree.html index 2aa6e0480..1bb98f72d 100644 --- a/git-mktree.html +++ b/git-mktree.html @@ -811,7 +811,7 @@

GIT

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

GIT

diff --git a/git-mv.html b/git-mv.html index ced14c8b3..e928ca73e 100644 --- a/git-mv.html +++ b/git-mv.html @@ -857,7 +857,7 @@

GIT

diff --git a/git-name-rev.html b/git-name-rev.html index 9f83873af..74e35afab 100644 --- a/git-name-rev.html +++ b/git-name-rev.html @@ -903,7 +903,7 @@

GIT

diff --git a/git-notes.html b/git-notes.html index 689a7b6f9..849ec4c76 100644 --- a/git-notes.html +++ b/git-notes.html @@ -1396,7 +1396,7 @@

GIT

diff --git a/git-p4.html b/git-p4.html index ee0d4df6e..ed16cfbd7 100644 --- a/git-p4.html +++ b/git-p4.html @@ -1974,7 +1974,7 @@

GIT

diff --git a/git-pack-objects.html b/git-pack-objects.html index 5b737819a..f5cc212ff 100644 --- a/git-pack-objects.html +++ b/git-pack-objects.html @@ -1388,7 +1388,7 @@

GIT

diff --git a/git-pack-redundant.html b/git-pack-redundant.html index e0002ac5d..92bfb27ba 100644 --- a/git-pack-redundant.html +++ b/git-pack-redundant.html @@ -834,7 +834,7 @@

GIT

diff --git a/git-pack-refs.html b/git-pack-refs.html index d403b921b..851b6de27 100644 --- a/git-pack-refs.html +++ b/git-pack-refs.html @@ -860,7 +860,7 @@

GIT

diff --git a/git-patch-id.html b/git-patch-id.html index 47b008913..2ce031a5b 100644 --- a/git-patch-id.html +++ b/git-patch-id.html @@ -855,7 +855,7 @@

GIT

diff --git a/git-prune-packed.html b/git-prune-packed.html index eca33d4b5..3726c82db 100644 --- a/git-prune-packed.html +++ b/git-prune-packed.html @@ -814,7 +814,7 @@

GIT

diff --git a/git-prune.html b/git-prune.html index 81142d2c8..cdc99c623 100644 --- a/git-prune.html +++ b/git-prune.html @@ -884,7 +884,7 @@

GIT

diff --git a/git-pull.html b/git-pull.html index 5e8b36c77..c32ec00f8 100644 --- a/git-pull.html +++ b/git-pull.html @@ -2314,7 +2314,7 @@

GIT

diff --git a/git-push.html b/git-push.html index fa0be5f05..1aeffea37 100644 --- a/git-push.html +++ b/git-push.html @@ -2181,7 +2181,7 @@

GIT

diff --git a/git-quiltimport.html b/git-quiltimport.html index 0b629e6f7..ea022dc54 100644 --- a/git-quiltimport.html +++ b/git-quiltimport.html @@ -841,7 +841,7 @@

GIT

diff --git a/git-range-diff.html b/git-range-diff.html index 2a75d031f..47321c984 100644 --- a/git-range-diff.html +++ b/git-range-diff.html @@ -1085,7 +1085,7 @@

GIT

diff --git a/git-read-tree.html b/git-read-tree.html index 1bbe705c6..1968d7e86 100644 --- a/git-read-tree.html +++ b/git-read-tree.html @@ -1294,7 +1294,7 @@

GIT

diff --git a/git-rebase.html b/git-rebase.html index a3a44f0e5..dc91f9f38 100644 --- a/git-rebase.html +++ b/git-rebase.html @@ -1545,21 +1545,25 @@

OPTIONS

- When the commit log message begins with "squash! …" or "fixup! …" - or "amend! …", and there is already a commit in the todo list that - matches the same ..., automatically modify the todo list of - rebase -i, so that the commit marked for squashing comes right after - the commit to be modified, and change the action of the moved commit - from pick to squash or fixup or fixup -C respectively. A commit - matches the ... if the commit subject matches, or if the ... refers - to the commit’s hash. As a fall-back, partial matches of the commit - subject work, too. The recommended way to create fixup/amend/squash - commits is by using the --fixup, --fixup=amend: or --fixup=reword: - and --squash options respectively of git-commit(1). -

-

If the --autosquash option is enabled by default using the -configuration variable rebase.autoSquash, this option can be -used to override and disable this setting.

+ Automatically squash commits with specially formatted messages into + previous commits being rebased. If a commit message starts with + "squash! ", "fixup! " or "amend! ", the remainder of the subject line + is taken as a commit specifier, which matches a previous commit if it + matches the subject line or the hash of that commit. If no commit + matches fully, matches of the specifier with the start of commit + subjects are considered. +

+

In the rebase todo list, the actions of squash, fixup and amend commits are +changed from pick to squash, fixup or fixup -C, respectively, and they +are moved right after the commit they modify. The --interactive option can +be used to review and edit the todo list before proceeding.

+

The recommended way to create commits with squash markers is by using the +--squash, --fixup, --fixup=amend: or --fixup=reword: options of +git-commit(1), which take the target commit as an argument and +automatically fill in the subject line of the new commit from that.

+

Settting configuration variable rebase.autoSquash to true enables +auto-squashing by default for interactive rebase. The --no-autosquash +option can be used to override that setting.

See also INCOMPATIBLE OPTIONS below.

@@ -2659,7 +2663,9 @@

CONFIGURATION

- If set to true enable --autosquash option by default. + If set to true, enable the --autosquash option of + git-rebase(1) by default for interactive mode. + This can be overridden with the --no-autosquash option.

@@ -2803,7 +2809,7 @@

GIT

diff --git a/git-rebase.txt b/git-rebase.txt index b4526ca24..1dd6555f6 100644 --- a/git-rebase.txt +++ b/git-rebase.txt @@ -589,21 +589,27 @@ See also INCOMPATIBLE OPTIONS below. --autosquash:: --no-autosquash:: - When the commit log message begins with "squash! ..." or "fixup! ..." - or "amend! ...", and there is already a commit in the todo list that - matches the same `...`, automatically modify the todo list of - `rebase -i`, so that the commit marked for squashing comes right after - the commit to be modified, and change the action of the moved commit - from `pick` to `squash` or `fixup` or `fixup -C` respectively. A commit - matches the `...` if the commit subject matches, or if the `...` refers - to the commit's hash. As a fall-back, partial matches of the commit - subject work, too. The recommended way to create fixup/amend/squash - commits is by using the `--fixup`, `--fixup=amend:` or `--fixup=reword:` - and `--squash` options respectively of linkgit:git-commit[1]. + Automatically squash commits with specially formatted messages into + previous commits being rebased. If a commit message starts with + "squash! ", "fixup! " or "amend! ", the remainder of the subject line + is taken as a commit specifier, which matches a previous commit if it + matches the subject line or the hash of that commit. If no commit + matches fully, matches of the specifier with the start of commit + subjects are considered. + -If the `--autosquash` option is enabled by default using the -configuration variable `rebase.autoSquash`, this option can be -used to override and disable this setting. +In the rebase todo list, the actions of squash, fixup and amend commits are +changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they +are moved right after the commit they modify. The `--interactive` option can +be used to review and edit the todo list before proceeding. ++ +The recommended way to create commits with squash markers is by using the +`--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of +linkgit:git-commit[1], which take the target commit as an argument and +automatically fill in the subject line of the new commit from that. ++ +Settting configuration variable `rebase.autoSquash` to true enables +auto-squashing by default for interactive rebase. The `--no-autosquash` +option can be used to override that setting. + See also INCOMPATIBLE OPTIONS below. diff --git a/git-receive-pack.html b/git-receive-pack.html index 69620116b..25bc415f1 100644 --- a/git-receive-pack.html +++ b/git-receive-pack.html @@ -1094,7 +1094,7 @@

GIT

diff --git a/git-reflog.html b/git-reflog.html index 82cafdf9a..a6265b239 100644 --- a/git-reflog.html +++ b/git-reflog.html @@ -925,7 +925,7 @@

GIT

diff --git a/git-remote-ext.html b/git-remote-ext.html index ad6862a75..7c6850d48 100644 --- a/git-remote-ext.html +++ b/git-remote-ext.html @@ -963,7 +963,7 @@

GIT

diff --git a/git-remote-fd.html b/git-remote-fd.html index e95aa67fc..3bfe8eca3 100644 --- a/git-remote-fd.html +++ b/git-remote-fd.html @@ -843,7 +843,7 @@

GIT

diff --git a/git-remote-helpers.html b/git-remote-helpers.html index bb9430815..4ee301748 100644 --- a/git-remote-helpers.html +++ b/git-remote-helpers.html @@ -735,7 +735,7 @@
@@ -751,7 +751,7 @@

git-remote-helpers

diff --git a/git-remote.html b/git-remote.html index dc22f9c8a..9f04749ff 100644 --- a/git-remote.html +++ b/git-remote.html @@ -1057,7 +1057,7 @@

GIT

diff --git a/git-repack.html b/git-repack.html index 6f3f08baf..ff848c396 100644 --- a/git-repack.html +++ b/git-repack.html @@ -1169,7 +1169,7 @@

GIT

diff --git a/git-replace.html b/git-replace.html index e4a53890b..a61a62620 100644 --- a/git-replace.html +++ b/git-replace.html @@ -971,7 +971,7 @@

GIT

diff --git a/git-request-pull.html b/git-request-pull.html index 7b116a7f0..058ee0c84 100644 --- a/git-request-pull.html +++ b/git-request-pull.html @@ -855,7 +855,7 @@

GIT

diff --git a/git-rerere.html b/git-rerere.html index bd49b4712..335515835 100644 --- a/git-rerere.html +++ b/git-rerere.html @@ -990,7 +990,7 @@

GIT

diff --git a/git-reset.html b/git-reset.html index fb99c427b..0dfcc3530 100644 --- a/git-reset.html +++ b/git-reset.html @@ -1507,7 +1507,7 @@

GIT

diff --git a/git-restore.html b/git-restore.html index b9ef32fe0..04efbff66 100644 --- a/git-restore.html +++ b/git-restore.html @@ -1077,7 +1077,7 @@

GIT

diff --git a/git-rev-list.html b/git-rev-list.html index 51789a417..6d5a95367 100644 --- a/git-rev-list.html +++ b/git-rev-list.html @@ -3770,7 +3770,7 @@

GIT

diff --git a/git-rev-parse.html b/git-rev-parse.html index 6aca71679..01238dcc4 100644 --- a/git-rev-parse.html +++ b/git-rev-parse.html @@ -2151,7 +2151,7 @@

GIT

diff --git a/git-revert.html b/git-revert.html index 842cfa289..ad8b3d8de 100644 --- a/git-revert.html +++ b/git-revert.html @@ -1070,7 +1070,7 @@

GIT

diff --git a/git-rm.html b/git-rm.html index 6b07f8688..ac15f874b 100644 --- a/git-rm.html +++ b/git-rm.html @@ -1033,7 +1033,7 @@

GIT

diff --git a/git-send-email.html b/git-send-email.html index 05ab8cc50..c32eabb54 100644 --- a/git-send-email.html +++ b/git-send-email.html @@ -1834,7 +1834,7 @@

GIT

diff --git a/git-send-pack.html b/git-send-pack.html index e220938b6..7fe9e63d2 100644 --- a/git-send-pack.html +++ b/git-send-pack.html @@ -994,7 +994,7 @@

GIT

diff --git a/git-sh-i18n--envsubst.html b/git-sh-i18n--envsubst.html index a5b9dc097..1aefa501c 100644 --- a/git-sh-i18n--envsubst.html +++ b/git-sh-i18n--envsubst.html @@ -785,7 +785,7 @@

GIT

diff --git a/git-sh-i18n.html b/git-sh-i18n.html index 80a63de30..b66da6e91 100644 --- a/git-sh-i18n.html +++ b/git-sh-i18n.html @@ -807,7 +807,7 @@

GIT

diff --git a/git-sh-setup.html b/git-sh-setup.html index 4d5cb1d74..5ebb9ea7a 100644 --- a/git-sh-setup.html +++ b/git-sh-setup.html @@ -902,7 +902,7 @@

GIT

diff --git a/git-shell.html b/git-shell.html index 675ea2d8f..8f46133c2 100644 --- a/git-shell.html +++ b/git-shell.html @@ -873,7 +873,7 @@

GIT

diff --git a/git-shortlog.html b/git-shortlog.html index 1ac89a3ad..d3d2b1421 100644 --- a/git-shortlog.html +++ b/git-shortlog.html @@ -2037,7 +2037,7 @@

GIT

diff --git a/git-show-branch.html b/git-show-branch.html index a9fdaaed7..d25943de9 100644 --- a/git-show-branch.html +++ b/git-show-branch.html @@ -1065,7 +1065,7 @@

GIT

diff --git a/git-show-index.html b/git-show-index.html index 6e2f2fc7f..4e2a48cde 100644 --- a/git-show-index.html +++ b/git-show-index.html @@ -826,7 +826,7 @@

GIT

diff --git a/git-show-ref.html b/git-show-ref.html index d66f9c56a..2fac233e2 100644 --- a/git-show-ref.html +++ b/git-show-ref.html @@ -1004,7 +1004,7 @@

GIT

diff --git a/git-show.html b/git-show.html index 80b3fd1a4..3c83e4a7a 100644 --- a/git-show.html +++ b/git-show.html @@ -3829,7 +3829,7 @@

GIT

diff --git a/git-sparse-checkout.html b/git-sparse-checkout.html index d8e1c5765..56f600cc5 100644 --- a/git-sparse-checkout.html +++ b/git-sparse-checkout.html @@ -1312,7 +1312,7 @@

GIT

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

GIT

diff --git a/git-stash.html b/git-stash.html index bd4c53846..226e7ac6e 100644 --- a/git-stash.html +++ b/git-stash.html @@ -1327,7 +1327,7 @@

GIT

diff --git a/git-status.html b/git-status.html index eec1c149d..829aa59e3 100644 --- a/git-status.html +++ b/git-status.html @@ -1464,7 +1464,7 @@

GIT

diff --git a/git-stripspace.html b/git-stripspace.html index 1d2eedc2a..5a54c830b 100644 --- a/git-stripspace.html +++ b/git-stripspace.html @@ -876,7 +876,7 @@

GIT

diff --git a/git-submodule.html b/git-submodule.html index 460a20453..5ca592e05 100644 --- a/git-submodule.html +++ b/git-submodule.html @@ -1416,7 +1416,7 @@

GIT

diff --git a/git-svn.html b/git-svn.html index b52b294c8..26baae2bd 100644 --- a/git-svn.html +++ b/git-svn.html @@ -2514,7 +2514,7 @@

GIT

diff --git a/git-switch.html b/git-switch.html index 94213c668..1f9277ff2 100644 --- a/git-switch.html +++ b/git-switch.html @@ -1199,7 +1199,7 @@

GIT

diff --git a/git-symbolic-ref.html b/git-symbolic-ref.html index a0aae080c..0e2558780 100644 --- a/git-symbolic-ref.html +++ b/git-symbolic-ref.html @@ -863,7 +863,7 @@

GIT

diff --git a/git-tag.html b/git-tag.html index 7e260c50a..59571e6cf 100644 --- a/git-tag.html +++ b/git-tag.html @@ -1367,7 +1367,7 @@

GIT

diff --git a/git-unpack-file.html b/git-unpack-file.html index 601312ad5..4e058a94d 100644 --- a/git-unpack-file.html +++ b/git-unpack-file.html @@ -788,7 +788,7 @@

GIT

diff --git a/git-unpack-objects.html b/git-unpack-objects.html index c96452ff1..da0e9a997 100644 --- a/git-unpack-objects.html +++ b/git-unpack-objects.html @@ -830,7 +830,7 @@

GIT

diff --git a/git-update-index.html b/git-update-index.html index 7f04846dd..07d2ca98c 100644 --- a/git-update-index.html +++ b/git-update-index.html @@ -1557,7 +1557,7 @@

GIT

diff --git a/git-update-ref.html b/git-update-ref.html index 861fbc652..6a2c094ee 100644 --- a/git-update-ref.html +++ b/git-update-ref.html @@ -974,7 +974,7 @@

GIT

diff --git a/git-update-server-info.html b/git-update-server-info.html index d1ba95388..b3675ccf4 100644 --- a/git-update-server-info.html +++ b/git-update-server-info.html @@ -813,7 +813,7 @@

GIT

diff --git a/git-upload-archive.html b/git-upload-archive.html index 7240ffbf7..c60273b05 100644 --- a/git-upload-archive.html +++ b/git-upload-archive.html @@ -832,7 +832,7 @@

GIT

diff --git a/git-upload-pack.html b/git-upload-pack.html index b421c6f1f..9a9a70402 100644 --- a/git-upload-pack.html +++ b/git-upload-pack.html @@ -854,7 +854,7 @@

GIT

diff --git a/git-var.html b/git-var.html index 13964d132..4d49b2ac5 100644 --- a/git-var.html +++ b/git-var.html @@ -924,7 +924,7 @@

GIT

diff --git a/git-verify-commit.html b/git-verify-commit.html index 6f5ace1bb..5d96af43f 100644 --- a/git-verify-commit.html +++ b/git-verify-commit.html @@ -806,7 +806,7 @@

GIT

diff --git a/git-verify-pack.html b/git-verify-pack.html index 2ef00f89e..3230d9f73 100644 --- a/git-verify-pack.html +++ b/git-verify-pack.html @@ -836,7 +836,7 @@

GIT

diff --git a/git-verify-tag.html b/git-verify-tag.html index c7985cc38..3e1786e1c 100644 --- a/git-verify-tag.html +++ b/git-verify-tag.html @@ -806,7 +806,7 @@

GIT

diff --git a/git-version.html b/git-version.html index f0cd99551..689a0e37c 100644 --- a/git-version.html +++ b/git-version.html @@ -789,7 +789,7 @@

GIT

diff --git a/git-web--browse.html b/git-web--browse.html index 35c3a9152..60e675aaf 100644 --- a/git-web--browse.html +++ b/git-web--browse.html @@ -964,7 +964,7 @@

GIT

diff --git a/git-whatchanged.html b/git-whatchanged.html index 6a681b5b9..e1280a31f 100644 --- a/git-whatchanged.html +++ b/git-whatchanged.html @@ -803,7 +803,7 @@

GIT

diff --git a/git-worktree.html b/git-worktree.html index 0f02f5936..8eb6c94b2 100644 --- a/git-worktree.html +++ b/git-worktree.html @@ -1399,7 +1399,7 @@

GIT

diff --git a/git-write-tree.html b/git-write-tree.html index cd1d4499b..49ed13fcd 100644 --- a/git-write-tree.html +++ b/git-write-tree.html @@ -805,7 +805,7 @@

GIT

diff --git a/git.html b/git.html index 2d01f0559..07f4de539 100644 --- a/git.html +++ b/git.html @@ -3828,7 +3828,7 @@

GIT

diff --git a/gitattributes.html b/gitattributes.html index e01ee4c67..848f4fad8 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -2246,7 +2246,7 @@

GIT

diff --git a/gitcli.html b/gitcli.html index 0b4d92d3a..4ed8ec24f 100644 --- a/gitcli.html +++ b/gitcli.html @@ -1052,7 +1052,7 @@

GIT

diff --git a/gitcore-tutorial.html b/gitcore-tutorial.html index 1f2c8b2b8..8821f1d40 100644 --- a/gitcore-tutorial.html +++ b/gitcore-tutorial.html @@ -2458,7 +2458,7 @@

GIT

diff --git a/gitcredentials.html b/gitcredentials.html index b79e4c2be..a05dc5bc0 100644 --- a/gitcredentials.html +++ b/gitcredentials.html @@ -1122,7 +1122,7 @@

GIT

diff --git a/gitcvs-migration.html b/gitcvs-migration.html index a4dbd62d6..2018d1ab9 100644 --- a/gitcvs-migration.html +++ b/gitcvs-migration.html @@ -957,7 +957,7 @@

GIT

diff --git a/gitdiffcore.html b/gitdiffcore.html index 9e44a45bf..b29f33347 100644 --- a/gitdiffcore.html +++ b/gitdiffcore.html @@ -1108,7 +1108,7 @@

GIT

diff --git a/giteveryday.html b/giteveryday.html index 68388d9c7..4507ec4e6 100644 --- a/giteveryday.html +++ b/giteveryday.html @@ -1546,7 +1546,7 @@

GIT

diff --git a/gitfaq.html b/gitfaq.html index 70aba080d..3ca5875c2 100644 --- a/gitfaq.html +++ b/gitfaq.html @@ -1262,7 +1262,7 @@

GIT

diff --git a/gitformat-bundle.html b/gitformat-bundle.html index a962c88d9..10befb28f 100644 --- a/gitformat-bundle.html +++ b/gitformat-bundle.html @@ -879,7 +879,7 @@

GIT

diff --git a/gitformat-chunk.html b/gitformat-chunk.html index 2a08dad27..99740ceac 100644 --- a/gitformat-chunk.html +++ b/gitformat-chunk.html @@ -888,7 +888,7 @@

GIT

diff --git a/gitformat-commit-graph.html b/gitformat-commit-graph.html index 48084b510..feaa323ed 100644 --- a/gitformat-commit-graph.html +++ b/gitformat-commit-graph.html @@ -1076,7 +1076,7 @@

GIT

diff --git a/gitformat-index.html b/gitformat-index.html index 204dd3e81..940ea0cfe 100644 --- a/gitformat-index.html +++ b/gitformat-index.html @@ -1493,7 +1493,7 @@

GIT

diff --git a/gitformat-pack.html b/gitformat-pack.html index 3f3030951..0ec60b5ab 100644 --- a/gitformat-pack.html +++ b/gitformat-pack.html @@ -1553,7 +1553,7 @@

GIT

diff --git a/gitformat-signature.html b/gitformat-signature.html index 90266d404..da48c3b9e 100644 --- a/gitformat-signature.html +++ b/gitformat-signature.html @@ -1064,7 +1064,7 @@

GIT

diff --git a/gitglossary.html b/gitglossary.html index edda6d94a..39a2fdd3e 100644 --- a/gitglossary.html +++ b/gitglossary.html @@ -2001,7 +2001,7 @@

GIT

diff --git a/githooks.html b/githooks.html index 9ec0b2072..6d1777df2 100644 --- a/githooks.html +++ b/githooks.html @@ -1442,7 +1442,7 @@

GIT

diff --git a/gitignore.html b/gitignore.html index 4a72a80d3..4203adea7 100644 --- a/gitignore.html +++ b/gitignore.html @@ -1073,7 +1073,7 @@

GIT

diff --git a/gitk.html b/gitk.html index a2eabfc35..a60354d83 100644 --- a/gitk.html +++ b/gitk.html @@ -1101,7 +1101,7 @@

GIT

diff --git a/gitmailmap.html b/gitmailmap.html index 21e042161..0e095185a 100644 --- a/gitmailmap.html +++ b/gitmailmap.html @@ -892,7 +892,7 @@

GIT

diff --git a/gitmodules.html b/gitmodules.html index 4206b680c..a5fae00b2 100644 --- a/gitmodules.html +++ b/gitmodules.html @@ -948,7 +948,7 @@

GIT

diff --git a/gitnamespaces.html b/gitnamespaces.html index df10c2142..5f21d87da 100644 --- a/gitnamespaces.html +++ b/gitnamespaces.html @@ -850,7 +850,7 @@

GIT

diff --git a/gitprotocol-capabilities.html b/gitprotocol-capabilities.html index d28572d1b..3b4d5dec2 100644 --- a/gitprotocol-capabilities.html +++ b/gitprotocol-capabilities.html @@ -1154,7 +1154,7 @@

GIT

diff --git a/gitprotocol-common.html b/gitprotocol-common.html index 7ab286d15..90d5db18a 100644 --- a/gitprotocol-common.html +++ b/gitprotocol-common.html @@ -889,7 +889,7 @@

GIT

diff --git a/gitprotocol-http.html b/gitprotocol-http.html index bed497187..0285551f6 100644 --- a/gitprotocol-http.html +++ b/gitprotocol-http.html @@ -1279,7 +1279,7 @@

GIT

diff --git a/gitprotocol-pack.html b/gitprotocol-pack.html index 72ebc4172..dc70204f4 100644 --- a/gitprotocol-pack.html +++ b/gitprotocol-pack.html @@ -1494,7 +1494,7 @@

GIT

diff --git a/gitprotocol-v2.html b/gitprotocol-v2.html index 69d06f3d2..7080f39a2 100644 --- a/gitprotocol-v2.html +++ b/gitprotocol-v2.html @@ -1719,7 +1719,7 @@

GIT

diff --git a/gitremote-helpers.html b/gitremote-helpers.html index 5181b9d62..57b295833 100644 --- a/gitremote-helpers.html +++ b/gitremote-helpers.html @@ -1537,7 +1537,7 @@

GIT

diff --git a/gitrepository-layout.html b/gitrepository-layout.html index 17b40f6b2..1fe37233d 100644 --- a/gitrepository-layout.html +++ b/gitrepository-layout.html @@ -1372,7 +1372,7 @@

GIT

diff --git a/gitrevisions.html b/gitrevisions.html index cc63fe392..764b805a7 100644 --- a/gitrevisions.html +++ b/gitrevisions.html @@ -1417,7 +1417,7 @@

GIT

diff --git a/gitsubmodules.html b/gitsubmodules.html index 853f320bd..f125266d3 100644 --- a/gitsubmodules.html +++ b/gitsubmodules.html @@ -1113,7 +1113,7 @@

GIT

diff --git a/gittutorial-2.html b/gittutorial-2.html index 3f6717bad..4be9cc51e 100644 --- a/gittutorial-2.html +++ b/gittutorial-2.html @@ -1171,7 +1171,7 @@

GIT

diff --git a/gittutorial.html b/gittutorial.html index 3eadf0512..78b57f99a 100644 --- a/gittutorial.html +++ b/gittutorial.html @@ -1374,7 +1374,7 @@

GIT

diff --git a/gitweb.conf.html b/gitweb.conf.html index cb5bd4fba..9369a341b 100644 --- a/gitweb.conf.html +++ b/gitweb.conf.html @@ -2015,7 +2015,7 @@

GIT

diff --git a/gitweb.html b/gitweb.html index 044ac94f6..d9c01c75c 100644 --- a/gitweb.html +++ b/gitweb.html @@ -1642,7 +1642,7 @@

GIT

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

GIT

diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html index d573020c3..85f1a789d 100644 --- a/howto/coordinate-embargoed-releases.html +++ b/howto/coordinate-embargoed-releases.html @@ -1038,7 +1038,7 @@

Last updated - 2023-11-21 01:57:07 JST + 2023-12-09 17:41:26 PST

diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index e19d73455..ed65deed1 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html @@ -735,7 +735,7 @@
@@ -939,7 +939,7 @@

Keep authoritative canonical history correct with git pull

diff --git a/howto/maintain-git.html b/howto/maintain-git.html index ec35401f3..78775397a 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html @@ -735,7 +735,7 @@
@@ -1479,7 +1479,7 @@

Preparing a "merge-fix"

diff --git a/howto/new-command.html b/howto/new-command.html index 9bafae85b..84f8bbc27 100644 --- a/howto/new-command.html +++ b/howto/new-command.html @@ -735,7 +735,7 @@
@@ -864,7 +864,7 @@

Integrating a command

diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index 35c41f9c2..318e7d2ce 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html @@ -735,7 +735,7 @@
@@ -896,7 +896,7 @@

How to rebase from an internal branch

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index fc3ee9e24..b4ac28e4f 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html @@ -735,7 +735,7 @@
@@ -848,7 +848,7 @@

How to rebuild from update hook

diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index c3c0eed7b..4b0278004 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html @@ -735,7 +735,7 @@
@@ -881,7 +881,7 @@

How to recover a corrupted blob object

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index 6a38ae43e..286590845 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html @@ -735,7 +735,7 @@
@@ -1190,7 +1190,7 @@

The adventure continues…

diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 5e2e36ea6..3d5bc8abd 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html @@ -735,7 +735,7 @@
@@ -1026,7 +1026,7 @@

How to revert a faulty merge

diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index 62f7e16c1..b530fd2af 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html @@ -735,7 +735,7 @@
@@ -908,7 +908,7 @@

How to revert an existing commit

diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index 5e88f25a9..f6fd68cda 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html @@ -735,7 +735,7 @@
@@ -842,7 +842,7 @@

How to separate topic branches

diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index a29b67764..5c4cd343f 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html @@ -735,7 +735,7 @@
@@ -1072,7 +1072,7 @@

Troubleshooting:

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index 898b00560..a677b8772 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html @@ -735,7 +735,7 @@
@@ -931,7 +931,7 @@

How to use the update hook

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 33bfe6ca9..bc92e5638 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html @@ -735,7 +735,7 @@
@@ -792,7 +792,7 @@

How to use git-daemon

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index 1c0a90440..109815475 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html @@ -735,7 +735,7 @@
@@ -849,7 +849,7 @@

Additional tips

diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index 1fb56b951..b5743ec25 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html @@ -735,7 +735,7 @@
@@ -953,7 +953,7 @@

Auditors

diff --git a/scalar.html b/scalar.html index b39c140de..36729baf6 100644 --- a/scalar.html +++ b/scalar.html @@ -999,7 +999,7 @@

GIT

diff --git a/technical/api-error-handling.html b/technical/api-error-handling.html index 4a573f5ce..95f34ee7c 100644 --- a/technical/api-error-handling.html +++ b/technical/api-error-handling.html @@ -735,7 +735,7 @@
@@ -879,7 +879,7 @@

Caller-handled errors

diff --git a/technical/api-index.html b/technical/api-index.html index 1c1267c47..8ced06053 100644 --- a/technical/api-index.html +++ b/technical/api-index.html @@ -735,7 +735,7 @@
@@ -776,7 +776,7 @@

Git API Documents

diff --git a/technical/api-merge.html b/technical/api-merge.html index ed4d6e97e..eb1fc7628 100644 --- a/technical/api-merge.html +++ b/technical/api-merge.html @@ -735,7 +735,7 @@
@@ -802,7 +802,7 @@

Low-level (single file) merge

diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html index 9a6dd4386..c11b77419 100644 --- a/technical/api-parse-options.html +++ b/technical/api-parse-options.html @@ -735,7 +735,7 @@
@@ -1352,7 +1352,7 @@

Examples

diff --git a/technical/api-simple-ipc.html b/technical/api-simple-ipc.html index abbb70092..ffedaac8d 100644 --- a/technical/api-simple-ipc.html +++ b/technical/api-simple-ipc.html @@ -735,7 +735,7 @@
@@ -841,7 +841,7 @@

Summary

diff --git a/technical/api-trace2.html b/technical/api-trace2.html index 9b095205b..aa7511234 100644 --- a/technical/api-trace2.html +++ b/technical/api-trace2.html @@ -735,7 +735,7 @@
@@ -2355,7 +2355,7 @@

Relationship to t diff --git a/technical/bitmap-format.html b/technical/bitmap-format.html index d3a461857..56ef54fe7 100644 --- a/technical/bitmap-format.html +++ b/technical/bitmap-format.html @@ -735,7 +735,7 @@
@@ -1209,7 +1209,7 @@

Commit lookup table

diff --git a/technical/bundle-uri.html b/technical/bundle-uri.html index 796804290..db8d5f1cf 100644 --- a/technical/bundle-uri.html +++ b/technical/bundle-uri.html @@ -735,7 +735,7 @@
@@ -1464,7 +1464,7 @@

See Also

diff --git a/technical/hash-function-transition.html b/technical/hash-function-transition.html index 3246fe9d5..1c1541a23 100644 --- a/technical/hash-function-transition.html +++ b/technical/hash-function-transition.html @@ -735,7 +735,7 @@
@@ -2088,7 +2088,7 @@

Document History

diff --git a/technical/long-running-process-protocol.html b/technical/long-running-process-protocol.html index 7529f956b..dc77d3697 100644 --- a/technical/long-running-process-protocol.html +++ b/technical/long-running-process-protocol.html @@ -735,7 +735,7 @@
@@ -796,7 +796,7 @@

Shutdown

diff --git a/technical/multi-pack-index.html b/technical/multi-pack-index.html index 05b75b8a6..66e4c80e0 100644 --- a/technical/multi-pack-index.html +++ b/technical/multi-pack-index.html @@ -735,7 +735,7 @@
@@ -913,7 +913,7 @@

Related Links

diff --git a/technical/pack-heuristics.html b/technical/pack-heuristics.html index c1abfaba3..8a19c9602 100644 --- a/technical/pack-heuristics.html +++ b/technical/pack-heuristics.html @@ -735,7 +735,7 @@
@@ -1344,7 +1344,7 @@

Concerning Git’s Packing Heuristics

diff --git a/technical/parallel-checkout.html b/technical/parallel-checkout.html index 564e4fede..8c84be746 100644 --- a/technical/parallel-checkout.html +++ b/technical/parallel-checkout.html @@ -735,7 +735,7 @@
@@ -1076,7 +1076,7 @@

The API

diff --git a/technical/partial-clone.html b/technical/partial-clone.html index 22b779b62..39dc073bf 100644 --- a/technical/partial-clone.html +++ b/technical/partial-clone.html @@ -735,7 +735,7 @@
@@ -1214,7 +1214,7 @@

Related Links

diff --git a/technical/racy-git.html b/technical/racy-git.html index 88ffb00e5..ca4b7a00d 100644 --- a/technical/racy-git.html +++ b/technical/racy-git.html @@ -735,7 +735,7 @@
@@ -953,7 +953,7 @@

Avoiding runtime penalty

diff --git a/technical/reftable.html b/technical/reftable.html index 0b6e6315d..d226a686c 100644 --- a/technical/reftable.html +++ b/technical/reftable.html @@ -2056,7 +2056,7 @@

LMDB

diff --git a/technical/scalar.html b/technical/scalar.html index 8a4c6101b..0bd4bb2bf 100644 --- a/technical/scalar.html +++ b/technical/scalar.html @@ -735,7 +735,7 @@
@@ -834,7 +834,7 @@

Design

diff --git a/technical/send-pack-pipeline.html b/technical/send-pack-pipeline.html index 63b752807..d4bb0d611 100644 --- a/technical/send-pack-pipeline.html +++ b/technical/send-pack-pipeline.html @@ -735,7 +735,7 @@
@@ -828,7 +828,7 @@

Pack_objects pipeline

diff --git a/technical/shallow.html b/technical/shallow.html index 9de5814d9..7e79cf3ed 100644 --- a/technical/shallow.html +++ b/technical/shallow.html @@ -735,7 +735,7 @@
@@ -814,7 +814,7 @@

Shallow commits

diff --git a/technical/trivial-merge.html b/technical/trivial-merge.html index 402496a1a..657ca4470 100644 --- a/technical/trivial-merge.html +++ b/technical/trivial-merge.html @@ -735,7 +735,7 @@
@@ -857,7 +857,7 @@

Three-way merge

diff --git a/technical/unit-tests.html b/technical/unit-tests.html new file mode 100644 index 000000000..45a9cd45a --- /dev/null +++ b/technical/unit-tests.html @@ -0,0 +1,1216 @@ + + + + + + +Unit Testing + + + + + +
+
+
+

In our current testing environment, we spend a significant amount of effort +crafting end-to-end tests for error conditions that could easily be captured by +unit tests (or we simply forgo some hard-to-setup and rare error conditions). +Unit tests additionally provide stability to the codebase and can simplify +debugging through isolation. Writing unit tests in pure C, rather than with our +current shell/test-tool helper setup, simplifies test setup, simplifies passing +data around (no shell-isms required), and reduces testing runtime by not +spawning a separate process for every test invocation.

+

We believe that a large body of unit tests, living alongside the existing test +suite, will improve code quality for the Git project.

+
+
+
+

Definitions

+
+

For the purposes of this document, we’ll use test framework to refer to +projects that support writing test cases and running tests within the context +of a single executable. Test harness will refer to projects that manage +running multiple executables (each of which may contain multiple test cases) and +aggregating their results.

+

In reality, these terms are not strictly defined, and many of the projects +discussed below contain features from both categories.

+

For now, we will evaluate projects solely on their framework features. Since we +are relying on having TAP output (see below), we can assume that any framework +can be made to work with a harness that we can choose later.

+
+
+
+

Summary

+
+

We believe the best way forward is to implement a custom TAP framework for the +Git project. We use a version of the framework originally proposed in +1.

+

See the Framework Selection section below for the +rationale behind this decision.

+
+
+
+

Choosing a test harness

+
+

During upstream discussion, it was occasionally noted that prove provides many +convenient features, such as scheduling slower tests first, or re-running +previously failed tests.

+

While we already support the use of prove as a test harness for the shell +tests, it is not strictly required. The t/Makefile allows running shell tests +directly (though with interleaved output if parallelism is enabled). Git +developers who wish to use prove as a more advanced harness can do so by +setting DEFAULT_TEST_TARGET=prove in their config.mak.

+

We will follow a similar approach for unit tests: by default the test +executables will be run directly from the t/Makefile, but prove can be +configured with DEFAULT_UNIT_TEST_TARGET=prove.

+
+
+
+

Framework selection

+
+

There are a variety of features we can use to rank the candidate frameworks, and +those features have different priorities:

+
+
+

License

+

We must be able to legally use the framework in connection with Git. As Git is +licensed only under GPLv2, we must eliminate any LGPLv3, GPLv3, or Apache 2.0 +projects.

+
+
+

Vendorable or ubiquitous

+

We want to avoid forcing Git developers to install new tools just to run unit +tests. Any prospective frameworks and harnesses must either be vendorable +(meaning, we can copy their source directly into Git’s repository), or so +ubiquitous that it is reasonable to expect that most developers will have the +tools installed already.

+
+
+

Maintainable / extensible

+

It is unlikely that any pre-existing project perfectly fits our needs, so any +project we select will need to be actively maintained and open to accepting +changes. Alternatively, assuming we are vendoring the source into our repo, it +must be simple enough that Git developers can feel comfortable making changes as +needed to our version.

+

In the comparison table below, "True" means that the framework seems to have +active developers, that it is simple enough that Git developers can make changes +to it, and that the project seems open to accepting external contributions (or +that it is vendorable). "Partial" means that at least one of the above +conditions holds.

+
+
+

Major platform support

+

At a bare minimum, unit-testing must work on Linux, MacOS, and Windows.

+

In the comparison table below, "True" means that it works on all three major +platforms with no issues. "Partial" means that there may be annoyances on one or +more platforms, but it is still usable in principle.

+
+
+

TAP support

+

The Test Anything Protocol is a text-based interface +that allows tests to communicate with a test harness. It is already used by +Git’s integration test suite. Supporting TAP output is a mandatory feature for +any prospective test framework.

+

In the comparison table below, "True" means this is natively supported. +"Partial" means TAP output must be generated by post-processing the native +output.

+

Frameworks that do not have at least Partial support will not be evaluated +further.

+
+
+

Diagnostic output

+

When a test case fails, the framework must generate enough diagnostic output to +help developers find the appropriate test case in source code in order to debug +the failure.

+
+
+

Runtime-skippable tests

+

Test authors may wish to skip certain test cases based on runtime circumstances, +so the framework should support this.

+
+
+

Parallel execution

+

Ideally, we will build up a significant collection of unit test cases, most +likely split across multiple executables. It will be necessary to run these +tests in parallel to enable fast develop-test-debug cycles.

+

In the comparison table below, "True" means that individual test cases within a +single test executable can be run in parallel. We assume that executable-level +parallelism can be handled by the test harness.

+
+
+

Mock support

+

Unit test authors may wish to test code that interacts with objects that may be +inconvenient to handle in a test (e.g. interacting with a network service). +Mocking allows test authors to provide a fake implementation of these objects +for more convenient tests.

+
+
+

Signal & error handling

+

The test framework should fail gracefully when test cases are themselves buggy +or when they are interrupted by signals during runtime.

+
+
+

Project KLOC

+

The size of the project, in thousands of lines of code as measured by +sloccount (rounded up to the next multiple of +1,000). As a tie-breaker, we probably prefer a project with fewer LOC.

+
+
+

Adoption

+

As a tie-breaker, we prefer a more widely-used project. We use the number of +GitHub / GitLab stars to estimate this.

+
+
+

Comparison

+
+ ++++++++++++++++++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FrameworkLicenseVendorable or ubiquitousMaintainable / extensibleMajor platform supportTAP supportDiagnostic outputRuntime- skippable testsParallel executionMock supportSignal & error handlingProject KLOCAdoption

Custom Git impl.

GPL v2

True

True

True

True

True

True

False

False

False

1

0

Greatest

ISC

True

Partial

True

Partial

True

True

False

False

False

3

1400

Criterion

MIT

False

Partial

True

True

True

True

True

False

True

19

1800

C TAP

Expat

True

Partial

Partial

True

False

True

False

False

False

4

33

Check

LGPL v2.1

False

Partial

True

True

True

False

False

False

True

17

973

+
+
+
+

Additional framework candidates

+

Several suggested frameworks have been eliminated from consideration:

+
+
+
+
+
+

Milestones

+
+
    +
  • +

    +Add useful tests of library-like code +

    +
    • +
  • +

    +Integrate with + stdlib + work +

    +
    • +
  • +

    +Run alongside regular make test target +

    +
    • +
+
+
+
+
+ + + diff --git a/technical/unit-tests.txt b/technical/unit-tests.txt new file mode 100644 index 000000000..206037ffb --- /dev/null +++ b/technical/unit-tests.txt @@ -0,0 +1,240 @@ += Unit Testing + +In our current testing environment, we spend a significant amount of effort +crafting end-to-end tests for error conditions that could easily be captured by +unit tests (or we simply forgo some hard-to-setup and rare error conditions). +Unit tests additionally provide stability to the codebase and can simplify +debugging through isolation. Writing unit tests in pure C, rather than with our +current shell/test-tool helper setup, simplifies test setup, simplifies passing +data around (no shell-isms required), and reduces testing runtime by not +spawning a separate process for every test invocation. + +We believe that a large body of unit tests, living alongside the existing test +suite, will improve code quality for the Git project. + +== Definitions + +For the purposes of this document, we'll use *test framework* to refer to +projects that support writing test cases and running tests within the context +of a single executable. *Test harness* will refer to projects that manage +running multiple executables (each of which may contain multiple test cases) and +aggregating their results. + +In reality, these terms are not strictly defined, and many of the projects +discussed below contain features from both categories. + +For now, we will evaluate projects solely on their framework features. Since we +are relying on having TAP output (see below), we can assume that any framework +can be made to work with a harness that we can choose later. + + +== Summary + +We believe the best way forward is to implement a custom TAP framework for the +Git project. We use a version of the framework originally proposed in +https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[1]. + +See the <> section below for the +rationale behind this decision. + + +== Choosing a test harness + +During upstream discussion, it was occasionally noted that `prove` provides many +convenient features, such as scheduling slower tests first, or re-running +previously failed tests. + +While we already support the use of `prove` as a test harness for the shell +tests, it is not strictly required. The t/Makefile allows running shell tests +directly (though with interleaved output if parallelism is enabled). Git +developers who wish to use `prove` as a more advanced harness can do so by +setting DEFAULT_TEST_TARGET=prove in their config.mak. + +We will follow a similar approach for unit tests: by default the test +executables will be run directly from the t/Makefile, but `prove` can be +configured with DEFAULT_UNIT_TEST_TARGET=prove. + + +[[framework-selection]] +== Framework selection + +There are a variety of features we can use to rank the candidate frameworks, and +those features have different priorities: + +* Critical features: we probably won't consider a framework without these +** Can we legally / easily use the project? +*** <> +*** <> +*** <> +*** <> +** Does the project support our bare-minimum needs? +*** <> +*** <> +*** <> +* Nice-to-have features: +** <> +** <> +** <> +* Tie-breaker stats +** <> +** <> + +[[license]] +=== License + +We must be able to legally use the framework in connection with Git. As Git is +licensed only under GPLv2, we must eliminate any LGPLv3, GPLv3, or Apache 2.0 +projects. + +[[vendorable-or-ubiquitous]] +=== Vendorable or ubiquitous + +We want to avoid forcing Git developers to install new tools just to run unit +tests. Any prospective frameworks and harnesses must either be vendorable +(meaning, we can copy their source directly into Git's repository), or so +ubiquitous that it is reasonable to expect that most developers will have the +tools installed already. + +[[maintainable-extensible]] +=== Maintainable / extensible + +It is unlikely that any pre-existing project perfectly fits our needs, so any +project we select will need to be actively maintained and open to accepting +changes. Alternatively, assuming we are vendoring the source into our repo, it +must be simple enough that Git developers can feel comfortable making changes as +needed to our version. + +In the comparison table below, "True" means that the framework seems to have +active developers, that it is simple enough that Git developers can make changes +to it, and that the project seems open to accepting external contributions (or +that it is vendorable). "Partial" means that at least one of the above +conditions holds. + +[[major-platform-support]] +=== Major platform support + +At a bare minimum, unit-testing must work on Linux, MacOS, and Windows. + +In the comparison table below, "True" means that it works on all three major +platforms with no issues. "Partial" means that there may be annoyances on one or +more platforms, but it is still usable in principle. + +[[tap-support]] +=== TAP support + +The https://testanything.org/[Test Anything Protocol] is a text-based interface +that allows tests to communicate with a test harness. It is already used by +Git's integration test suite. Supporting TAP output is a mandatory feature for +any prospective test framework. + +In the comparison table below, "True" means this is natively supported. +"Partial" means TAP output must be generated by post-processing the native +output. + +Frameworks that do not have at least Partial support will not be evaluated +further. + +[[diagnostic-output]] +=== Diagnostic output + +When a test case fails, the framework must generate enough diagnostic output to +help developers find the appropriate test case in source code in order to debug +the failure. + +[[runtime-skippable-tests]] +=== Runtime-skippable tests + +Test authors may wish to skip certain test cases based on runtime circumstances, +so the framework should support this. + +[[parallel-execution]] +=== Parallel execution + +Ideally, we will build up a significant collection of unit test cases, most +likely split across multiple executables. It will be necessary to run these +tests in parallel to enable fast develop-test-debug cycles. + +In the comparison table below, "True" means that individual test cases within a +single test executable can be run in parallel. We assume that executable-level +parallelism can be handled by the test harness. + +[[mock-support]] +=== Mock support + +Unit test authors may wish to test code that interacts with objects that may be +inconvenient to handle in a test (e.g. interacting with a network service). +Mocking allows test authors to provide a fake implementation of these objects +for more convenient tests. + +[[signal-error-handling]] +=== Signal & error handling + +The test framework should fail gracefully when test cases are themselves buggy +or when they are interrupted by signals during runtime. + +[[project-kloc]] +=== Project KLOC + +The size of the project, in thousands of lines of code as measured by +https://dwheeler.com/sloccount/[sloccount] (rounded up to the next multiple of +1,000). As a tie-breaker, we probably prefer a project with fewer LOC. + +[[adoption]] +=== Adoption + +As a tie-breaker, we prefer a more widely-used project. We use the number of +GitHub / GitLab stars to estimate this. + + +=== Comparison + +:true: [lime-background]#True# +:false: [red-background]#False# +:partial: [yellow-background]#Partial# + +:gpl: [lime-background]#GPL v2# +:isc: [lime-background]#ISC# +:mit: [lime-background]#MIT# +:expat: [lime-background]#Expat# +:lgpl: [lime-background]#LGPL v2.1# + +:custom-impl: https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[Custom Git impl.] +:greatest: https://github.com/silentbicycle/greatest[Greatest] +:criterion: https://github.com/Snaipe/Criterion[Criterion] +:c-tap: https://github.com/rra/c-tap-harness/[C TAP] +:check: https://libcheck.github.io/check/[Check] + +[format="csv",options="header",width="33%",subs="specialcharacters,attributes,quotes,macros"] +|===== +Framework,"<>","<>","<>","<>","<>","<>","<>","<>","<>","<>","<>","<>" +{custom-impl},{gpl},{true},{true},{true},{true},{true},{true},{false},{false},{false},1,0 +{greatest},{isc},{true},{partial},{true},{partial},{true},{true},{false},{false},{false},3,1400 +{criterion},{mit},{false},{partial},{true},{true},{true},{true},{true},{false},{true},19,1800 +{c-tap},{expat},{true},{partial},{partial},{true},{false},{true},{false},{false},{false},4,33 +{check},{lgpl},{false},{partial},{true},{true},{true},{false},{false},{false},{true},17,973 +|===== + +=== Additional framework candidates + +Several suggested frameworks have been eliminated from consideration: + +* Incompatible licenses: +** https://github.com/zorgnax/libtap[libtap] (LGPL v3) +** https://cmocka.org/[cmocka] (Apache 2.0) +* Missing source: https://www.kindahl.net/mytap/doc/index.html[MyTap] +* No TAP support: +** https://nemequ.github.io/munit/[µnit] +** https://github.com/google/cmockery[cmockery] +** https://github.com/lpabon/cmockery2[cmockery2] +** https://github.com/ThrowTheSwitch/Unity[Unity] +** https://github.com/siu/minunit[minunit] +** https://cunit.sourceforge.net/[CUnit] + + +== Milestones + +* Add useful tests of library-like code +* Integrate with + https://lore.kernel.org/git/20230502211454.1673000-1-calvinwan@google.com/[stdlib + work] +* Run alongside regular `make test` target diff --git a/user-manual.html b/user-manual.html index 13915fd79..0050db0d5 100644 --- a/user-manual.html +++ b/user-manual.html @@ -1,5 +1,5 @@ -Git User Manual

Git User Manual

Revision History
2023-11-20

Table of Contents

Introduction
1. Repositories and Branches
How to get a Git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring Git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with Git
Telling Git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public Git repositories
Setting up a public repository
Exporting a Git repository via the Git protocol
Exporting a git repository via HTTP
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository
How to get a Git repository with minimal history
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git rebase
Rewriting a single commit
Reordering or selecting from a patch series
Using interactive rebases
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote-tracking branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How Git stores objects efficiently: pack files
Dangling objects
Recovering from repository corruption
The index
8. Submodules
Pitfalls with submodules
9. Low-level Git operations
Object access and manipulation
The Workflow
working directory → index
index → object database
object database → index
index → working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking Git
Object storage format
A birds-eye view of Git’s source code
11. Git Glossary
Git explained
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual
Todo list

Introduction

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX +Git User Manual

Git User Manual

Revision History
2023-12-09

Table of Contents

Introduction
1. Repositories and Branches
How to get a Git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring Git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with Git
Telling Git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public Git repositories
Setting up a public repository
Exporting a Git repository via the Git protocol
Exporting a git repository via HTTP
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository
How to get a Git repository with minimal history
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git rebase
Rewriting a single commit
Reordering or selecting from a patch series
Using interactive rebases
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote-tracking branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How Git stores objects efficiently: pack files
Dangling objects
Recovering from repository corruption
The index
8. Submodules
Pitfalls with submodules
9. Low-level Git operations
Object access and manipulation
The Workflow
working directory → index
index → object database
object database → index
index → working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking Git
Object storage format
A birds-eye view of Git’s source code
11. Git Glossary
Git explained
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual
Todo list

Introduction

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.

Chapter 1, Repositories and Branches and Chapter 2, Exploring Git history explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for