diff options
Diffstat (limited to 'Documentation')
59 files changed, 1791 insertions, 316 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c..bd6b6fcb93 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -24,10 +24,21 @@ MAN1_TXT += gitweb.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt +MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-chunk.txt +MAN5_TXT += gitformat-commit-graph.txt +MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-pack.txt +MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt +MAN5_TXT += gitprotocol-capabilities.txt +MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-http.txt +MAN5_TXT += gitprotocol-pack.txt +MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt MAN5_TXT += gitweb.conf.txt @@ -95,26 +106,17 @@ TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format -TECH_DOCS += technical/bundle-format -TECH_DOCS += technical/cruft-packs +TECH_DOCS += technical/bundle-uri TECH_DOCS += technical/hash-function-transition -TECH_DOCS += technical/http-protocol -TECH_DOCS += technical/index-format TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index -TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics -TECH_DOCS += technical/pack-protocol TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone -TECH_DOCS += technical/protocol-capabilities -TECH_DOCS += technical/protocol-common -TECH_DOCS += technical/protocol-v2 TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow -TECH_DOCS += technical/signature-format TECH_DOCS += technical/trivial-merge SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index @@ -290,6 +292,8 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ cmds-guide.txt \ + cmds-developerinterfaces.txt \ + cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt diff --git a/Documentation/RelNotes/2.37.2.txt b/Documentation/RelNotes/2.37.2.txt new file mode 100644 index 0000000000..d82b29e014 --- /dev/null +++ b/Documentation/RelNotes/2.37.2.txt @@ -0,0 +1,88 @@ +Git 2.37.2 Release Notes +======================== + +This primarily is to backport various fixes accumulated on the 'master' +front since 2.37.1. + +Fixes since v2.37.1 +------------------- + + * "git shortlog -n" relied on the underlying qsort() to be stable, + which shouldn't have. Fixed. + + * Variable quoting fix in the vimdiff driver of "git mergetool". + + * An earlier attempt to plug leaks placed a clean-up label to jump to + at a bogus place, which as been corrected. + + * Fixes a long-standing corner case bug around directory renames in + the merge-ort strategy. + + * Recent update to vimdiff layout code has been made more robust + against different end-user vim settings. + + * In a non-bare repository, the behavior of Git when the + core.worktree configuration variable points at a directory that has + a repository as its subdirectory, regressed in Git 2.27 days. + + * References to commands-to-be-typed-literally in "git rebase" + documentation mark-up have been corrected. + + * Give _() markings to fatal/warning/usage: labels that are shown in + front of these messages. + + * "git mktree --missing" lazily fetched objects that are missing from + the local object store, which was totally unnecessary for the purpose + of creating the tree object(s) from its input. + + * Fixes for tests when the source directory has unusual characters in + its path, e.g. whitespaces, double-quotes, etc. + + * Adjust technical/bitmap-format to be formatted by AsciiDoc, and + add some missing information to the documentation. + + * Certain diff options are currently ignored when combined-diff is + shown; mark them as incompatible with the feature. + + * "git clone" from a repository with some ref whose HEAD is unborn + did not set the HEAD in the resulting repository correctly, which + has been corrected. + + * mkstemp() emulation on Windows has been improved. + + * Add missing documentation for "include" and "includeIf" features in + "git config" file format, which incidentally teaches the command + line completion to include them in its offerings. + + * Avoid "white/black-list" in documentation and code comments. + + * Workaround for a compiler warning against use of die() in + osx-keychain (in contrib/). + + * Workaround for a false positive compiler warning. + + * The resolve-undo information in the index was not protected against + GC, which has been corrected. + + * A corner case bug where lazily fetching objects from a promisor + remote resulted in infinite recursion has been corrected. + + * "git p4" working on UTF-16 files on Windows did not implement + CRLF-to-LF conversion correctly, which has been corrected. + + * "git p4" did not handle non-ASCII client name well, which has been + corrected. + + * "rerere-train" script (in contrib/) used to honor commit.gpgSign + while recreating the throw-away merges. + + * "git checkout" miscounted the paths it updated, which has been + corrected. + + * Fix for a bug that makes write-tree to fail to write out a + non-existent index as a tree, introduced in 2.37. + + * There was a bug in the codepath to upgrade generation information + in commit-graph from v1 to v2 format, which has been corrected. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.37.3.txt b/Documentation/RelNotes/2.37.3.txt new file mode 100644 index 0000000000..d66689e598 --- /dev/null +++ b/Documentation/RelNotes/2.37.3.txt @@ -0,0 +1,46 @@ +Git 2.37.3 Release Notes +======================== + +This primarily is to backport various fixes accumulated on the 'master' +front since 2.37.2. + +Fixes since v2.37.2 +------------------- + + * The build procedure for Windows that uses CMake has been updated to + pick up the shell interpreter from local installation location. + + * Conditionally allow building Python interpreter on Windows + + * Fix to lstat() emulation on Windows. + + * Older gcc with -Wall complains about the universal zero initializer + "struct s = { 0 };" idiom, which makes developers' lives + inconvenient (as -Werror is enabled by DEVELOPER=YesPlease). The + build procedure has been tweaked to help these compilers. + + * Plug memory leaks in the failure code path in the "merge-ort" merge + strategy backend. + + * Avoid repeatedly running getconf to ask libc version in the test + suite, and instead just as it once per script. + + * Platform-specific code that determines if a directory is OK to use + as a repository has been taught to report more details, especially + on Windows. + + * "vimdiff3" regression has been corrected. + + * "git fsck" reads mode from tree objects but canonicalizes the mode + before passing it to the logic to check object sanity, which has + hid broken tree objects from the checking logic. This has been + corrected, but to help exiting projects with broken tree objects + that they cannot fix retroactively, the severity of anomalies this + code detects has been demoted to "info" for now. + + * Fixes to sparse index compatibility work for "reset" and "checkout" + commands. + + * Documentation for "git add --renormalize" has been improved. + +Also contains other minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.38.0.txt b/Documentation/RelNotes/2.38.0.txt index c394ec731e..91a822e62b 100644 --- a/Documentation/RelNotes/2.38.0.txt +++ b/Documentation/RelNotes/2.38.0.txt @@ -30,6 +30,48 @@ UI, Workflows & Features * Introduce a discovery.barerepository configuration variable that allows users to forbid discovery of bare repositories. + * Various messages that come from the pack-bitmap codepaths have been + tweaked. + + * "git rebase -i" learns to update branches whose tip appear in the + rebased range with "--update-refs" option. + + * "git ls-files" learns the "--format" option to tweak its output. + + * "git cat-file" learned an option to use the mailmap when showing + commit and tag objects. + + * When "git merge" finds that it cannot perform a merge, it should + restore the working tree to the state before the command was + initiated, but in some corner cases it didn't. + + * Operating modes like "--batch" of "git cat-file" command learned to + take NUL-terminated input, instead of one-item-per-line. + + * "git rm" has become more aware of the sparse-index feature. + + * "git rev-list --disk-usage" learned to take an optional value + "human" to show the reported value in human-readable format, like + "3.40MiB". + + * The "diagnose" feature to create a zip archive for diagnostic + material has been lifted from "scalar" and made into a feature of + "git bugreport". + + * The namespaces used by "log --decorate" from "refs/" hierarchy by + default has been tightened. + + * "git rev-list --ancestry-path=C A..B" is a natural extension of + "git rev-list A..B"; instead of choosing a subset of A..B to those + that have ancestry relationship with A, it lets a subset with + ancestry relationship with C. + + * "scalar" now enables built-in fsmonitor on enlisted repositories, + when able. + + * The bash prompt (in contrib/) learned to optionally indicate when + the index is unmerged. + Performance, Internal Implementation, Development Support etc. @@ -75,6 +117,28 @@ Performance, Internal Implementation, Development Support etc. * A coccinelle rule (in contrib/) to encourage use of COPY_ARRAY macro has been improved. + * API tweak to make it easier to run fuzz testing on commit-graph parser. + + * Omit fsync-related trace2 entries when their values are all zero. + + * The codepath to write multi-pack index has been taught to release a + large chunk of memory that holds an array of objects in the packs, + as soon as it is done with the array, to reduce memory consumption. + + * Add a level of redirection to array allocation API in xdiff part, + to make it easier to share with the libgit2 project. + + * "git fetch" client logs the partial clone filter used in the trace2 + output. + + * The "bundle URI" design gets documented. + + * The common ancestor negotiation exchange during a "git fetch" + session now leaves trace log. + + * Test portability improvements. + (merge 4d1d843be7 mt/rot13-in-c later to maint). + Fixes since v2.37 ----------------- @@ -84,85 +148,153 @@ Fixes since v2.37 * Certain diff options are currently ignored when combined-diff is shown; mark them as incompatible with the feature. - (merge cfb19ae05f rs/combine-diff-with-incompatible-options later to maint). * Adjust technical/bitmap-format to be formatted by AsciiDoc, and add some missing information to the documentation. - (merge ac7667bd44 ac/bitmap-format-doc later to maint). * Fixes for tests when the source directory has unusual characters in its path, e.g. whitespaces, double-quotes, etc. - (merge eb1cd60290 ab/test-quoting-fix later to maint). * "git mktree --missing" lazily fetched objects that are missing from the local object store, which was totally unnecessary for the purpose of creating the tree object(s) from its input. - (merge 817b0f6027 ro/mktree-allow-missing-fix later to maint). * Give _() markings to fatal/warning/usage: labels that are shown in front of these messages. - (merge a1fd2cf8cd dr/i18n-die-warn-error-usage later to maint). * References to commands-to-be-typed-literally in "git rebase" documentation mark-up have been corrected. - (merge 54e51e559e ds/git-rebase-doc-markup later to maint). * In a non-bare repository, the behavior of Git when the core.worktree configuration variable points at a directory that has a repository as its subdirectory, regressed in Git 2.27 days. - (merge d6c9a71755 gg/worktree-from-the-above later to maint). * Recent update to vimdiff layout code has been made more robust against different end-user vim settings. - (merge f3d7623a13 fr/vimdiff-layout-fix later to maint). - - * Plug various memory leaks. - (merge ece3974ba6 ab/leakfix later to maint). - * Plug various memory leaks in test-tool commands. - (merge f40a693450 ab/test-tool-leakfix later to maint). + * Plug various memory leaks, both in the main code and in test-tool + commands. * Fixes a long-standing corner case bug around directory renames in the merge-ort strategy. - (merge 751e165424 en/merge-dual-dir-renames-fix later to maint). * The resolve-undo information in the index was not protected against GC, which has been corrected. - (merge e0ad13977a jc/resolve-undo later to maint). * A corner case bug where lazily fetching objects from a promisor remote resulted in infinite recursion has been corrected. - (merge cb88b37cb9 hx/lookup-commit-in-graph-fix later to maint). * "git clone" from a repository with some ref whose HEAD is unborn did not set the HEAD in the resulting repository correctly, which has been corrected. - (merge daf7898abb jk/clone-unborn-confusion later to maint). * An earlier attempt to plug leaks placed a clean-up label to jump to at a bogus place, which as been corrected. - (merge 04393ae7f7 jk/diff-files-cleanup-fix later to maint). * Variable quoting fix in the vimdiff driver of "git mergetool" - (merge ccc7b5148b js/vimdiff-quotepath-fix later to maint). * "git shortlog -n" relied on the underlying qsort() to be stable, which shouldn't have. Fixed. - (merge df534dcbaa js/shortlog-sort-stably later to maint). * A fix for a regression in test framework. - (merge 7253f7ca9f js/ci-github-workflow-markup later to maint). * mkstemp() emulation on Windows has been improved. - (merge ae25974de3 rs/mingw-tighten-mkstemp later to maint). + + * Add missing documentation for "include" and "includeIf" features in + "git config" file format, which incidentally teaches the command + line completion to include them in its offerings. + + * Avoid "white/black-list" in documentation and code comments. + + * Workaround for a compiler warning against use of die() in + osx-keychain (in contrib/). + + * Workaround for a false positive compiler warning. + + * "git p4" working on UTF-16 files on Windows did not implement + CRLF-to-LF conversion correctly, which has been corrected. + + * "git p4" did not handle non-ASCII client name well, which has been + corrected. + + * "rerere-train" script (in contrib/) used to honor commit.gpgSign + while recreating the throw-away merges. + + * "git checkout" miscounted the paths it updated, which has been + corrected. + + * Fix for a bug that makes write-tree to fail to write out a + non-existent index as a tree, introduced in 2.37. + + * There was a bug in the codepath to upgrade generation information + in commit-graph from v1 to v2 format, which has been corrected. + + * Gitweb had legacy URL shortener that is specific to the way + projects hosted on kernel.org used to (but no longer) work, which + has been removed. + + * Fix build procedure for Windows that uses CMake so that it can pick + up the shell interpreter from local installation location. + + * Conditionally allow building Python interpreter on Windows + + * Fix to lstat() emulation on Windows. + + * Older gcc with -Wall complains about the universal zero initializer + "struct s = { 0 };" idiom, which makes developers' lives + inconvenient (as -Werror is enabled by DEVELOPER=YesPlease). The + build procedure has been tweaked to help these compilers. + + * Plug memory leaks in the failure code path in the "merge-ort" merge + strategy backend. + + * "git symbolic-ref symref non..sen..se" is now diagnosed as an error. + + * A follow-up fix to a fix for a regression in 2.36 around hooks. + + * Avoid repeatedly running getconf to ask libc version in the test + suite, and instead just as it once per script. + + * Platform-specific code that determines if a directory is OK to use + as a repository has been taught to report more details, especially + on Windows. + + * "vimdiff3" regression fix. + + * "git fsck" reads mode from tree objects but canonicalizes the mode + before passing it to the logic to check object sanity, which has + hid broken tree objects from the checking logic. This has been + corrected, but to help exiting projects with broken tree objects + that they cannot fix retroactively, the severity of anomalies this + code detects has been demoted to "info" for now. + + * Fixes to sparse index compatibility work for "reset" and "checkout" + commands. + + * An earlier optimization discarded a tree-object buffer that is + still in use, which has been corrected. + (merge 1490d7d82d jk/is-promisor-object-keep-tree-in-use later to maint). + + * Fix deadlocks between main Git process and subprocess spawned via + the pipe_command() API, that can kill "git add -p" that was + reimplemented in C recently. + (merge 716c1f649e jk/pipe-command-nonblock later to maint). + + * The sequencer machinery translated messages left in the reflog by + mistake, which has been corrected. + + * xcalloc(), imitating calloc(), takes "number of elements of the + array", and "size of a single element", in this order. A call that + does not follow this ordering has been corrected. + (merge c4bbd9bb8f sg/xcalloc-cocci-fix later to maint). + + * The preload-index codepath made copies of pathspec to give to + multiple threads, which were left leaked. + (merge 23578904da ad/preload-plug-memleak later to maint). + + * Update the version of Ubuntu used for GitHub Actions CI from 18.04 + to 22.04. + (merge ef46584831 ds/github-actions-use-newer-ubuntu later to maint). * Other code cleanup, docfix, build fix, etc. - (merge 5fd9d1738e jk/revisions-doc-markup-fix later to maint). - (merge 1971510c35 pb/diff-doc-raw-format later to maint). - (merge a3ba4fa715 cr/setup-bug-typo later to maint). - (merge 85845580d9 ds/vscode-settings later to maint). - (merge ec2f6c0cca en/t6429-test-must-be-empty-fix later to maint). - (merge 14deb585fb tb/pack-objects-remove-pahole-comment later to maint). - (merge 2ffb7d13ee ds/t5510-brokequote later to maint). - (merge 18337d406f ll/ls-files-tests-update later to maint). - (merge 8cdab69d96 tk/rev-parse-doc-clarify-at-u later to maint). + (merge 77b9e85c0f vd/fix-perf-tests later to maint).
\ No newline at end of file diff --git a/Documentation/config.txt b/Documentation/config.txt index e376d547ce..5b5b976569 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -445,6 +445,8 @@ include::config/i18n.txt[] include::config/imap.txt[] +include::config/includeif.txt[] + include::config/index.txt[] include::config/init.txt[] diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 3ea3124f7f..37afbaf5a4 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -722,8 +722,8 @@ core.sparseCheckout:: core.sparseCheckoutCone:: Enables the "cone mode" of the sparse checkout feature. When the sparse-checkout file contains a limited set of patterns, this - mode provides significant performance advantages. The "non - cone mode" can be requested to allow specifying a more flexible + mode provides significant performance advantages. The "non-cone + mode" can be requested to allow specifying more flexible patterns by setting this variable to 'false'. See linkgit:git-sparse-checkout[1] for more information. diff --git a/Documentation/config/includeif.txt b/Documentation/config/includeif.txt new file mode 100644 index 0000000000..82fe431c34 --- /dev/null +++ b/Documentation/config/includeif.txt @@ -0,0 +1,6 @@ +include.path:: +includeIf.<condition>.path:: + Special variables to include other configuration files. See + the "CONFIGURATION FILE" section in the main + linkgit:git-config[1] documentation, + specifically the "Includes" and "Conditional Includes" subsections. diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt index 456eb07800..5250ba45fb 100644 --- a/Documentation/config/log.txt +++ b/Documentation/config/log.txt @@ -18,6 +18,11 @@ log.decorate:: names are shown. This is the same as the `--decorate` option of the `git log`. +log.initialDecorationSet:: + By default, `git log` only shows decorations for certain known ref + namespaces. If 'all' is specified, then show all refs as + decorations. + log.excludeDecoration:: Exclude the specified patterns from the log decorations. This is similar to the `--decorate-refs-exclude` command-line option, but diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.txt index adeda0f24d..3d88fb0bad 100644 --- a/Documentation/config/lsrefs.txt +++ b/Documentation/config/lsrefs.txt @@ -1,7 +1,7 @@ lsrefs.unborn:: May be "advertise" (the default), "allow", or "ignore". If "advertise", the server will respond to the client sending "unborn" (as described in - protocol-v2.txt) and will advertise support for this feature during the + linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the protocol v2 capability advertisement. "allow" is the same as "advertise" except that the server will not advertise support for this feature; this is useful for load-balanced servers that cannot be diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index ad7f73a1ea..3e581eab84 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap. pack.writeReverseIndex:: When true, git will write a corresponding .rev file (see: - link:../technical/pack-format.html[Documentation/technical/pack-format.txt]) + linkgit:gitformat-pack[5]) for each new packfile that it writes in all places except for linkgit:git-fast-import[1] and in the bulk checkin mechanism. Defaults to false. diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index 756591d77b..5760381851 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -58,6 +58,6 @@ protocol.version:: * `1` - the original wire protocol with the addition of a version string in the initial response from the server. -* `2` - link:technical/protocol-v2.html[wire protocol version 2]. +* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5]. -- diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index 8c979cb20f..f19bd0e040 100644 --- a/Documentation/config/rebase.txt +++ b/Documentation/config/rebase.txt @@ -21,6 +21,9 @@ rebase.autoStash:: `--autostash` options of linkgit:git-rebase[1]. Defaults to false. +rebase.updateRefs:: + If set to true enable `--update-refs` option by default. + rebase.missingCommitsCheck:: If set to "warn", git rebase -i will print a warning if some commits are removed (e.g. a line was deleted), however the diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 11eb70f16c..9b37f35654 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -188,7 +188,9 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. forcibly add them again to the index. This is useful after changing `core.autocrlf` configuration or the `text` attribute in order to correct files added with wrong CRLF/LF line endings. - This option implies `-u`. + This option implies `-u`. Lone CR characters are untouched, thus + while a CRLF cleans to LF, a CRCRLF sequence is only partially + cleaned to CRLF. --chmod=(+|-)x:: Override the executable bit of the added files. The executable diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 09107fb106..320da6c4f7 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -112,10 +112,7 @@ default. You can use `--no-utf8` to override this. am.threeWay configuration variable. For more information, see am.threeWay in linkgit:git-config[1]. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] --ignore-space-change:: --ignore-whitespace:: diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt index d8817bf3ce..eca726e579 100644 --- a/Documentation/git-bugreport.txt +++ b/Documentation/git-bugreport.txt @@ -9,6 +9,7 @@ SYNOPSIS -------- [verse] 'git bugreport' [(-o | --output-directory) <path>] [(-s | --suffix) <format>] + [--diagnose[=<mode>]] DESCRIPTION ----------- @@ -31,6 +32,10 @@ The following information is captured automatically: - A list of enabled hooks - $SHELL +Additional information may be gathered into a separate zip archive using the +`--diagnose` option, and can be attached alongside the bugreport document to +provide additional context to readers. + This tool is invoked via the typical Git setup process, which means that in some cases, it might not be able to launch - for example, if a relevant config file is unreadable. In this kind of scenario, it may be helpful to manually gather @@ -49,6 +54,19 @@ OPTIONS named 'git-bugreport-<formatted suffix>'. This should take the form of a strftime(3) format string; the current local time will be used. +--no-diagnose:: +--diagnose[=<mode>]:: + Create a zip archive of supplemental information about the user's + machine, Git client, and repository state. The archive is written to the + same output directory as the bug report and is named + 'git-diagnostics-<formatted suffix>'. ++ +Without `mode` specified, the diagnostic archive will contain the default set of +statistics reported by `git diagnose`. An optional `mode` value may be specified +to change which information is included in the archive. See +linkgit:git-diagnose[1] for the list of valid values for `mode` and details +about their usage. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 7685b57045..6da6172243 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -56,10 +56,8 @@ using "thin packs", bundles created using exclusions are smaller in size. That they're "thin" under the hood is merely noted here as a curiosity, and as a reference to other documentation. -See link:technical/bundle-format.html[the `bundle-format` -documentation] for more details and the discussion of "thin pack" in -link:technical/pack-format.html[the pack format documentation] for -further details. +See linkgit:gitformat-bundle[5] for more details and the discussion of +"thin pack" in linkgit:gitformat-pack[5] for further details. OPTIONS ------- @@ -77,7 +75,7 @@ verify <file>:: commits exist and are fully linked in the current repository. Then, 'git bundle' prints a list of missing commits, if any. Finally, information about additional capabilities, such as "object - filter", is printed. See "Capabilities" in link:technical/bundle-format.html + filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5] for more information. The exit code is zero for success, but will be nonzero if the bundle file is invalid. @@ -337,6 +335,11 @@ You can also see what references it offers: $ git ls-remote mybundle ---------------- +FILE FORMAT +----------- + +See linkgit:gitformat-bundle[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 24a811f0ef..ec30b5c574 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -14,7 +14,7 @@ SYNOPSIS 'git cat-file' (-t | -s) [--allow-unknown-type] <object> 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] [--buffer] [--follow-symlinks] [--unordered] - [--textconv | --filters] + [--textconv | --filters] [-z] 'git cat-file' (--textconv | --filters) [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] @@ -63,6 +63,12 @@ OPTIONS or to ask for a "blob" with `<object>` being a tag object that points at it. +--[no-]mailmap:: +--[no-]use-mailmap:: + Use mailmap file to map author, committer and tagger names + and email addresses to canonical real names and email addresses. + See linkgit:git-shortlog[1]. + --textconv:: Show the content as transformed by a textconv filter. In this case, `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>` in @@ -207,6 +213,11 @@ respectively print: /etc/passwd -- +-z:: + Only meaningful with `--batch`, `--batch-check`, or + `--batch-command`; input is NUL-delimited instead of + newline-delimited. + OUTPUT ------ diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 78dcc9171f..1e8ac9df60 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -156,10 +156,7 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] SEQUENCER SUBCOMMANDS --------------------- diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 632bd1348e..d032d971dd 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -323,6 +323,13 @@ or `--mirror` is given) for `host.xz:foo/.git`). Cloning into an existing directory is only allowed if the directory is empty. +--bundle-uri=<uri>:: + Before fetching from the remote, fetch a bundle from the given + `<uri>` and unbundle the data into the local repository. The refs + in the bundle will be stored under the hidden `refs/bundle/*` + namespace. This option is incompatible with `--depth`, + `--shallow-since`, and `--shallow-exclude`. + :git-clone: 1 include::urls.txt[] diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index e1f48c95b3..047decdb65 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append ------------------------------------------------ +FILE FORMAT +----------- + +see linkgit:gitformat-commit-graph[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 4dc57ed254..53f111bc0a 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -63,11 +63,10 @@ Print version information and exit Print usage information and exit <directory>:: -You can specify a list of allowed directories. If no directories -are given, all are allowed. This is an additional restriction, gitcvs -access still needs to be enabled by the `gitcvs.enabled` config option -unless `--export-all` was given, too. - +The remaining arguments provide a list of directories. If no directories +are given, then all are allowed. Repositories within these directories +still require the `gitcvs.enabled` config option, unless `--export-all` +is specified. LIMITATIONS ----------- @@ -311,11 +310,13 @@ ENVIRONMENT These variables obviate the need for command-line options in some circumstances, allowing easier restricted usage through git-shell. -GIT_CVSSERVER_BASE_PATH takes the place of the argument to --base-path. +GIT_CVSSERVER_BASE_PATH:: + This variable replaces the argument to --base-path. -GIT_CVSSERVER_ROOT specifies a single-directory whitelist. The -repository must still be configured to allow access through -git-cvsserver, as described above. +GIT_CVSSERVER_ROOT:: + This variable specifies a single directory, replacing the + `<directory>...` argument list. The repository still requires the + `gitcvs.enabled` config option, unless `--export-all` is specified. When these environment variables are set, the corresponding command-line arguments may not be used. diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index fdc28c041c..236df516c7 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -32,8 +32,8 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, you can further restrict -the offers to a whitelist comprising of those. +pass some directory paths as 'git daemon' arguments, the offers are limited to +repositories within those directories. By default, only `upload-pack` service is enabled, which serves 'git fetch-pack' and 'git ls-remote' clients, which are invoked @@ -50,7 +50,7 @@ OPTIONS Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. 'git daemon' will refuse to start when this option is enabled and no - whitelist is specified. + directory arguments are provided. --base-path=<path>:: Remap all the path requests as relative to the given path. @@ -73,7 +73,7 @@ OPTIONS %IP for the server's IP address, %P for the port number, and %D for the absolute path of the named repository. After interpolation, the path is validated against the directory - whitelist. + list. --export-all:: Allow pulling from all directories that look like Git repositories @@ -218,9 +218,11 @@ standard output to be sent to the requestor as an error message when it declines the service. <directory>:: - A directory to add to the whitelist of allowed directories. Unless - --strict-paths is specified this will also include subdirectories - of each named directory. + The remaining arguments provide a list of directories. If any + directories are specified, then the `git-daemon` process will + serve a requested directory only if it is contained in one of + these directories. If `--strict-paths` is specified, then the + requested directory must match one of these directories exactly. SERVICES -------- @@ -264,9 +266,8 @@ git 9418/tcp # Git Version Control System 'git daemon' as inetd server:: To set up 'git daemon' as an inetd service that handles any - repository under the whitelisted set of directories, /pub/foo - and /pub/bar, place an entry like the following into - /etc/inetd all on one line: + repository within `/pub/foo` or `/pub/bar`, place an entry like + the following into `/etc/inetd` all on one line: + ------------------------------------------------ git stream tcp nowait nobody /usr/bin/git diff --git a/Documentation/git-diagnose.txt b/Documentation/git-diagnose.txt new file mode 100644 index 0000000000..3ec8cc7ad7 --- /dev/null +++ b/Documentation/git-diagnose.txt @@ -0,0 +1,65 @@ +git-diagnose(1) +================ + +NAME +---- +git-diagnose - Generate a zip archive of diagnostic information + +SYNOPSIS +-------- +[verse] +'git diagnose' [(-o | --output-directory) <path>] [(-s | --suffix) <format>] + [--mode=<mode>] + +DESCRIPTION +----------- +Collects detailed information about the user's machine, Git client, and +repository state and packages that information into a zip archive. The +generated archive can then, for example, be shared with the Git mailing list to +help debug an issue or serve as a reference for independent debugging. + +By default, the following information is captured in the archive: + + * 'git version --build-options' + * The path to the repository root + * The available disk space on the filesystem + * The name and size of each packfile, including those in alternate object + stores + * The total count of loose objects, as well as counts broken down by + `.git/objects` subdirectory + +Additional information can be collected by selecting a different diagnostic mode +using the `--mode` option. + +This tool differs from linkgit:git-bugreport[1] in that it collects much more +detailed information with a greater focus on reporting the size and data shape +of repository contents. + +OPTIONS +------- +-o <path>:: +--output-directory <path>:: + Place the resulting diagnostics archive in `<path>` instead of the + current directory. + +-s <format>:: +--suffix <format>:: + Specify an alternate suffix for the diagnostics archive name, to create + a file named 'git-diagnostics-<formatted suffix>'. This should take the + form of a strftime(3) format string; the current local time will be + used. + +--mode=(stats|all):: + Specify the type of diagnostics that should be collected. The default behavior + of 'git diagnose' is equivalent to `--mode=stats`. ++ +The `--mode=all` option collects everything included in `--mode=stats`, as well +as copies of `.git`, `.git/hooks`, `.git/info`, `.git/logs`, and +`.git/objects/info` directories. This additional information may be sensitive, +as it can be used to reconstruct the full contents of the diagnosed repository. +Users should exercise caution when sharing an archive generated with +`--mode=all`. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 239c68db45..2b0b5e390d 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,16 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] -'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>] 'git help' [-g|--guides] 'git help' [-c|--config] +'git help' [--user-interfaces] +'git help' [--developer-interfaces] DESCRIPTION ----------- -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git' +With no options and no '<command>' or '<doc>' given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. @@ -26,8 +28,8 @@ printed on the standard output. If the option `--guides` or `-g` is given, a list of the Git concept guides is also printed on the standard output. -If a command, or a guide, is given, a manual page for that command or -guide is brought up. The 'man' program is used by default for this +If a command or other documentation is given, the relevant manual page +will be brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. @@ -69,6 +71,23 @@ OPTIONS --guides:: Prints a list of the Git concept guides on the standard output. +--user-interfaces:: + Prints a list of the repository, command and file interfaces + documentation on the standard output. ++ +In-repository file interfaces such as `.git/info/exclude` are +documented here (see linkgit:gitrepository-layout[5]), as well as +in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]). ++ +This section of the documentation also covers general or widespread +user-interface conventions (e.g. linkgit:gitcli[7]), and +pseudo-configuration such as the file-based `.git/hooks/*` interface +described in linkgit:githooks[5]. + +--developer-interfaces:: + Print list of file formats, protocols and other developer + interfaces documentation on the standard output. + -i:: --info:: Display manual page for the command in the 'info' format. The diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 20e87cecf4..b1285aee3c 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -45,13 +45,23 @@ OPTIONS --decorate-refs=<pattern>:: --decorate-refs-exclude=<pattern>:: - If no `--decorate-refs` is given, pretend as if all refs were - included. For each candidate, do not use it for decoration if it + For each candidate reference, do not use it for decoration if it matches any patterns given to `--decorate-refs-exclude` or if it doesn't match any of the patterns given to `--decorate-refs`. The `log.excludeDecoration` config option allows excluding refs from the decorations, but an explicit `--decorate-refs` pattern will override a match in `log.excludeDecoration`. ++ +If none of these options or config settings are given, then references are +used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, +`refs/stash/`, or `refs/tags/`. + +--clear-decorations:: + When specified, this option clears all previous `--decorate-refs` + or `--decorate-refs-exclude` options and relaxes the default + decoration filter to include all references. This option is + assumed if the config value `log.initialDecorationSet` is set to + `all`. --source:: Print out the ref name given on the command line by which each diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 0dabf3f0dd..d7986419c2 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -20,7 +20,7 @@ SYNOPSIS [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--recurse-submodules] - [--abbrev[=<n>]] [--] [<file>...] + [--abbrev[=<n>]] [--format=<format>] [--] [<file>...] DESCRIPTION ----------- @@ -192,6 +192,13 @@ followed by the ("attr/<eolattr>"). to the contained files. Sparse directories will be shown with a trailing slash, such as "x/" for a sparse directory "x". +--format=<format>:: + A string that interpolates `%(fieldname)` from the result being shown. + 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). + --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo` + and `--eol`. \--:: Do not interpret any more arguments as options. @@ -223,6 +230,36 @@ quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). Using `-z` the filename is output verbatim and the line is terminated by a NUL byte. +It is possible to print in a custom format by using the `--format` +option, which is able to interpolate different fields using +a `%(fieldname)` notation. For example, if you only care about the +"objectname" and "path" fields, you can execute with a specific +"--format" like + + git ls-files --format='%(objectname) %(path)' + +FIELD NAMES +----------- +The way each path is shown can be customized by using the +`--format=<format>` option, where the %(fieldname) in the +<format> string for various aspects of the index entry are +interpolated. The following "fieldname" are understood: + +objectmode:: + The mode of the file which is recorded in the index. +objectname:: + The name of the file which is recorded in the index. +stage:: + The stage of the file which is recorded in the index. +eolinfo:index:: +eolinfo:worktree:: + The <eolinfo> (see the description of the `--eol` option) of + the contents in the index or in the worktree for the path. +eolattr:: + The <eolattr> (see the description of the `--eol` option) + that applies to the path. +path:: + The pathname of the file which is recorded in the index. EXCLUDE PATTERNS ---------------- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3125473cc1..fee1dc2df2 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -90,10 +90,7 @@ invocations. The automated message can include the branch description. If `--log` is specified, a shortlog of the commits being merged will be appended to the specified message. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] --overwrite-ignore:: --no-overwrite-ignore:: diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index c588fb91af..a48c3d5ea6 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -128,8 +128,8 @@ $ git multi-pack-index verify SEE ALSO -------- See link:technical/multi-pack-index.html[The Multi-Pack-Index Design -Document] and link:technical/pack-format.html[The Multi-Pack-Index -Format] for more information on the multi-pack-index feature. +Document] and linkgit:gitformat-pack[5] for more information on the +multi-pack-index feature and its file format. GIT diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index a872ab0fbd..1877942180 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -376,10 +376,7 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -612,6 +609,15 @@ provided. Otherwise an explicit `--no-reschedule-failed-exec` at the start would be overridden by the presence of `rebase.rescheduleFailedExec=true` configuration. +--update-refs:: +--no-update-refs:: + Automatically force-update any branches that point to commits that + are being rebased. Any branches that are checked out in a worktree + are not updated in this way. ++ +If the configuration variable `rebase.updateRefs` is set, then this option +can be used to override and disable this setting. + INCOMPATIBLE OPTIONS -------------------- @@ -635,6 +641,7 @@ are incompatible with the following options: * --empty= * --reapply-cherry-picks * --edit-todo + * --update-refs * --root when used in combination with --onto In addition, the following pairs of options are incompatible: diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 5ced7ad4f8..db9d46edfa 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -22,7 +22,7 @@ depending on the subcommand: [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... + [--dry-run | -n] [--verbose] <ref>@{<specifier>}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 8463fe9cf7..0105a54c1a 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -112,10 +112,7 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. +include::rerere-options.txt[] --reference:: Instead of starting the body of the log message with "This diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 8f87b23ea8..3f89d64077 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -39,10 +39,9 @@ OPTIONS --http-backend-info-refs:: Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See - "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in - link:technical/protocol-v2.html[the Git Wire Protocol, Version - 2] documentation. Also understood by + "Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP + Transport" in in the linkgit:gitprotocol-v2[5] + documentation. Also understood by linkgit:git-receive-pack[1]. <directory>:: diff --git a/Documentation/git.txt b/Documentation/git.txt index 302607a496..0ef7f5e4ec 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -339,6 +339,23 @@ The following documentation pages are guides about Git concepts. include::cmds-guide.txt[] +Repository, command and file interfaces +--------------------------------------- + +This documentation discusses repository and command interfaces which +users are expected to interact with directly. See `--user-formats` in +linkgit:git-help[1] for more details on the critera. + +include::cmds-userinterfaces.txt[] + +File formats, protocols and other developer interfaces +------------------------------------------------------ + +This documentation discusses file formats, over-the-wire protocols and +other git developer interfaces. See `--developer-interfaces` in +linkgit:git-help[1]. + +include::cmds-developerinterfaces.txt[] Configuration Mechanism ----------------------- @@ -885,9 +902,7 @@ for full details. If set to a colon-separated list of protocols, behave as if `protocol.allow` is set to `never`, and each of the listed protocols has `protocol.<name>.allow` set to `always` - (overriding any existing configuration). In other words, any - protocol not mentioned will be disallowed (i.e., this is a - whitelist, not a blacklist). See the description of + (overriding any existing configuration). See the description of `protocol.allow` in linkgit:git-config[1] for more details. `GIT_PROTOCOL_FROM_USER`:: diff --git a/Documentation/technical/bundle-format.txt b/Documentation/gitformat-bundle.txt index b9be8644cf..00e0a20e65 100644 --- a/Documentation/technical/bundle-format.txt +++ b/Documentation/gitformat-bundle.txt @@ -1,11 +1,33 @@ -= Git bundle v2 format +gitformat-bundle(5) +=================== -The Git bundle format is a format that represents both refs and Git objects. +NAME +---- +gitformat-bundle - The bundle file format + + +SYNOPSIS +-------- +[verse] +*.bundle +*.bdl + +DESCRIPTION +----------- + +The Git bundle format is a format that represents both refs and Git +objects. A bundle is a header in a format similar to +linkgit:git-show-ref[1] followed by a pack in *.pack format. -== Format +The format is created and read by the linkgit:git-bundle[1] command, +and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1]. + + +FORMAT +------ We will use ABNF notation to define the Git bundle format. See -protocol-common.txt for the details. +linkgit:gitprotocol-common[5] for the details. A v2 bundle looks like this: @@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF) pack = ... ; packfile ---- -== Semantics + +SEMANTICS +--------- A Git bundle consists of several parts. @@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id. This is a comment and it has no specific meaning. The writer of the bundle MAY put any string here. The reader of the bundle MUST ignore the comment. -=== Note on the shallow clone and a Git bundle +Note on the shallow clone and a Git bundle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that the prerequisites does not represent a shallow-clone boundary. The semantics of the prerequisites and the shallow-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository. -== Capabilities +CAPABILITIES +------------ Because there is no opportunity for negotiation, unknown capabilities cause 'git bundle' to abort. @@ -79,3 +105,7 @@ bundle' to abort. * `filter` specifies an object filter as in the `--filter` option in linkgit:git-rev-list[1]. The resulting pack-file must be marked as a `.promisor` pack-file after it is unbundled. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt index 593614fced..57202ede27 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/gitformat-chunk.txt @@ -1,12 +1,25 @@ -Chunk-based file formats -======================== +gitformat-chunk(5) +================== + +NAME +---- +gitformat-chunk - Chunk-based file formats + +SYNOPSIS +-------- + +Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see +the pack format documentation in linkgit:gitformat-pack[5]). + +DESCRIPTION +----------- Some file formats in Git use a common concept of "chunks" to describe sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the `commit-graph` and `multi-pack-index` files. See -link:technical/pack-format.html[the `multi-pack-index` format] and -link:technical/commit-graph-format.html[the `commit-graph` format] for +the `multi-pack-index` format in linkgit:gitformat-pack[5] and +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for how they use the chunks to describe structured data. A chunk-based file format begins with some header information custom to @@ -108,9 +121,13 @@ for future formats: * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()` in `commit-graph.c` for how the chunk-format API is used to write and parse the commit-graph file format documented in - link:technical/commit-graph-format.html[the commit-graph file format]. + the commit-graph file format in linkgit:gitformat-commit-graph[5]. * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` in `midx.c` for how the chunk-format API is used to write and parse the multi-pack-index file format documented in - link:technical/pack-format.html[the multi-pack-index file format]. + the multi-pack-index file format section of linkgit:gitformat-pack[5]. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt index 484b185ba9..7324665716 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -1,5 +1,18 @@ -Git commit graph format -======================= +gitformat-commit-graph(5) +========================= + +NAME +---- +gitformat-commit-graph - Git commit graph format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/info/commit-graph +$GIT_DIR/objects/info/commit-graphs/* + +DESCRIPTION +----------- The Git commit graph stores a list of commit OIDs and some associated metadata, including: @@ -30,7 +43,7 @@ and hash type. All multi-byte numbers are in network byte order. -HEADER: +=== HEADER: 4-byte signature: The signature is: {'C', 'G', 'P', 'H'} @@ -52,7 +65,7 @@ HEADER: We infer the length (H*B) of the Base Graphs chunk from this value. -CHUNK LOOKUP: +=== CHUNK LOOKUP: (C + 1) * 12 bytes listing the table of contents for the chunks: First 4 bytes describe the chunk id. Value 0 is a terminating label. @@ -62,23 +75,23 @@ CHUNK LOOKUP: ID appears at most once. The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5] The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless otherwise specified. -CHUNK DATA: +=== CHUNK DATA: - OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) The ith entry, F[i], stores the number of OIDs with first byte at most i. Thus F[255] stores the total number of commits (N). - OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) +==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) The OIDs for all commits in the graph, sorted in ascending order. - Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) +==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) * The first H bytes are for the OID of the root tree. * The next 8 bytes are for the positions of the first two parents of the ith commit. Stores value 0x70000000 if no parent in that @@ -93,7 +106,7 @@ CHUNK DATA: 2 bits of the lowest byte, storing the 33rd and 34th bit of the commit time. - Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] * This list of 4-byte values store corrected commit date offsets for the commits, arranged in the same order as commit data chunk. * If the corrected commit date offset cannot be stored within 31 bits, @@ -104,7 +117,7 @@ CHUNK DATA: by compatible versions of Git and in case of split commit-graph chains, the topmost layer also has Generation Data chunk. - Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] * This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits. @@ -112,7 +125,7 @@ CHUNK DATA: chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits. - Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit @@ -120,14 +133,14 @@ CHUNK DATA: positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent. - Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters from commit 0 to commit i (inclusive) in lexicographic order. The Bloom filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header length), where BIDX[-1] is 0. * The BIDX chunk is ignored if the BDAT chunk is not present. - Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] * It starts with header consisting of three unsigned 32-bit integers: - Version of the hash algorithm being used. We currently only support value 1 which corresponds to the 32-bit version of the murmur3 hash @@ -147,13 +160,13 @@ CHUNK DATA: of length one, with either all bits set to zero or one respectively. * The BDAT chunk is present if and only if BIDX is present. - Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] This list of H-byte hashes describe a set of B commit-graph files that form a commit-graph chain. The graph position for the ith commit in this file's OID Lookup chunk is equal to i plus the number of commits in all base graphs. If B is non-zero, this chunk must exist. -TRAILER: +=== TRAILER: H-byte HASH-checksum of all of the above. @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By changing the IDs, newer versions of Git will silently ignore those older chunks and write the new information without trusting the incorrect data. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt index 65da0daaa5..015cb21bdc 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/gitformat-index.txt @@ -1,5 +1,19 @@ +gitformat-index(5) +================== + +NAME +---- +gitformat-index - Git index format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/index + +DESCRIPTION +----------- + Git index format -================ == The Git index file has the following format @@ -26,8 +40,6 @@ Git index format Extensions are identified by signature. Optional extensions can be ignored if Git does not understand them. - Git currently supports cache tree and resolve undo extensions. - 4-byte extension signature. If the first byte is 'A'..'Z' the extension is optional and can be ignored. @@ -127,7 +139,7 @@ Git index format entry is encoded as if the path name for the previous entry is an empty string). At the beginning of an entry, an integer N in the variable width encoding (the same encoding as the offset is encoded - for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed by a NUL-terminated string S. Removing N bytes from the end of the path name for the previous entry, and replacing it with the string S yields the path name for this entry. @@ -404,3 +416,7 @@ The remaining data of each directory block is grouped by type: with signature { 's', 'd', 'i', 'r' }. Like the split-index extension, tools should avoid interacting with a sparse index unless they understand this extension. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/pack-format.txt b/Documentation/gitformat-pack.txt index b520aa9c45..e06af02f21 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/gitformat-pack.txt @@ -1,5 +1,30 @@ -Git pack format -=============== +gitformat-pack(5) +================= + +NAME +---- +gitformat-pack - Git pack format + + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/pack/pack-*.{pack,idx} +$GIT_DIR/objects/pack/pack-*.rev +$GIT_DIR/objects/pack/pack-*.mtimes +$GIT_DIR/objects/pack/multi-pack-index + +DESCRIPTION +----------- + +The Git pack format is now Git stores most of its primary repository +data. Over the lietime af a repository loose objects (if any) and +smaller packs are consolidated into larger pack(s). See +linkgit:git-gc[1] and linkgit:git-pack-objects[1]. + +The pack format is also used over-the-wire, see +e.g. linkgit:gitprotocol-v2[5], as well as being a part of +other container formats in the case of linkgit:gitformat-bundle[5]. == Checksums and object IDs @@ -356,7 +381,7 @@ CHUNK LOOKUP: using the next chunk position if necessary.) The CHUNK LOOKUP matches the table of contents from - link:technical/chunk-format.html[the chunk-based file format]. + the chunk-based file format, see linkgit:gitformat-chunk[5]. The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless @@ -482,3 +507,132 @@ packs arranged in MIDX order (with the preferred pack coming first). The MIDX's reverse index is stored in the optional 'RIDX' chunk within the MIDX itself. + +== cruft packs + +The cruft packs feature offer an alternative to Git's traditional mechanism of +removing unreachable objects. This document provides an overview of Git's +pruning mechanism, and how a cruft pack can be used instead to accomplish the +same. + +=== Background + +To remove unreachable objects from your repository, Git offers `git repack -Ad` +(see linkgit:git-repack[1]). Quoting from the documentation: + +---- +[...] unreachable objects in a previous pack become loose, unpacked objects, +instead of being left in the old pack. [...] loose unreachable objects will be +pruned according to normal expiry rules with the next 'git gc' invocation. +---- + +Unreachable objects aren't removed immediately, since doing so could race with +an incoming push which may reference an object which is about to be deleted. +Instead, those unreachable objects are stored as loose objects and stay that way +until they are older than the expiration window, at which point they are removed +by linkgit:git-prune[1]. + +Git must store these unreachable objects loose in order to keep track of their +per-object mtimes. If these unreachable objects were written into one big pack, +then either freshening that pack (because an object contained within it was +re-written) or creating a new pack of unreachable objects would cause the pack's +mtime to get updated, and the objects within it would never leave the expiration +window. Instead, objects are stored loose in order to keep track of the +individual object mtimes and avoid a situation where all cruft objects are +freshened at once. + +This can lead to undesirable situations when a repository contains many +unreachable objects which have not yet left the grace period. Having large +directories in the shards of `.git/objects` can lead to decreased performance in +the repository. But given enough unreachable objects, this can lead to inode +starvation and degrade the performance of the whole system. Since we +can never pack those objects, these repositories often take up a large amount of +disk space, since we can only zlib compress them, but not store them in delta +chains. + +=== Cruft packs + +A cruft pack eliminates the need for storing unreachable objects in a loose +state by including the per-object mtimes in a separate file alongside a single +pack containing all loose objects. + +A cruft pack is written by `git repack --cruft` when generating a new pack. +linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft` +is a classic all-into-one repack, meaning that everything in the resulting pack is +reachable, and everything else is unreachable. Once written, the `--cruft` +option instructs `git repack` to generate another pack containing only objects +not packed in the previous step (which equates to packing all unreachable +objects together). This progresses as follows: + + 1. Enumerate every object, marking any object which is (a) not contained in a + kept-pack, and (b) whose mtime is within the grace period as a traversal + tip. + + 2. Perform a reachability traversal based on the tips gathered in the previous + step, adding every object along the way to the pack. + + 3. Write the pack out, along with a `.mtimes` file that records the per-object + timestamps. + +This mode is invoked internally by linkgit:git-repack[1] when instructed to +write a cruft pack. Crucially, the set of in-core kept packs is exactly the set +of packs which will not be deleted by the repack; in other words, they contain +all of the repository's reachable objects. + +When a repository already has a cruft pack, `git repack --cruft` typically only +adds objects to it. An exception to this is when `git repack` is given the +`--cruft-expiration` option, which allows the generated cruft pack to omit +expired objects instead of waiting for linkgit:git-gc[1] to expire those objects +later on. + +It is linkgit:git-gc[1] that is typically responsible for removing expired +unreachable objects. + +=== Caution for mixed-version environments + +Repositories that have cruft packs in them will continue to work with any older +version of Git. Note, however, that previous versions of Git which do not +understand the `.mtimes` file will use the cruft pack's mtime as the mtime for +all of the objects in it. In other words, do not expect older (pre-cruft pack) +versions of Git to interpret or even read the contents of the `.mtimes` file. + +Note that having mixed versions of Git GC-ing the same repository can lead to +unreachable objects never being completely pruned. This can happen under the +following circumstances: + + - An older version of Git running GC explodes the contents of an existing + cruft pack loose, using the cruft pack's mtime. + - A newer version running GC collects those loose objects into a cruft pack, + where the .mtime file reflects the loose object's actual mtimes, but the + cruft pack mtime is "now". + +Repeating this process will lead to unreachable objects not getting pruned as a +result of repeatedly resetting the objects' mtimes to the present time. + +If you are GC-ing repositories in a mixed version environment, consider omitting +the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and +leaving the `gc.cruftPacks` configuration unset until all writers understand +cruft packs. + +=== Alternatives + +Notable alternatives to this design include: + + - The location of the per-object mtime data, and + - Storing unreachable objects in multiple cruft packs. + +On the location of mtime data, a new auxiliary file tied to the pack was chosen +to avoid complicating the `.idx` format. If the `.idx` format were ever to gain +support for optional chunks of data, it may make sense to consolidate the +`.mtimes` format into the `.idx` itself. + +Storing unreachable objects among multiple cruft packs (e.g., creating a new +cruft pack during each repacking operation including only unreachable objects +which aren't already stored in an earlier cruft pack) is significantly more +complicated to construct, and so aren't pursued here. The obvious drawback to +the current implementation is that the entire cruft pack must be re-written from +scratch. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt index 166721be6f..a249869faf 100644 --- a/Documentation/technical/signature-format.txt +++ b/Documentation/gitformat-signature.txt @@ -1,7 +1,18 @@ -Git signature format -==================== +gitformat-signature(5) +====================== -== Overview +NAME +---- +gitformat-signature - Git cryptographic signature formats + +SYNOPSIS +-------- +[verse] +<[tag|commit] object header(s)> +<over-the-wire protocol> + +DESCRIPTION +----------- Git uses cryptographic signatures in various places, currently objects (tags, commits, mergetags) and transactions (pushes). In every case, the command which @@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000 # gpg: There is no indication that the signature belongs to the owner. # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt index 9dfade930d..c6dcc7d565 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -1,8 +1,20 @@ -Git Protocol Capabilities -========================= +gitprotocol-capabilities(5) +=========================== + +NAME +---- +gitprotocol-capabilities - Protocol v0 and v1 capabilities + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- NOTE: this document describes capabilities for versions 0 and 1 of the pack -protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2] +protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5] doc. Servers SHOULD support all capabilities defined in this document. @@ -77,7 +89,7 @@ interleaved with S-R-Q. multi_ack_detailed ------------------ This is an extension of multi_ack that permits client to better -understand the server's in-memory state. See pack-protocol.txt, +understand the server's in-memory state. See linkgit:gitprotocol-pack[5], section "Packfile Negotiation" for more information. no-done @@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server will respond with whether the packfile unpacked successfully and if each reference was updated successfully. If any of those were not -successful, it will send back an error message. See pack-protocol.txt +successful, it will send back an error message. See linkgit:gitprotocol-pack[5] for example messages. report-status-v2 @@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by the "proc-receive" hook. The "proc-receive" hook may handle a command for a pseudo-reference which may create or update a reference with different name, new-oid, and old-oid. While the capability -'report-status' cannot report for such case. See pack-protocol.txt +'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5] for details. delete-refs @@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see link:api-trace2.html[api-trace2] for details), but this may change and users of the session ID should not rely on this fact. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-common.txt b/Documentation/gitprotocol-common.txt index ecedb34bba..1486651bd1 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/gitprotocol-common.txt @@ -1,5 +1,20 @@ -Documentation Common to Pack and Http Protocols -=============================================== +gitprotocol-common(5) +===================== + +NAME +---- +gitprotocol-common - Things common to various protocols + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- + +This document sets defines things common to various over-the-wire +protocols and file formats used in Git. ABNF Notation ------------- @@ -97,3 +112,7 @@ Examples (as C-style strings): "000bfoobar\n" "foobar\n" "0004" "" ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/http-protocol.txt b/Documentation/gitprotocol-http.txt index cc5126cfed..ccc13f0a40 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/gitprotocol-http.txt @@ -1,5 +1,19 @@ -HTTP transfer protocols -======================= +gitprotocol-http(5) +=================== + +NAME +---- +gitprotocol-http - Git HTTP-based protocols + + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + + +DESCRIPTION +----------- Git supports two HTTP based transfer protocols. A "dumb" protocol which requires only a standard HTTP server on the server end of the @@ -222,7 +236,7 @@ smart server reply: S: 0000 The client may send Extra Parameters (see -Documentation/technical/pack-protocol.txt) as a colon-separated string +linkgit:gitprotocol-pack[5]) as a colon-separated string in the Git-Protocol HTTP header. Uses the `--http-backend-info-refs` option to @@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id. TODO: Document this further. - -References +REFERENCES ---------- http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] -link:technical/pack-protocol.html -link:technical/protocol-capabilities.html + +SEE ALSO +-------- + +linkgit:gitprotocol-pack[5] +linkgit:gitprotocol-capabilities[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/gitprotocol-pack.txt index e13a2c064d..dd4108b7a3 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/gitprotocol-pack.txt @@ -1,11 +1,23 @@ -Packfile transfer protocols -=========================== +gitprotocol-pack(5) +=================== + +NAME +---- +gitprotocol-pack - How packs are transferred over-the-wire + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same -protocol to transfer data. http is documented in http-protocol.txt. +protocol to transfer data. http is documented in linkgit:gitprotocol-http[5]. The processes invoked in the canonical Git implementation are 'upload-pack' on the server side and 'fetch-pack' on the client side for fetching data; @@ -18,7 +30,7 @@ pkt-line Format --------------- The descriptions below build on the pkt-line format described in -protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless +linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless otherwise noted the usual pkt-line LF rules apply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not present. @@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is -"version" with a value of '1' or '2'. See protocol-v2.txt for more +"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more information on protocol version 2. Git Transport @@ -455,7 +467,7 @@ Now that the client and server have finished negotiation about what the minimal amount of data that needs to be sent to the client is, the server will construct and send the required data in packfile format. -See pack-format.txt for what the packfile itself actually looks like. +See linkgit:gitformat-pack[5] for what the packfile itself actually looks like. If 'side-band' or 'side-band-64k' capabilities have been specified by the client, the server will send the packfile data multiplexed. @@ -707,3 +719,7 @@ An example client/server communication might look like this: S: 0018ok refs/heads/debug\n S: 002ang refs/heads/master non-fast-forward\n ---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/gitprotocol-v2.txt index 8a877d27e2..c9c0f9160b 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -1,5 +1,17 @@ -Git Wire Protocol, Version 2 -============================ +gitprotocol-v2(5) +================= + +NAME +---- +gitprotocol-v2 - Git Wire Protocol, Version 2 + +SYNOPSIS +-------- +[verse] +<over-the-wire-protocol> + +DESCRIPTION +----------- This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways: @@ -26,8 +38,7 @@ Packet-Line Framing ------------------- All communication is done using packet-line framing, just as in v1. See -`Documentation/technical/pack-protocol.txt` and -`Documentation/technical/protocol-common.txt` for more information. +linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information. In protocol v2 these special packets will have the following semantics: @@ -42,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in `pack-protocol.txt` and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -66,7 +77,7 @@ HTTP Transport ~~~~~~~~~~~~~~ When using the http:// or https:// transport a client makes a "smart" -info/refs request as described in `http-protocol.txt` and requests that +info/refs request as described in linkgit:gitprotocol-http[5] and requests that v2 be used by supplying "version=2" in the `Git-Protocol` header. C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 @@ -566,3 +577,7 @@ and associated requested information, each separated by a single space. attr = "size" obj-info = obj-id SP obj-size + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 6f1e269ae4..ed8da428c9 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -168,6 +168,9 @@ Supported commands: 'list', 'import'. Can guarantee that when a clone is requested, the received pack is self contained and is connected. +'get':: + Can use the 'get' command to download a file from a given URI. + If a helper advertises 'connect', Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the 'connect' command under COMMANDS). @@ -418,6 +421,12 @@ Supported if the helper has the "connect" capability. + Supported if the helper has the "stateless-connect" capability. +'get' <uri> <path>:: + Downloads the file from the given `<uri>` to the given `<path>`. If + `<path>.temp` exists, then Git assumes that the `.temp` file is a + partial download from a previous attempt and will resume the + download from that position. + If a fatal error occurs, the program writes the error message to stderr and exits. The caller should expect that a suitable error message has been printed if the child closes the connection without diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt index 8994e2559e..5efb4fe81f 100644 --- a/Documentation/howto/recover-corrupted-object-harder.txt +++ b/Documentation/howto/recover-corrupted-object-harder.txt @@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it has the git packed object header, which is variable-length. We want to strip that off so we can start playing with the zlib data directly. You can either work your way through it manually (the format is described in -link:../technical/pack-format.html[Documentation/technical/pack-format.txt]), +linkgit:gitformat-pack[5]), or you can walk through it in a debugger. I did the latter, creating a valid pack like: diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl index 425377dfeb..02408a0062 100755 --- a/Documentation/lint-man-section-order.perl +++ b/Documentation/lint-man-section-order.perl @@ -32,6 +32,9 @@ my %SECTIONS; 'SEE ALSO' => { order => $order++, }, + 'FILE FORMAT' => { + order => $order++, + }, 'GIT' => { required => 1, order => $order++, diff --git a/Documentation/rerere-options.txt b/Documentation/rerere-options.txt new file mode 100644 index 0000000000..c3321ddea2 --- /dev/null +++ b/Documentation/rerere-options.txt @@ -0,0 +1,9 @@ +--rerere-autoupdate:: +--no-rerere-autoupdate:: + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. `--no-rerere-autoupdate` is a good way to + double-check what `rerere` did and catch potential + mismerges, before committing the result to the index with a + separate `git add`. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 195e74eec6..1837509566 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -242,6 +242,7 @@ ifdef::git-rev-list[] to `/dev/null` as the output does not have to be formatted. --disk-usage:: +--disk-usage=human:: Suppress normal output; instead, print the sum of the bytes used for on-disk storage by the selected commits or objects. This is equivalent to piping the output into `git cat-file @@ -249,6 +250,8 @@ ifdef::git-rev-list[] faster (especially with `--use-bitmap-index`). See the `CAVEATS` section in linkgit:git-cat-file[1] for the limitations of what "on-disk storage" means. + With the optional value `human`, on-disk storage size is shown + in human-readable string(e.g. 12.24 Kib, 3.50 Mib). endif::git-rev-list[] --cherry-mark:: @@ -389,12 +392,14 @@ Default mode:: merges from the resulting history, as there are no selected commits contributing to this merge. ---ancestry-path:: +--ancestry-path[=<commit>]:: When given a range of commits to display (e.g. 'commit1..commit2' - or 'commit2 {caret}commit1'), only display commits that exist - directly on the ancestry chain between the 'commit1' and - 'commit2', i.e. commits that are both descendants of 'commit1', - and ancestors of 'commit2'. + or 'commit2 {caret}commit1'), only display commits in that range + that are ancestors of <commit>, descendants of <commit>, or + <commit> itself. If no commit is specified, use 'commit1' (the + excluded part of the range) as <commit>. Can be passed multiple + times; if so, a commit is included if it is any of the commits + given or if it is an ancestor or descendant of one of them. A more detailed explanation follows. @@ -568,11 +573,10 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`: There is another simplification mode available: ---ancestry-path:: - Limit the displayed commits to those directly on the ancestry - chain between the ``from'' and ``to'' commits in the given commit - range. I.e. only display commits that are ancestor of the ``to'' - commit and descendants of the ``from'' commit. +--ancestry-path[=<commit>]:: + Limit the displayed commits to those which are an ancestor of + <commit>, or which are a descendant of <commit>, or are <commit> + itself. + As an example use case, consider the following commit history: + @@ -604,6 +608,29 @@ option does. Applied to the 'D..M' range, it results in: \ L--M ----------------------------------------------------------------------- ++ +We can also use `--ancestry-path=D` instead of `--ancestry-path` which +means the same thing when applied to the 'D..M' range but is just more +explicit. ++ +If we instead are interested in a given topic within this range, and all +commits affected by that topic, we may only want to view the subset of +`D..M` which contain that topic in their ancestry path. So, using +`--ancestry-path=H D..M` for example would result in: ++ +----------------------------------------------------------------------- + E + \ + G---H---I---J + \ + L--M +----------------------------------------------------------------------- ++ +Whereas `--ancestry-path=K D..M` would result in ++ +----------------------------------------------------------------------- + K---------------L--M +----------------------------------------------------------------------- Before discussing another option, `--show-pulls`, we need to create a new example history. @@ -659,7 +686,7 @@ Here, the merge commits `O` and `P` contribute extra noise, as they did not actually contribute a change to `file.txt`. They only merged a topic that was based on an older version of `file.txt`. This is a common issue in repositories using a workflow where many contributors work in -parallel and merge their topic branches along a single trunk: manu +parallel and merge their topic branches along a single trunk: many unrelated merges appear in the `--full-history` results. When using the `--simplify-merges` option, the commits `O` and `P` diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt index d79ad323e6..d44ada98e7 100644 --- a/Documentation/technical/api-simple-ipc.txt +++ b/Documentation/technical/api-simple-ipc.txt @@ -78,7 +78,7 @@ client and an optional response message from the server. Both the client and server messages are unlimited in length and are terminated with a flush packet. -The pkt-line routines (Documentation/technical/protocol-common.txt) +The pkt-line routines (linkgit:gitprotocol-common[5]) are used to simplify buffer management during message generation, transmission, and reception. A flush packet is used to mark the end of the message. This allows the sender to incrementally generate and diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 77a150b30e..2afa28bb5a 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -717,6 +717,7 @@ The "exec_id" field is a command-unique id and is only useful if the { "event":"def_param", ... + "scope":"global", "param":"core.abbrev", "value":"7" } @@ -1207,6 +1208,45 @@ at offset 508. This example also shows that thread names are assigned in a racy manner as each thread starts and allocates TLS storage. +Config (def param) Events:: + + Dump "interesting" config values to trace2 log. ++ +We can optionally emit configuration events, see +`trace2.configparams` in linkgit:git-config[1] for how to enable +it. ++ +---------------- +$ git config --system color.ui never +$ git config --global color.ui always +$ git config --local color.ui auto +$ git config --list --show-scope | grep 'color.ui' +system color.ui=never +global color.ui=always +local color.ui=auto +---------------- ++ +Then, mark the config `color.ui` as "interesting" config with +`GIT_TRACE2_CONFIG_PARAMS`: ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ export GIT_TRACE2_CONFIG_PARAMS=color.ui +$ git version +... +$ cat ~/log.perf +d0 | main | version | | | | | ... +d0 | main | start | | 0.001642 | | | /usr/local/bin/git version +d0 | main | cmd_name | | | | | version (version) +d0 | main | def_param | | | | scope:system | color.ui:never +d0 | main | def_param | | | | scope:global | color.ui:always +d0 | main | def_param | | | | scope:local | color.ui:auto +d0 | main | data | r0 | 0.002100 | 0.002100 | fsync | fsync/writeout-only:0 +d0 | main | data | r0 | 0.002126 | 0.002126 | fsync | fsync/hardware-flush:0 +d0 | main | exit | | 0.000470 | | | code:0 +d0 | main | atexit | | 0.000477 | | | code:0 +---------------- == Future Work === Relationship to the Existing Trace Api (api-trace.txt) diff --git a/Documentation/technical/bundle-uri.txt b/Documentation/technical/bundle-uri.txt new file mode 100644 index 0000000000..c25c42378a --- /dev/null +++ b/Documentation/technical/bundle-uri.txt @@ -0,0 +1,573 @@ +Bundle URIs +=========== + +Git bundles are files that store a pack-file along with some extra metadata, +including a set of refs and a (possibly empty) set of necessary commits. See +linkgit:git-bundle[1] and link:bundle-format.txt[the bundle format] for more +information. + +Bundle URIs are locations where Git can download one or more bundles in +order to bootstrap the object database in advance of fetching the remaining +objects from a remote. + +One goal is to speed up clones and fetches for users with poor network +connectivity to the origin server. Another benefit is to allow heavy users, +such as CI build farms, to use local resources for the majority of Git data +and thereby reducing the load on the origin server. + +To enable the bundle URI feature, users can specify a bundle URI using +command-line options or the origin server can advertise one or more URIs +via a protocol v2 capability. + +Design Goals +------------ + +The bundle URI standard aims to be flexible enough to satisfy multiple +workloads. The bundle provider and the Git client have several choices in +how they create and consume bundle URIs. + +* Bundles can have whatever name the server desires. This name could refer + to immutable data by using a hash of the bundle contents. However, this + means that a new URI will be needed after every update of the content. + This might be acceptable if the server is advertising the URI (and the + server is aware of new bundles being generated) but would not be + ergonomic for users using the command line option. + +* The bundles could be organized specifically for bootstrapping full + clones, but could also be organized with the intention of bootstrapping + incremental fetches. The bundle provider must decide on one of several + organization schemes to minimize client downloads during incremental + fetches, but the Git client can also choose whether to use bundles for + either of these operations. + +* The bundle provider can choose to support full clones, partial clones, + or both. The client can detect which bundles are appropriate for the + repository's partial clone filter, if any. + +* The bundle provider can use a single bundle (for clones only), or a + list of bundles. When using a list of bundles, the provider can specify + whether or not the client needs _all_ of the bundle URIs for a full + clone, or if _any_ one of the bundle URIs is sufficient. This allows the + bundle provider to use different URIs for different geographies. + +* The bundle provider can organize the bundles using heuristics, such as + creation tokens, to help the client prevent downloading bundles it does + not need. When the bundle provider does not provide these heuristics, + the client can use optimizations to minimize how much of the data is + downloaded. + +* The bundle provider does not need to be associated with the Git server. + The client can choose to use the bundle provider without it being + advertised by the Git server. + +* The client can choose to discover bundle providers that are advertised + by the Git server. This could happen during `git clone`, during + `git fetch`, both, or neither. The user can choose which combination + works best for them. + +* The client can choose to configure a bundle provider manually at any + time. The client can also choose to specify a bundle provider manually + as a command-line option to `git clone`. + +Each repository is different and every Git server has different needs. +Hopefully the bundle URI feature is flexible enough to satisfy all needs. +If not, then the feature can be extended through its versioning mechanism. + +Server requirements +------------------- + +To provide a server-side implementation of bundle servers, no other parts +of the Git protocol are required. This allows server maintainers to use +static content solutions such as CDNs in order to serve the bundle files. + +At the current scope of the bundle URI feature, all URIs are expected to +be HTTP(S) URLs where content is downloaded to a local file using a `GET` +request to that URL. The server could include authentication requirements +to those requests with the aim of triggering the configured credential +helper for secure access. (Future extensions could use "file://" URIs or +SSH URIs.) + +Assuming a `200 OK` response from the server, the content at the URL is +inspected. First, Git attempts to parse the file as a bundle file of +version 2 or higher. If the file is not a bundle, then the file is parsed +as a plain-text file using Git's config parser. The key-value pairs in +that config file are expected to describe a list of bundle URIs. If +neither of these parse attempts succeed, then Git will report an error to +the user that the bundle URI provided erroneous data. + +Any other data provided by the server is considered erroneous. + +Bundle Lists +------------ + +The Git server can advertise bundle URIs using a set of `key=value` pairs. +A bundle URI can also serve a plain-text file in the Git config format +containing these same `key=value` pairs. In both cases, we consider this +to be a _bundle list_. The pairs specify information about the bundles +that the client can use to make decisions for which bundles to download +and which to ignore. + +A few keys focus on properties of the list itself. + +bundle.version:: + (Required) This value provides a version number for the bundle + list. If a future Git change enables a feature that needs the Git + client to react to a new key in the bundle list file, then this version + will increment. The only current version number is 1, and if any other + value is specified then Git will fail to use this file. + +bundle.mode:: + (Required) This value has one of two values: `all` and `any`. When `all` + is specified, then the client should expect to need all of the listed + bundle URIs that match their repository's requirements. When `any` is + specified, then the client should expect that any one of the bundle URIs + that match their repository's requirements will suffice. Typically, the + `any` option is used to list a number of different bundle servers + located in different geographies. + +bundle.heuristic:: + If this string-valued key exists, then the bundle list is designed to + work well with incremental `git fetch` commands. The heuristic signals + that there are additional keys available for each bundle that help + determine which subset of bundles the client should download. The only + heuristic currently planned is `creationToken`. + +The remaining keys include an `<id>` segment which is a server-designated +name for each available bundle. The `<id>` must contain only alphanumeric +and `-` characters. + +bundle.<id>.uri:: + (Required) This string value is the URI for downloading bundle `<id>`. + If the URI begins with a protocol (`http://` or `https://`) then the URI + is absolute. Otherwise, the URI is interpreted as relative to the URI + used for the bundle list. If the URI begins with `/`, then that relative + path is relative to the domain name used for the bundle list. (This use + of relative paths is intended to make it easier to distribute a set of + bundles across a large number of servers or CDNs with different domain + names.) + +bundle.<id>.filter:: + This string value represents an object filter that should also appear in + the header of this bundle. The server uses this value to differentiate + different kinds of bundles from which the client can choose those that + match their object filters. + +bundle.<id>.creationToken:: + This value is a nonnegative 64-bit integer used for sorting the bundles + the list. This is used to download a subset of bundles during a fetch + when `bundle.heuristic=creationToken`. + +bundle.<id>.location:: + This string value advertises a real-world location from where the bundle + URI is served. This can be used to present the user with an option for + which bundle URI to use or simply as an informative indicator of which + bundle URI was selected by Git. This is only valuable when + `bundle.mode` is `any`. + +Here is an example bundle list using the Git config format: + + [bundle] + version = 1 + mode = all + heuristic = creationToken + + [bundle "2022-02-09-1644442601-daily"] + uri = https://bundles.example.com/git/git/2022-02-09-1644442601-daily.bundle + creationToken = 1644442601 + + [bundle "2022-02-02-1643842562"] + uri = https://bundles.example.com/git/git/2022-02-02-1643842562.bundle + creationToken = 1643842562 + + [bundle "2022-02-09-1644442631-daily-blobless"] + uri = 2022-02-09-1644442631-daily-blobless.bundle + creationToken = 1644442631 + filter = blob:none + + [bundle "2022-02-02-1643842568-blobless"] + uri = /git/git/2022-02-02-1643842568-blobless.bundle + creationToken = 1643842568 + filter = blob:none + +This example uses `bundle.mode=all` as well as the +`bundle.<id>.creationToken` heuristic. It also uses the `bundle.<id>.filter` +options to present two parallel sets of bundles: one for full clones and +another for blobless partial clones. + +Suppose that this bundle list was found at the URI +`https://bundles.example.com/git/git/` and so the two blobless bundles have +the following fully-expanded URIs: + +* `https://bundles.example.com/git/git/2022-02-09-1644442631-daily-blobless.bundle` +* `https://bundles.example.com/git/git/2022-02-02-1643842568-blobless.bundle` + +Advertising Bundle URIs +----------------------- + +If a user knows a bundle URI for the repository they are cloning, then +they can specify that URI manually through a command-line option. However, +a Git host may want to advertise bundle URIs during the clone operation, +helping users unaware of the feature. + +The only thing required for this feature is that the server can advertise +one or more bundle URIs. This advertisement takes the form of a new +protocol v2 capability specifically for discovering bundle URIs. + +The client could choose an arbitrary bundle URI as an option _or_ select +the URI with best performance by some exploratory checks. It is up to the +bundle provider to decide if having multiple URIs is preferable to a +single URI that is geodistributed through server-side infrastructure. + +Cloning with Bundle URIs +------------------------ + +The primary need for bundle URIs is to speed up clones. The Git client +will interact with bundle URIs according to the following flow: + +1. The user specifies a bundle URI with the `--bundle-uri` command-line + option _or_ the client discovers a bundle list advertised by the + Git server. + +2. If the downloaded data from a bundle URI is a bundle, then the client + inspects the bundle headers to check that the prerequisite commit OIDs + are present in the client repository. If some are missing, then the + client delays unbundling until other bundles have been unbundled, + making those OIDs present. When all required OIDs are present, the + client unbundles that data using a refspec. The default refspec is + `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs + are stored so that later `git fetch` negotiations can communicate the + bundled refs as `have`s, reducing the size of the fetch over the Git + protocol. To allow pruning refs from this ref namespace, Git may + introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that + stale bundle refs can be deleted. + +3. If the file is instead a bundle list, then the client inspects the + `bundle.mode` to see if the list is of the `all` or `any` form. + + a. If `bundle.mode=all`, then the client considers all bundle + URIs. The list is reduced based on the `bundle.<id>.filter` options + matching the client repository's partial clone filter. Then, all + bundle URIs are requested. If the `bundle.<id>.creationToken` + heuristic is provided, then the bundles are downloaded in decreasing + order by the creation token, stopping when a bundle has all required + OIDs. The bundles can then be unbundled in increasing creation token + order. The client stores the latest creation token as a heuristic + for avoiding future downloads if the bundle list does not advertise + bundles with larger creation tokens. + + b. If `bundle.mode=any`, then the client can choose any one of the + bundle URIs to inspect. The client can use a variety of ways to + choose among these URIs. The client can also fallback to another URI + if the initial choice fails to return a result. + +Note that during a clone we expect that all bundles will be required, and +heuristics such as `bundle.<uri>.creationToken` can be used to download +bundles in chronological order or in parallel. + +If a given bundle URI is a bundle list with a `bundle.heuristic` +value, then the client can choose to store that URI as its chosen bundle +URI. The client can then navigate directly to that URI during later `git +fetch` calls. + +When downloading bundle URIs, the client can choose to inspect the initial +content before committing to downloading the entire content. This may +provide enough information to determine if the URI is a bundle list or +a bundle. In the case of a bundle, the client may inspect the bundle +header to determine that all advertised tips are already in the client +repository and cancel the remaining download. + +Fetching with Bundle URIs +------------------------- + +When the client fetches new data, it can decide to fetch from bundle +servers before fetching from the origin remote. This could be done via a +command-line option, but it is more likely useful to use a config value +such as the one specified during the clone. + +The fetch operation follows the same procedure to download bundles from a +bundle list (although we do _not_ want to use parallel downloads here). We +expect that the process will end when all prerequisite commit OIDs in a +thin bundle are already in the object database. + +When using the `creationToken` heuristic, the client can avoid downloading +any bundles if their creation tokenss are not larger than the stored +creation token. After fetching new bundles, Git updates this local +creation token. + +If the bundle provider does not provide a heuristic, then the client +should attempt to inspect the bundle headers before downloading the full +bundle data in case the bundle tips already exist in the client +repository. + +Error Conditions +---------------- + +If the Git client discovers something unexpected while downloading +information according to a bundle URI or the bundle list found at that +location, then Git can ignore that data and continue as if it was not +given a bundle URI. The remote Git server is the ultimate source of truth, +not the bundle URI. + +Here are a few example error conditions: + +* The client fails to connect with a server at the given URI or a connection + is lost without any chance to recover. + +* The client receives a 400-level response (such as `404 Not Found` or + `401 Not Authorized`). The client should use the credential helper to + find and provide a credential for the URI, but match the semantics of + Git's other HTTP protocols in terms of handling specific 400-level + errors. + +* The server reports any other failure reponse. + +* The client receives data that is not parsable as a bundle or bundle list. + +* A bundle includes a filter that does not match expectations. + +* The client cannot unbundle the bundles because the prerequisite commit OIDs + are not in the object database and there are no more bundles to download. + +There are also situations that could be seen as wasteful, but are not +error conditions: + +* The downloaded bundles contain more information than is requested by + the clone or fetch request. A primary example is if the user requests + a clone with `--single-branch` but downloads bundles that store every + reachable commit from all `refs/heads/*` references. This might be + initially wasteful, but perhaps these objects will become reachable by + a later ref update that the client cares about. + +* A bundle download during a `git fetch` contains objects already in the + object database. This is probably unavoidable if we are using bundles + for fetches, since the client will almost always be slightly ahead of + the bundle servers after performing its "catch-up" fetch to the remote + server. This extra work is most wasteful when the client is fetching + much more frequently than the server is computing bundles, such as if + the client is using hourly prefetches with background maintenance, but + the server is computing bundles weekly. For this reason, the client + should not use bundle URIs for fetch unless the server has explicitly + recommended it through a `bundle.heuristic` value. + +Example Bundle Provider organization +------------------------------------ + +The bundle URI feature is intentionally designed to be flexible to +different ways a bundle provider wants to organize the object data. +However, it can be helpful to have a complete organization model described +here so providers can start from that base. + +This example organization is a simplified model of what is used by the +GVFS Cache Servers (see section near the end of this document) which have +been beneficial in speeding up clones and fetches for very large +repositories, although using extra software outside of Git. + +The bundle provider deploys servers across multiple geographies. Each +server manages its own bundle set. The server can track a number of Git +repositories, but provides a bundle list for each based on a pattern. For +example, when mirroring a repository at `https://<domain>/<org>/<repo>` +the bundle server could have its bundle list available at +`https://<server-url>/<domain>/<org>/<repo>`. The origin Git server can +list all of these servers under the "any" mode: + + [bundle] + version = 1 + mode = any + + [bundle "eastus"] + uri = https://eastus.example.com/<domain>/<org>/<repo> + + [bundle "europe"] + uri = https://europe.example.com/<domain>/<org>/<repo> + + [bundle "apac"] + uri = https://apac.example.com/<domain>/<org>/<repo> + +This "list of lists" is static and only changes if a bundle server is +added or removed. + +Each bundle server manages its own set of bundles. The initial bundle list +contains only a single bundle, containing all of the objects received from +cloning the repository from the origin server. The list uses the +`creationToken` heuristic and a `creationToken` is made for the bundle +based on the server's timestamp. + +The bundle server runs regularly-scheduled updates for the bundle list, +such as once a day. During this task, the server fetches the latest +contents from the origin server and generates a bundle containing the +objects reachable from the latest origin refs, but not contained in a +previously-computed bundle. This bundle is added to the list, with care +that the `creationToken` is strictly greater than the previous maximum +`creationToken`. + +When the bundle list grows too large, say more than 30 bundles, then the +oldest "_N_ minus 30" bundles are combined into a single bundle. This +bundle's `creationToken` is equal to the maximum `creationToken` among the +merged bundles. + +An example bundle list is provided here, although it only has two daily +bundles and not a full list of 30: + + [bundle] + version = 1 + mode = all + heuristic = creationToken + + [bundle "2022-02-13-1644770820-daily"] + uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-09-1644770820-daily.bundle + creationToken = 1644770820 + + [bundle "2022-02-09-1644442601-daily"] + uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-09-1644442601-daily.bundle + creationToken = 1644442601 + + [bundle "2022-02-02-1643842562"] + uri = https://eastus.example.com/<domain>/<org>/<repo>/2022-02-02-1643842562.bundle + creationToken = 1643842562 + +To avoid storing and serving object data in perpetuity despite becoming +unreachable in the origin server, this bundle merge can be more careful. +Instead of taking an absolute union of the old bundles, instead the bundle +can be created by looking at the newer bundles and ensuring that their +necessary commits are all available in this merged bundle (or in another +one of the newer bundles). This allows "expiring" object data that is not +being used by new commits in this window of time. That data could be +reintroduced by a later push. + +The intention of this data organization has two main goals. First, initial +clones of the repository become faster by downloading precomputed object +data from a closer source. Second, `git fetch` commands can be faster, +especially if the client has not fetched for a few days. However, if a +client does not fetch for 30 days, then the bundle list organization would +cause redownloading a large amount of object data. + +One way to make this organization more useful to users who fetch frequently +is to have more frequent bundle creation. For example, bundles could be +created every hour, and then once a day those "hourly" bundles could be +merged into a "daily" bundle. The daily bundles are merged into the +oldest bundle after 30 days. + +It is recommened that this bundle strategy is repeated with the `blob:none` +filter if clients of this repository are expecting to use blobless partial +clones. This list of blobless bundles stays in the same list as the full +bundles, but uses the `bundle.<id>.filter` key to separate the two groups. +For very large repositories, the bundle provider may want to _only_ provide +blobless bundles. + +Implementation Plan +------------------- + +This design document is being submitted on its own as an aspirational +document, with the goal of implementing all of the mentioned client +features over the course of several patch series. Here is a potential +outline for submitting these features: + +1. Integrate bundle URIs into `git clone` with a `--bundle-uri` option. + This will include a new `git fetch --bundle-uri` mode for use as the + implementation underneath `git clone`. The initial version here will + expect a single bundle at the given URI. + +2. Implement the ability to parse a bundle list from a bundle URI and + update the `git fetch --bundle-uri` logic to properly distinguish + between `bundle.mode` options. Specifically design the feature so + that the config format parsing feeds a list of key-value pairs into the + bundle list logic. + +3. Create the `bundle-uri` protocol v2 command so Git servers can advertise + bundle URIs using the key-value pairs. Plug into the existing key-value + input to the bundle list logic. Allow `git clone` to discover these + bundle URIs and bootstrap the client repository from the bundle data. + (This choice is an opt-in via a config option and a command-line + option.) + +4. Allow the client to understand the `bundle.flag=forFetch` configuration + and the `bundle.<id>.creationToken` heuristic. When `git clone` + discovers a bundle URI with `bundle.flag=forFetch`, it configures the + client repository to check that bundle URI during later `git fetch <remote>` + commands. + +5. Allow clients to discover bundle URIs during `git fetch` and configure + a bundle URI for later fetches if `bundle.flag=forFetch`. + +6. Implement the "inspect headers" heuristic to reduce data downloads when + the `bundle.<id>.creationToken` heuristic is not available. + +As these features are reviewed, this plan might be updated. We also expect +that new designs will be discovered and implemented as this feature +matures and becomes used in real-world scenarios. + +Related Work: Packfile URIs +--------------------------- + +The Git protocol already has a capability where the Git server can list +a set of URLs along with the packfile response when serving a client +request. The client is then expected to download the packfiles at those +locations in order to have a complete understanding of the response. + +This mechanism is used by the Gerrit server (implemented with JGit) and +has been effective at reducing CPU load and improving user performance for +clones. + +A major downside to this mechanism is that the origin server needs to know +_exactly_ what is in those packfiles, and the packfiles need to be available +to the user for some time after the server has responded. This coupling +between the origin and the packfile data is difficult to manage. + +Further, this implementation is extremely hard to make work with fetches. + +Related Work: GVFS Cache Servers +-------------------------------- + +The GVFS Protocol [2] is a set of HTTP endpoints designed independently of +the Git project before Git's partial clone was created. One feature of this +protocol is the idea of a "cache server" which can be colocated with build +machines or developer offices to transfer Git data without overloading the +central server. + +The endpoint that VFS for Git is famous for is the `GET /gvfs/objects/{oid}` +endpoint, which allows downloading an object on-demand. This is a critical +piece of the filesystem virtualization of that product. + +However, a more subtle need is the `GET /gvfs/prefetch?lastPackTimestamp=<t>` +endpoint. Given an optional timestamp, the cache server responds with a list +of precomputed packfiles containing the commits and trees that were introduced +in those time intervals. + +The cache server computes these "prefetch" packfiles using the following +strategy: + +1. Every hour, an "hourly" pack is generated with a given timestamp. +2. Nightly, the previous 24 hourly packs are rolled up into a "daily" pack. +3. Nightly, all prefetch packs more than 30 days old are rolled up into + one pack. + +When a user runs `gvfs clone` or `scalar clone` against a repo with cache +servers, the client requests all prefetch packfiles, which is at most +`24 + 30 + 1` packfiles downloading only commits and trees. The client +then follows with a request to the origin server for the references, and +attempts to checkout that tip reference. (There is an extra endpoint that +helps get all reachable trees from a given commit, in case that commit +was not already in a prefetch packfile.) + +During a `git fetch`, a hook requests the prefetch endpoint using the +most-recent timestamp from a previously-downloaded prefetch packfile. +Only the list of packfiles with later timestamps are downloaded. Most +users fetch hourly, so they get at most one hourly prefetch pack. Users +whose machines have been off or otherwise have not fetched in over 30 days +might redownload all prefetch packfiles. This is rare. + +It is important to note that the clients always contact the origin server +for the refs advertisement, so the refs are frequently "ahead" of the +prefetched pack data. The missing objects are downloaded on-demand using +the `GET gvfs/objects/{oid}` requests, when needed by a command such as +`git checkout` or `git log`. Some Git optimizations disable checks that +would cause these on-demand downloads to be too aggressive. + +See Also +-------- + +[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/ + An earlier RFC for a bundle URI feature. + +[2] https://github.com/microsoft/VFSForGit/blob/master/Protocol.md + The GVFS Protocol diff --git a/Documentation/technical/cruft-packs.txt b/Documentation/technical/cruft-packs.txt deleted file mode 100644 index d81f3a8982..0000000000 --- a/Documentation/technical/cruft-packs.txt +++ /dev/null @@ -1,123 +0,0 @@ -= Cruft packs - -The cruft packs feature offer an alternative to Git's traditional mechanism of -removing unreachable objects. This document provides an overview of Git's -pruning mechanism, and how a cruft pack can be used instead to accomplish the -same. - -== Background - -To remove unreachable objects from your repository, Git offers `git repack -Ad` -(see linkgit:git-repack[1]). Quoting from the documentation: - -[quote] -[...] unreachable objects in a previous pack become loose, unpacked objects, -instead of being left in the old pack. [...] loose unreachable objects will be -pruned according to normal expiry rules with the next 'git gc' invocation. - -Unreachable objects aren't removed immediately, since doing so could race with -an incoming push which may reference an object which is about to be deleted. -Instead, those unreachable objects are stored as loose objects and stay that way -until they are older than the expiration window, at which point they are removed -by linkgit:git-prune[1]. - -Git must store these unreachable objects loose in order to keep track of their -per-object mtimes. If these unreachable objects were written into one big pack, -then either freshening that pack (because an object contained within it was -re-written) or creating a new pack of unreachable objects would cause the pack's -mtime to get updated, and the objects within it would never leave the expiration -window. Instead, objects are stored loose in order to keep track of the -individual object mtimes and avoid a situation where all cruft objects are -freshened at once. - -This can lead to undesirable situations when a repository contains many -unreachable objects which have not yet left the grace period. Having large -directories in the shards of `.git/objects` can lead to decreased performance in -the repository. But given enough unreachable objects, this can lead to inode -starvation and degrade the performance of the whole system. Since we -can never pack those objects, these repositories often take up a large amount of -disk space, since we can only zlib compress them, but not store them in delta -chains. - -== Cruft packs - -A cruft pack eliminates the need for storing unreachable objects in a loose -state by including the per-object mtimes in a separate file alongside a single -pack containing all loose objects. - -A cruft pack is written by `git repack --cruft` when generating a new pack. -linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft` -is a classic all-into-one repack, meaning that everything in the resulting pack is -reachable, and everything else is unreachable. Once written, the `--cruft` -option instructs `git repack` to generate another pack containing only objects -not packed in the previous step (which equates to packing all unreachable -objects together). This progresses as follows: - - 1. Enumerate every object, marking any object which is (a) not contained in a - kept-pack, and (b) whose mtime is within the grace period as a traversal - tip. - - 2. Perform a reachability traversal based on the tips gathered in the previous - step, adding every object along the way to the pack. - - 3. Write the pack out, along with a `.mtimes` file that records the per-object - timestamps. - -This mode is invoked internally by linkgit:git-repack[1] when instructed to -write a cruft pack. Crucially, the set of in-core kept packs is exactly the set -of packs which will not be deleted by the repack; in other words, they contain -all of the repository's reachable objects. - -When a repository already has a cruft pack, `git repack --cruft` typically only -adds objects to it. An exception to this is when `git repack` is given the -`--cruft-expiration` option, which allows the generated cruft pack to omit -expired objects instead of waiting for linkgit:git-gc[1] to expire those objects -later on. - -It is linkgit:git-gc[1] that is typically responsible for removing expired -unreachable objects. - -== Caution for mixed-version environments - -Repositories that have cruft packs in them will continue to work with any older -version of Git. Note, however, that previous versions of Git which do not -understand the `.mtimes` file will use the cruft pack's mtime as the mtime for -all of the objects in it. In other words, do not expect older (pre-cruft pack) -versions of Git to interpret or even read the contents of the `.mtimes` file. - -Note that having mixed versions of Git GC-ing the same repository can lead to -unreachable objects never being completely pruned. This can happen under the -following circumstances: - - - An older version of Git running GC explodes the contents of an existing - cruft pack loose, using the cruft pack's mtime. - - A newer version running GC collects those loose objects into a cruft pack, - where the .mtime file reflects the loose object's actual mtimes, but the - cruft pack mtime is "now". - -Repeating this process will lead to unreachable objects not getting pruned as a -result of repeatedly resetting the objects' mtimes to the present time. - -If you are GC-ing repositories in a mixed version environment, consider omitting -the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and -leaving the `gc.cruftPacks` configuration unset until all writers understand -cruft packs. - -== Alternatives - -Notable alternatives to this design include: - - - The location of the per-object mtime data, and - - Storing unreachable objects in multiple cruft packs. - -On the location of mtime data, a new auxiliary file tied to the pack was chosen -to avoid complicating the `.idx` format. If the `.idx` format were ever to gain -support for optional chunks of data, it may make sense to consolidate the -`.mtimes` format into the `.idx` itself. - -Storing unreachable objects among multiple cruft packs (e.g., creating a new -cruft pack during each repacking operation including only unreachable objects -which aren't already stored in an earlier cruft pack) is significantly more -complicated to construct, and so aren't pursued here. The obvious drawback to -the current implementation is that the entire cruft pack must be re-written from -scratch. diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 260224b033..e2ac36dd21 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -205,7 +205,7 @@ SHA-1 content. Object storage ~~~~~~~~~~~~~~ Loose objects use zlib compression and packed objects use the packed -format described in Documentation/technical/pack-format.txt, just like +format described in linkgit:gitformat-pack[5], just like today. The content that is compressed and stored uses SHA-256 content instead of SHA-1 content. diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.txt index aa0aa9af1c..6f33654b42 100644 --- a/Documentation/technical/long-running-process-protocol.txt +++ b/Documentation/technical/long-running-process-protocol.txt @@ -3,7 +3,7 @@ Long-running process protocol This protocol is used when Git needs to communicate with an external process throughout the entire life of a single Git command. All -communication is in pkt-line format (see technical/protocol-common.txt) +communication is in pkt-line format (see linkgit:gitprotocol-common[5]) over standard input and standard output. Handshake diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.txt index 1eb525fe76..9d453d4765 100644 --- a/Documentation/technical/packfile-uri.txt +++ b/Documentation/technical/packfile-uri.txt @@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section directly before the `packfile` section (right after `wanted-refs` if it is sent) containing URIs of any of the given protocols. The URIs point to packfiles that use only features that the client has declared that it supports -(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of +(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of this section. Clients should then download and index all the given URIs (in addition to diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt index 99f0eb3040..92fcee2bff 100644 --- a/Documentation/technical/partial-clone.txt +++ b/Documentation/technical/partial-clone.txt @@ -79,7 +79,7 @@ Design Details upload-pack negotiation. + This uses the existing capability discovery mechanism. -See "filter" in Documentation/technical/pack-protocol.txt. +See "filter" in linkgit:gitprotocol-pack[5]. - Clients pass a "filter-spec" to clone and fetch which is passed to the server to request filtering during packfile construction. diff --git a/Documentation/technical/scalar.txt b/Documentation/technical/scalar.txt new file mode 100644 index 0000000000..0600150b3a --- /dev/null +++ b/Documentation/technical/scalar.txt @@ -0,0 +1,127 @@ +Scalar +====== + +Scalar is a repository management tool that optimizes Git for use in large +repositories. It accomplishes this by helping users to take advantage of +advanced performance features in Git. Unlike most other Git built-in commands, +Scalar is not executed as a subcommand of 'git'; rather, it is built as a +separate executable containing its own series of subcommands. + +Background +---------- + +Scalar was originally designed as an add-on to Git and implemented as a .NET +Core application. It was created based on the learnings from the VFS for Git +project (another application aimed at improving the experience of working with +large repositories). As part of its initial implementation, Scalar relied on +custom features in the Microsoft fork of Git that have since been integrated +into core Git: + +* partial clone, +* commit graphs, +* multi-pack index, +* sparse checkout (cone mode), +* scheduled background maintenance, +* etc + +With the requisite Git functionality in place and a desire to bring the benefits +of Scalar to the larger Git community, the Scalar application itself was ported +from C# to C and integrated upstream. + +Features +-------- + +Scalar is comprised of two major pieces of functionality: automatically +configuring built-in Git performance features and managing repository +enlistments. + +The Git performance features configured by Scalar (see "Background" for +examples) confer substantial performance benefits to large repositories, but are +either too experimental to enable for all of Git yet, or only benefit large +repositories. As new features are introduced, Scalar should be updated +accordingly to incorporate them. This will prevent the tool from becoming stale +while also providing a path for more easily bringing features to the appropriate +users. + +Enlistments are how Scalar knows which repositories on a user's system should +utilize Scalar-configured features. This allows it to update performance +settings when new ones are added to the tool, as well as centrally manage +repository maintenance. The enlistment structure - a root directory with a +`src/` subdirectory containing the cloned repository itself - is designed to +encourage users to route build outputs outside of the repository to avoid the +performance-limiting overhead of ignoring those files in Git. + +Design +------ + +Scalar is implemented in C and interacts with Git via a mix of child process +invocations of Git and direct usage of `libgit.a`. Internally, it is structured +much like other built-ins with subcommands (e.g., `git stash`), containing a +`cmd_<subcommand>()` function for each subcommand, routed through a `cmd_main()` +function. Most options are unique to each subcommand, with `scalar` respecting +some "global" `git` options (e.g., `-c` and `-C`). + +Because `scalar` is not invoked as a Git subcommand (like `git scalar`), it is +built and installed as its own executable in the `bin/` directory, alongside +`git`, `git-gui`, etc. + +Roadmap +------- + +NOTE: this section will be removed once the remaining tasks outlined in this +roadmap are complete. + +Scalar is a large enough project that it is being upstreamed incrementally, +living in `contrib/` until it is feature-complete. So far, the following patch +series have been accepted: + +- `scalar-the-beginning`: The initial patch series which sets up + `contrib/scalar/` and populates it with a minimal `scalar` command that + demonstrates the fundamental ideas. + +- `scalar-c-and-C`: The `scalar` command learns about two options that can be + specified before the command, `-c <key>=<value>` and `-C <directory>`. + +- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand. + +- `scalar-generalize-diagnose`: Move the functionality of `scalar diagnose` + into `git diagnose` and `git bugreport --diagnose`. + +- 'scalar-add-fsmonitor: Enable the built-in FSMonitor in Scalar + enlistments. At the end of this series, Scalar should be feature-complete + from the perspective of a user. + +Roughly speaking (and subject to change), the following series are needed to +"finish" this initial version of Scalar: + +- Move Scalar to toplevel: Move Scalar out of `contrib/` and into the root of + `git`. This includes a variety of related updates, including: + - building & installing Scalar in the Git root-level 'make [install]'. + - builing & testing Scalar as part of CI. + - moving and expanding test coverage of Scalar (including perf tests). + - implementing 'scalar help'/'git help scalar' to display scalar + documentation. + +Finally, there are two additional patch series that exist in Microsoft's fork of +Git, but there is no current plan to upstream them. There are some interesting +ideas there, but the implementation is too specific to Azure Repos and/or VFS +for Git to be of much help in general. + +These still exist mainly because the GVFS protocol is what Azure Repos has +instead of partial clone, while Git is focused on improving partial clone: + +- `scalar-with-gvfs`: The primary purpose of this patch series is to support + existing Scalar users whose repositories are hosted in Azure Repos (which does + not support Git's partial clones, but supports its predecessor, the GVFS + protocol, which is used by Scalar to emulate the partial clone). + + Since the GVFS protocol will never be supported by core Git, this patch series + will remain in Microsoft's fork of Git. + +- `run-scalar-functional-tests`: The Scalar project developed a quite + comprehensive set of integration tests (or, "Functional Tests"). They are the + sole remaining part of the original C#-based Scalar project, and this patch + adds a GitHub workflow that runs them all. + + Since the tests partially depend on features that are only provided in the + `scalar-with-gvfs` patch series, this patch cannot be upstreamed. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 865074bed4..ca9decdd95 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -3133,7 +3133,7 @@ those "loose" objects. You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in link:technical/pack-format.html[pack format]. +found in link:gitformat-pack[5]. To put the loose objects into a pack, just run git repack: |