summaryrefslogtreecommitdiff
path: root/Documentation
AgeCommit message (Collapse)AuthorFilesLines
2022-02-25Merge branch 'js/apply-partial-clone-filters-recursively'Libravatar Junio C Hamano3-2/+16
"git clone --filter=... --recurse-submodules" only makes the top-level a partial clone, while submodules are fully cloned. This behaviour is changed to pass the same filter down to the submodules. * js/apply-partial-clone-filters-recursively: clone, submodule: pass partial clone filters to submodules
2022-02-25Merge branch 'ds/sparse-checkout-requires-per-worktree-config'Libravatar Junio C Hamano4-9/+57
"git sparse-checkout" wants to work with per-worktree configuration, but did not work well in a worktree attached to a bare repository. * ds/sparse-checkout-requires-per-worktree-config: config: make git_configset_get_string_tmp() private worktree: copy sparse-checkout patterns and config on add sparse-checkout: set worktree-config correctly config: add repo_config_set_worktree_gently() worktree: create init_worktree_config() Documentation: add extensions.worktreeConfig details
2022-02-23The seventh batchLibravatar Junio C Hamano1-0/+12
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-23Merge branch 'bc/clarify-eol-attr'Libravatar Junio C Hamano1-5/+6
Documentation update * bc/clarify-eol-attr: doc: clarify interaction between 'eol' and text=auto
2022-02-18The sixth batchLibravatar Junio C Hamano1-0/+34
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-18Merge branch 'jc/glossary-worktree'Libravatar Junio C Hamano1-2/+11
"working tree" and "per-worktree ref" were in glossary, but "worktree" itself wasn't, which has been corrected. * jc/glossary-worktree: glossary: describe "worktree"
2022-02-18Merge branch 'gc/branch-recurse-submodules'Libravatar Junio C Hamano3-12/+47
"git branch" learned the "--recurse-submodules" option. * gc/branch-recurse-submodules: branch.c: use 'goto cleanup' in setup_tracking() to fix memory leaks branch: add --recurse-submodules option for branch creation builtin/branch: consolidate action-picking logic in cmd_branch() branch: add a dry_run parameter to create_branch() branch: make create_branch() always create a branch branch: move --set-upstream-to behavior to dwim_and_setup_tracking()
2022-02-17The fifth batchLibravatar Junio C Hamano1-0/+24
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-17Merge branch 'po/doc-check-ignore-markup-fix'Libravatar Junio C Hamano1-2/+2
Typofix. * po/doc-check-ignore-markup-fix: doc: check-ignore: code-quote an exclamation mark
2022-02-17Merge branch 'vd/sparse-clean-etc'Libravatar Junio C Hamano1-2/+8
"git update-index", "git checkout-index", and "git clean" are taught to work better with the sparse checkout feature. * vd/sparse-clean-etc: update-index: reduce scope of index expansion in do_reupdate update-index: integrate with sparse index update-index: add tests for sparse-checkout compatibility checkout-index: integrate with sparse index checkout-index: add --ignore-skip-worktree-bits option checkout-index: expand sparse checkout compatibility tests clean: integrate with sparse index reset: reorder wildcard pathspec conditions reset: fix validation in sparse index test
2022-02-17Merge branch 'jz/rev-list-exclude-first-parent-only'Libravatar Junio C Hamano1-7/+15
"git log" and friends learned an option --exclude-first-parent-only to propagate UNINTERESTING bit down only along the first-parent chain, just like --first-parent option shows commits that lack the UNINTERESTING bit only along the first-parent chain. * jz/rev-list-exclude-first-parent-only: git-rev-list: add --exclude-first-parent-only flag
2022-02-16The fourth batchLibravatar Junio C Hamano1-0/+28
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-16Merge branch 'js/no-more-legacy-stash'Libravatar Junio C Hamano1-7/+0
Removal of unused code and doc. * js/no-more-legacy-stash: stash: stop warning about the obsolete `stash.useBuiltin` config setting stash: remove documentation for `stash.useBuiltin` add: remove support for `git-legacy-stash` git-sh-setup: remove remnant bits referring to `git-legacy-stash`
2022-02-16Merge branch 'js/diff-filter-negation-fix'Libravatar Junio C Hamano1-5/+2
"git diff --diff-filter=aR" is now parsed correctly. * js/diff-filter-negation-fix: diff-filter: be more careful when looking for negative bits diff.c: move the diff filter bits definitions up a bit docs(diff): lose incorrect claim about `diff-files --diff-filter=A`
2022-02-16Merge branch 'en/fetch-negotiation-default-fix'Libravatar Junio C Hamano1-12/+13
Interaction between fetch.negotiationAlgorithm and feature.experimental configuration variables has been corrected. * en/fetch-negotiation-default-fix: repo-settings: rename the traditional default fetch.negotiationAlgorithm repo-settings: fix error handling for unknown values repo-settings: fix checking for fetch.negotiationAlgorithm=default
2022-02-16Merge branch 'tb/midx-bitmap-corruption-fix'Libravatar Junio C Hamano2-6/+8
A bug that made multi-pack bitmap and the object order out-of-sync, making the .midx data corrupt, has been fixed. * tb/midx-bitmap-corruption-fix: pack-bitmap.c: gracefully fallback after opening pack/MIDX midx: read `RIDX` chunk when present t/lib-bitmap.sh: parameterize tests over reverse index source t5326: move tests to t/lib-bitmap.sh t5326: extract `test_rev_exists` t5326: drop unnecessary setup pack-revindex.c: instrument loading on-disk reverse index midx.c: make changing the preferred pack safe t5326: demonstrate bitmap corruption after permutation
2022-02-16Merge branch 'en/remerge-diff'Libravatar Junio C Hamano1-1/+13
"git log --remerge-diff" shows the difference from mechanical merge result and the result that is actually recorded in a merge commit. * en/remerge-diff: diff-merges: avoid history simplifications when diffing merges merge-ort: mark conflict/warning messages from inner merges as omittable show, log: include conflict/warning messages in --remerge-diff headers diff: add ability to insert additional headers for paths merge-ort: format messages slightly different for use in headers merge-ort: mark a few more conflict messages as omittable merge-ort: capture and print ll-merge warnings in our preferred fashion ll-merge: make callers responsible for showing warnings log: clean unneeded objects during `log --remerge-diff` show, log: provide a --remerge-diff capability
2022-02-16Merge branch 'll/doc-mktree-typofix'Libravatar Junio C Hamano1-1/+1
Typofix. * ll/doc-mktree-typofix: fix typo in git-mktree.txt
2022-02-14doc: clarify interaction between 'eol' and text=autoLibravatar brian m. carlson1-5/+6
The `eol` takes effect on text files only when the index has the contents in LF line endings. Paths with contents in CRLF line endings in the index may become dirty unless text=auto. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-11The third batchLibravatar Junio C Hamano1-0/+19
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-11Merge branch 'jc/doc-log-messages'Libravatar Junio C Hamano2-0/+43
Update the contributor-facing documents on proposed log messages. * jc/doc-log-messages: SubmittingPatches: explain why we care about log messages CodingGuidelines: hint why we value clearly written log messages SubmittingPatches: write problem statement in the log in the present tense
2022-02-11Merge branch 'gh/doc-typos'Libravatar Junio C Hamano1-2/+2
Typofix. * gh/doc-typos: Documentation/config/pgp.txt: add missing apostrophe Documentation/config/pgp.txt: replace stray <TAB> character with <SPC>
2022-02-11Merge branch 'bc/clarify-eol-attr'Libravatar Junio C Hamano1-5/+6
Doc and test update around the eol attribute. * bc/clarify-eol-attr: docs: correct documentation about eol attribute t0027: add tests for eol without text in .gitattributes
2022-02-09glossary: describe "worktree"Libravatar Junio C Hamano1-2/+11
We have description on "per worktree ref", but "worktree" is not described in the glossary. We do have "working tree", though. Casually put, a "working tree" is what your editor and compiler interacts with. "worktree" is a mechanism to allow one or more "working tree"s to be attached to a repository and used to check out different commits and branches independently, which includes not just a "working tree" but also repository metadata like HEAD, the index to support simultaneous use of them. Historically, we used these terms interchangeably but we have been trying to use "working tree" when we mean it, instead of "worktree". Most of the existing references to "working tree" in the glossary do refer primarily to the working tree portion, except for one that said refs like HEAD and refs/bisect/* are per "working tree", but it is more precise to say they are per "worktree". Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-09clone, submodule: pass partial clone filters to submodulesLibravatar Josh Steadmon3-2/+16
When cloning a repo with a --filter and with --recurse-submodules enabled, the partial clone filter only applies to the top-level repo. This can lead to unexpected bandwidth and disk usage for projects which include large submodules. For example, a user might wish to make a partial clone of Gerrit and would run: `git clone --recurse-submodules --filter=blob:5k https://gerrit.googlesource.com/gerrit`. However, only the superproject would be a partial clone; all the submodules would have all blobs downloaded regardless of their size. With this change, the same filter can also be applied to submodules, meaning the expected bandwidth and disk savings apply consistently. To avoid changing default behavior, add a new clone flag, `--also-filter-submodules`. When this is set along with `--filter` and `--recurse-submodules`, the filter spec is passed along to git-submodule and git-submodule--helper, such that submodule clones also have the filter applied. This applies the same filter to the superproject and all submodules. Users who need to customize the filter per-submodule would need to clone with `--no-recurse-submodules` and then manually initialize each submodule with the proper filter. Applying filters to submodules should be safe thanks to Jonathan Tan's recent work [1, 2, 3] eliminating the use of alternates as a method of accessing submodule objects, so any submodule object access now triggers a lazy fetch from the submodule's promisor remote if the accessed object is missing. This patch is a reworked version of [4], which was created prior to Jonathan Tan's work. [1]: 8721e2e (Merge branch 'jt/partial-clone-submodule-1', 2021-07-16) [2]: 11e5d0a (Merge branch 'jt/grep-wo-submodule-odb-as-alternate', 2021-09-20) [3]: 162a13b (Merge branch 'jt/no-abuse-alternate-odb-for-submodules', 2021-10-25) [4]: https://lore.kernel.org/git/52bf9d45b8e2b72ff32aa773f2415bf7b2b86da2.1563322192.git.steadmon@google.com/ Signed-off-by: Josh Steadmon <steadmon@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-09The second batch for 2.36Libravatar Junio C Hamano1-1/+59
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-09Merge branch 'ab/config-based-hooks-2'Libravatar Junio C Hamano2-0/+49
More "config-based hooks". * ab/config-based-hooks-2: run-command: remove old run_hook_{le,ve}() hook API receive-pack: convert push-to-checkout hook to hook.h read-cache: convert post-index-change to use hook.h commit: convert {pre-commit,prepare-commit-msg} hook to hook.h git-p4: use 'git hook' to run hooks send-email: use 'git hook run' for 'sendemail-validate' git hook run: add an --ignore-missing flag hooks: convert worktree 'post-checkout' hook to hook library hooks: convert non-worktree 'post-checkout' hook to hook library merge: convert post-merge to use hook.h am: convert applypatch-msg to use hook.h rebase: convert pre-rebase to use hook.h hook API: add a run_hooks_l() wrapper am: convert {pre,post}-applypatch to use hook.h gc: use hook library for pre-auto-gc hook hook API: add a run_hooks() wrapper hook: add 'run' subcommand
2022-02-09Merge branch 'jc/name-rev-stdin'Libravatar Junio C Hamano1-2/+28
"git name-rev --stdin" does not behave like usual "--stdin" at all. Start the process of renaming it to "--annotate-stdin". * jc/name-rev-stdin: name-rev.c: use strbuf_getline instead of limited size buffer name-rev: deprecate --stdin in favor of --annotate-stdin
2022-02-09Merge branch 'gc/fetch-negotiate-only-early-return'Libravatar Junio C Hamano1-0/+1
"git fetch --negotiate-only" is an internal command used by "git push" to figure out which part of our history is missing from the other side. It should never recurse into submodules even when fetch.recursesubmodules configuration variable is set, nor it should trigger "gc". The code has been tightened up to ensure it only does common ancestry discovery and nothing else. * gc/fetch-negotiate-only-early-return: fetch: help translators by reusing the same message template fetch --negotiate-only: do not update submodules fetch: skip tasks related to fetching objects fetch: use goto cleanup in cmd_fetch()
2022-02-09Merge branch 'tl/doc-cli-options-first'Libravatar Junio C Hamano1-5/+14
We explain that revs come first before the pathspec among command line arguments, but did not spell out that dashed options come before other args, which has been corrected. * tl/doc-cli-options-first: git-cli.txt: clarify "options first and then args"
2022-02-09Merge branch 'jt/conditional-config-on-remote-url'Libravatar Junio C Hamano1-0/+35
The conditional inclusion mechanism of configuration files using "[includeIf <condition>]" learns to base its decision on the URL of the remote repository the repository interacts with. * jt/conditional-config-on-remote-url: config: include file if remote URL matches a glob config: make git_config_include() static
2022-02-08sparse-checkout: set worktree-config correctlyLibravatar Derrick Stolee1-4/+12
`git sparse-checkout set/init` enables worktree-specific configuration[*] by setting extensions.worktreeConfig=true, but neglects to perform the additional necessary bookkeeping of relocating `core.bare=true` and `core.worktree` from $GIT_COMMON_DIR/config to $GIT_COMMON_DIR/config.worktree, as documented in git-worktree.txt. As a result of this oversight, these settings, which are nonsensical for secondary worktrees, can cause Git commands to incorrectly consider a worktree bare (in the case of `core.bare`) or operate on the wrong worktree (in the case of `core.worktree`). Fix this problem by taking advantage of the recently-added init_worktree_config() which enables `extensions.worktreeConfig` and takes care of necessary bookkeeping. While at it, for backward-compatibility reasons, also stop upgrading the repository format to "1" since doing so is (unintentionally) not required to take advantage of `extensions.worktreeConfig`, as explained by 11664196ac ("Revert "check_repository_format_gently(): refuse extensions for old repositories"", 2020-07-15). [*] The main reason to use worktree-specific config for the sparse-checkout builtin was to avoid enabling sparse-checkout patterns in one and causing a loss of files in another. If a worktree does not have a sparse-checkout patterns file, then the sparse-checkout logic will not kick in on that worktree. Reported-by: Sean Allred <allred.sean@gmail.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Reviewed-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-08Documentation: add extensions.worktreeConfig detailsLibravatar Derrick Stolee3-5/+45
The extensions.worktreeConfig extension was added in 58b284a (worktree: add per-worktree config files, 2018-10-21) and was somewhat documented in Documentation/git-config.txt. However, the extensions.worktreeConfig value was not specified further in the list of possible config keys. The location of the config.worktree file is not specified, and there are some precautions that should be mentioned clearly, but are only mentioned in git-worktree.txt. Expand the documentation to help users discover the complexities of extensions.worktreeConfig by adding details and cross links in these locations (relative to Documentation/): - config/extensions.txt - git-config.txt - git-worktree.txt The updates focus on items such as * $GIT_DIR/config.worktree takes precedence over $GIT_COMMON_DIR/config. * The core.worktree and core.bare=true settings are incorrect to have in the common config file when extensions.worktreeConfig is enabled. * The sparse-checkout settings core.sparseCheckout[Cone] are recommended to be set in the worktree config. As documented in 11664196ac ("Revert "check_repository_format_gently(): refuse extensions for old repositories"", 2020-07-15), this extension must be considered regardless of the repository format version for historical reasons. A future change will update references to extensions.worktreeConfig within git-sparse-checkout.txt, but a behavior change is needed before making those updates. Helped-by: Elijah Newren <newren@gmail.com> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Reviewed-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-05The first batchLibravatar Junio C Hamano1-3/+23
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-05Merge branch 'ab/cat-file'Libravatar Junio C Hamano1-2/+8
Assorted updates to "git cat-file", especially "-h". * ab/cat-file: cat-file: s/_/-/ in typo'd usage_msg_optf() message cat-file: don't whitespace-pad "(...)" in SYNOPSIS and usage output cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters) object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY cat-file: correct and improve usage information cat-file: fix remaining usage bugs cat-file: make --batch-all-objects a CMDMODE cat-file: move "usage" variable to cmd_cat_file() cat-file docs: fix SYNOPSIS and "-h" output parse-options API: add a usage_msg_optf() cat-file tests: test messaging on bad objects/paths cat-file tests: test bad usage
2022-02-04branch: add --recurse-submodules option for branch creationLibravatar Glen Choo3-12/+47
To improve the submodules UX, we would like to teach Git to handle branches in submodules. Start this process by teaching "git branch" the --recurse-submodules option so that "git branch --recurse-submodules topic" will create the `topic` branch in the superproject and its submodules. Although this commit does not introduce breaking changes, it does not work well with existing --recurse-submodules commands because "git branch --recurse-submodules" writes to the submodule ref store, but most commands only consider the superproject gitlink and ignore the submodule ref store. For example, "git checkout --recurse-submodules" will check out the commits in the superproject gitlinks (and put the submodules in detached HEAD) instead of checking out the submodule branches. Because of this, this commit introduces a new configuration value, `submodule.propagateBranches`. The plan is for Git commands to prioritize submodule ref store information over superproject gitlinks if this value is true. Because "git branch --recurse-submodules" writes to submodule ref stores, for the sake of clarity, it will not function unless this configuration value is set. This commit also includes changes that support working with submodules from a superproject commit because "branch --recurse-submodules" (and future commands) need to read .gitmodules and gitlinks from the superproject commit, but submodules are typically read from the filesystem's .gitmodules and the index's gitlinks. These changes are: * add a submodules_of_tree() helper that gives the relevant information of an in-tree submodule (e.g. path and oid) and initializes the repository * add is_tree_submodule_active() by adding a treeish_name parameter to is_submodule_active() * add the "submoduleNotUpdated" advice to advise users to update the submodules in their trees Incidentally, fix an incorrect usage string that combined the 'list' usage of git branch (-l) with the 'create' usage; this string has been incorrect since its inception, a8dfd5eac4 (Make builtin-branch.c use parse_options., 2007-10-07). Helped-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Glen Choo <chooglen@google.com> Reviewed-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-03doc: check-ignore: code-quote an exclamation markLibravatar Philip Oakley1-2/+2
The plain quoted exclamation mark renders as italics in the Windows pdf help manual. Fix this with back-tick quoting and surrounding double quotes as exemplified by the gitignore.txt guide. While at it, fix the surrounding double quotes for the other special characters usages. Signed-off-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-02fix typo in git-mktree.txtLibravatar Liginity Lee1-1/+1
fix a typo: change "as" to "a". Signed-off-by: Liginity Lee <liginity@outlook.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-02show, log: provide a --remerge-diff capabilityLibravatar Elijah Newren1-1/+13
When this option is specified, we remerge all (two parent) merge commits and diff the actual merge commit to the automatically created version, in order to show how users removed conflict markers, resolved the different conflict versions, and potentially added new changes outside of conflict regions in order to resolve semantic merge problems (or, possibly, just to hide other random changes). This capability works by creating a temporary object directory and marking it as the primary object store. This makes it so that any blobs or trees created during the automatic merge are easily removable afterwards by just deleting all objects from the temporary object directory. There are a few ways that this implementation is suboptimal: * `log --remerge-diff` becomes slow, because the temporary object directory can fill with many loose objects while running * the log output can be muddied with misplaced "warning: cannot merge binary files" messages, since ll-merge.c unconditionally writes those messages to stderr while running instead of allowing callers to manage them. * important conflict and warning messages are simply dropped; thus for conflicts like modify/delete or rename/rename or file/directory which are not representable with content conflict markers, there may be no way for a user of --remerge-diff to know that there had been a conflict which was resolved (and which possibly motivated other changes in the merge commit). * when fixing the previous issue, note that some unimportant conflict and warning messages might start being included. We should instead make sure these remain dropped. Subsequent commits will address these issues. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-02repo-settings: rename the traditional default fetch.negotiationAlgorithmLibravatar Elijah Newren1-12/+13
Give the traditional default fetch.negotiationAlgorithm the name 'consecutive'. Also allow a choice of 'default' to have Git decide between the choices (currently, picking 'skipping' if feature.experimental is true and 'consecutive' otherwise). Update the documentation accordingly. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-31Merge branch 'js/branch-track-inherit' into gc/branch-recurse-submodulesLibravatar Junio C Hamano4-10/+21
* js/branch-track-inherit: branch,checkout: fix --track documentation branch,checkout: fix --track usage strings config: require lowercase for branch.*.autosetupmerge branch: add flags and config to inherit tracking branch: accept multiple upstream branches for tracking
2022-01-28Sync with Git 2.35.1Libravatar Junio C Hamano1-0/+6
2022-01-28Name the next one 2.36 to prepare for 2.35.1Libravatar Junio C Hamano1-0/+34
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-28Git 2.35.1Libravatar Junio C Hamano1-0/+6
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-28docs(diff): lose incorrect claim about `diff-files --diff-filter=A`Libravatar Johannes Schindelin1-5/+2
Originally, before we had `--intent-to-add`, there was no way that `git diff-files` could see added files: if a file did not exist in the index, `git diff-files` would not show it because it looks only at worktree files when there is an index entry at the same path. We used this example in the documentation of the diff options to explain that not every `--diff-filter=<option>` has an effect in all scenarios. Even when we added `--intent-to-add`, the comment was still correct, because initially we showed such files as modified instead of added. However, when that bug was fixed in feea6946a5b (diff-files: treat "i-t-a" files as "not-in-index", 2020-06-20), the comment in the documentation became incorrect. Let's just remove it. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-27stash: remove documentation for `stash.useBuiltin`Libravatar Johannes Schindelin1-7/+0
In 8a2cd3f5123 (stash: remove the stash.useBuiltin setting, 2020-03-03), we removed the setting, and for a couple of major versions, we still documented the setting, telling users that it is gone. We can now safely remove even the documentation. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-27SubmittingPatches: explain why we care about log messagesLibravatar Junio C Hamano1-0/+29
Extend the "describe your changes well" section to cover whom we are trying to help by doing so in the first place. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-27CodingGuidelines: hint why we value clearly written log messagesLibravatar Junio C Hamano1-0/+7
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-27SubmittingPatches: write problem statement in the log in the present tenseLibravatar Junio C Hamano1-0/+7
We give a guidance for proposed log message to write problem statement first, followed by the reasoning behind, and recipe for, the solution. Clarify that we describe the situation _before_ the proposed patch is applied in the present tense (not in the past tense e.g. "we used to do X, but thanks to this commit we now do Y") for consistency. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-01-27midx.c: make changing the preferred pack safeLibravatar Taylor Blau2-6/+8
The previous patch demonstrates a bug where a MIDX's auxiliary object order can become out of sync with a MIDX bitmap. This is because of two confounding factors: - First, the object order is stored in a file which is named according to the multi-pack index's checksum, and the MIDX does not store the object order. This means that the object order can change without altering the checksum. - But the .rev file is moved into place with finalize_object_file(), which link(2)'s the file into place instead of renaming it. For us, that means that a modified .rev file will not be moved into place if MIDX's checksum was unchanged. This fix is to force the MIDX's checksum to change when the preferred pack changes but the set of packs contained in the MIDX does not. In other words, when the object order changes, the MIDX's checksum needs to change with it (regardless of whether the MIDX is tracking the same or different packs). This prevents a race whereby changing the object order (but not the packs themselves) enables a reader to see the new .rev file with the old MIDX, or similarly seeing the new bitmap with the old object order. But why can't we just stop hardlinking the .rev into place instead adding additional data to the MIDX? Suppose that's what we did. Then when we go to generate the new bitmap, we'll load the old MIDX bitmap, along with the MIDX that it references. That's fine, since the new MIDX isn't moved into place until after the new bitmap is generated. But the new object order *has* been moved into place. So we'll read the old bitmaps in the new order when generating the new bitmap file, meaning that without this secondary change, bitmap generation itself would become a victim of the race described here. This can all be prevented by forcing the MIDX's checksum to change when the object order does. By embedding the entire object order into the MIDX, we do just that. That is, the MIDX's checksum will change in response to any perturbation of the underlying object order. In t5326, this will cause the MIDX's checksum to update (even without changing the set of packs in the MIDX), preventing the stale read problem. Note that this makes it safe to continue to link(2) the MIDX .rev file into place, since it is now impossible to have a .rev file that is out-of-sync with the MIDX whose checksum it references. (But we will do away with MIDX .rev files later in this series anyway, so this is somewhat of a moot point). In theory, it is possible to store a "fingerprint" of the full object order here, so long as that fingerprint changes at least as often as the full object order does. Some possibilities here include storing the identity of the preferred pack, along with the mtimes of the non-preferred packs in a consistent order. But storing a limited part of the information makes it difficult to reason about whether or not there are gaps between the two that would cause us to get bitten by this bug again. Signed-off-by: Taylor Blau <me@ttaylorr.com> Reviewed-by: Derrick Stolee <dstolee@microsoft.com> Reviewed-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>