From d09d33db2e61405c02a0bdf4b7c07eb296623a2c Mon Sep 17 00:00:00 2001 From: ttaylorr Date: Tue, 24 Sep 2024 17:42:49 +0000 Subject: [PATCH] Update manual pages (2.46.2) Updated via the `update-git-version-and-manual-pages.yml` GitHub workflow. --- .../35a8f8e1fb14cdf92baf4490ae1127a37dcf3bb9 | 480 + .../8ce83a5e94562ab0e73c88ef4afd41ae6d2296a7 | 328 + .../a13f478d7cb3fc25a95f0e14cff73cd5203e4b57 | 1131 +++ .../b6eb1ed05504fc766aabc581c310057c6a46f010 | 7022 +++++++++++++ .../d470969260e7a605742fb34733463f6434be4872 | 1318 +++ .../docs/MyFirstContribution/2.46.0.html | 1 + .../docs/MyFirstObjectWalk/2.45.0.html | 1 + .../docs/SubmittingPatches/2.46.0.html | 1 + .../docs/api-error-handling/2.37.0.html | 1 + .../content/docs/api-index-skel/2.43.0.html | 1 + .../docs/content/docs/api-merge/2.42.0.html | 1 + .../docs/api-parse-options/2.38.0.html | 1 + .../content/docs/api-simple-ipc/2.43.0.html | 1 + .../docs/content/docs/api-trace2/2.44.0.html | 1 + .../content/docs/bitmap-format/2.46.0.html | 1 + .../docs/content/docs/bundle-uri/2.40.0.html | 1 + .../content/docs/commit-graph/2.43.0.html | 1 + .../docs/content/docs/diff-format/2.43.0.html | 1 + .../docs/diff-generate-patch/2.43.0.html | 1 + .../content/docs/diff-options/2.46.0.html | 1 + .../directory-rename-detection/2.33.1.html | 1 + external/docs/content/docs/fetch-options.html | 9 +- .../content/docs/fetch-options/2.46.2.html | 378 + .../docs/content/docs/git-add/2.46.0.html | 1 + external/docs/content/docs/git-am/2.46.0.html | 1 + .../content/docs/git-annotate/2.41.0.html | 1 + .../docs/content/docs/git-apply/2.43.0.html | 1 + .../content/docs/git-archimport/2.35.0.html | 1 + .../docs/content/docs/git-archive/2.46.0.html | 1 + .../docs/git-bisect-lk2009/2.40.0.html | 1 + .../docs/content/docs/git-bisect/2.44.0.html | 1 + .../docs/content/docs/git-blame/2.44.0.html | 1 + .../docs/content/docs/git-branch/2.44.0.html | 1 + .../content/docs/git-bugreport/2.45.0.html | 1 + .../docs/content/docs/git-bundle/2.41.0.html | 1 + .../content/docs/git-cat-file/2.46.1.html | 1 + .../content/docs/git-check-attr/2.43.0.html | 1 + .../content/docs/git-check-ignore/2.43.0.html | 1 + .../docs/git-check-mailmap/2.31.0.html | 1 + .../docs/git-check-ref-format/2.43.0.html | 1 + .../docs/git-checkout-index/2.43.0.html | 1 + .../content/docs/git-checkout/2.44.0.html | 1 + .../content/docs/git-cherry-pick/2.45.0.html | 1 + .../docs/content/docs/git-cherry/2.0.5.html | 1 + .../docs/content/docs/git-citool/2.0.5.html | 1 + .../docs/content/docs/git-clean/2.45.0.html | 1 + .../docs/content/docs/git-clone/2.46.0.html | 1 + .../docs/content/docs/git-column/2.43.0.html | 1 + .../content/docs/git-commit-graph/2.46.0.html | 1 + .../content/docs/git-commit-tree/2.45.0.html | 1 + .../docs/content/docs/git-commit/2.46.1.html | 1 + external/docs/content/docs/git-config.html | 17 +- .../docs/content/docs/git-config/2.46.2.html | 8705 +++++++++++++++++ .../docs/git-count-objects/2.43.0.html | 1 + .../git-credential-cache--daemon/2.39.0.html | 1 + .../docs/git-credential-cache/2.43.0.html | 1 + .../docs/git-credential-store/2.43.0.html | 1 + .../content/docs/git-credential/2.46.0.html | 1 + .../docs/git-cvsexportcommit/2.35.0.html | 1 + .../content/docs/git-cvsimport/2.43.1.html | 1 + .../content/docs/git-cvsserver/2.44.0.html | 1 + .../docs/content/docs/git-daemon/2.44.0.html | 1 + .../content/docs/git-describe/2.42.0.html | 1 + .../content/docs/git-diagnose/2.44.0.html | 1 + .../content/docs/git-diff-files/2.46.0.html | 1 + .../content/docs/git-diff-index/2.46.0.html | 1 + .../content/docs/git-diff-tree/2.46.1.html | 1 + .../docs/content/docs/git-diff/2.46.0.html | 1 + .../content/docs/git-difftool/2.45.0.html | 1 + .../content/docs/git-fast-export/2.45.0.html | 1 + .../content/docs/git-fast-import/2.45.0.html | 1 + .../content/docs/git-fetch-pack/2.43.0.html | 1 + external/docs/content/docs/git-fetch.html | 9 +- .../docs/content/docs/git-fetch/2.46.2.html | 1385 +++ .../docs/git-filter-branch/2.44.0.html | 1 + .../docs/git-fmt-merge-msg/2.35.0.html | 1 + .../content/docs/git-for-each-ref/2.45.0.html | 1 + .../docs/git-for-each-repo/2.46.0.html | 1 + .../content/docs/git-format-patch/2.46.0.html | 1 + .../content/docs/git-fsck-objects/2.0.5.html | 1 + .../docs/content/docs/git-fsck/2.45.2.html | 1 + .../docs/git-fsmonitor--daemon/2.43.0.html | 1 + external/docs/content/docs/git-gc/2.43.0.html | 1 + .../docs/git-get-tar-commit-id/2.43.0.html | 1 + .../docs/content/docs/git-grep/2.45.0.html | 1 + .../docs/content/docs/git-gui/2.46.0.html | 1 + .../content/docs/git-hash-object/2.43.0.html | 1 + .../docs/content/docs/git-help/2.43.0.html | 1 + .../docs/content/docs/git-hook/2.43.0.html | 1 + .../content/docs/git-http-backend/2.43.0.html | 1 + .../content/docs/git-http-fetch/2.43.0.html | 1 + .../content/docs/git-http-push/2.43.0.html | 1 + .../content/docs/git-imap-send/2.43.1.html | 1 + .../content/docs/git-index-pack/2.44.0.html | 1 + .../docs/content/docs/git-init-db/2.35.0.html | 1 + .../docs/content/docs/git-init/2.45.0.html | 1 + .../content/docs/git-instaweb/2.21.0.html | 1 + .../docs/git-interpret-trailers/2.45.0.html | 1 + .../docs/content/docs/git-log/2.46.0.html | 1 + .../content/docs/git-ls-files/2.46.1.html | 1 + .../content/docs/git-ls-remote/2.46.0.html | 1 + .../docs/content/docs/git-ls-tree/2.42.0.html | 1 + .../content/docs/git-mailinfo/2.43.0.html | 1 + .../content/docs/git-mailsplit/2.43.0.html | 1 + .../docs/content/docs/git-maintenance.html | 8 +- .../content/docs/git-maintenance/2.46.2.html | 617 ++ .../content/docs/git-merge-base/2.43.0.html | 1 + .../content/docs/git-merge-file/2.44.0.html | 1 + .../content/docs/git-merge-index/2.35.0.html | 1 + .../docs/git-merge-one-file/2.0.5.html | 1 + .../content/docs/git-merge-tree/2.46.0.html | 1 + .../docs/content/docs/git-merge/2.43.1.html | 1 + .../docs/git-mergetool--lib/2.43.0.html | 1 + .../content/docs/git-mergetool/2.45.0.html | 1 + .../docs/content/docs/git-mktag/2.43.0.html | 1 + .../docs/content/docs/git-mktree/2.43.0.html | 1 + .../docs/git-multi-pack-index/2.38.2.html | 1 + external/docs/content/docs/git-mv/2.44.0.html | 1 + .../content/docs/git-name-rev/2.43.0.html | 1 + .../docs/content/docs/git-notes/2.44.0.html | 1 + external/docs/content/docs/git-p4/2.37.0.html | 1 + .../content/docs/git-pack-objects/2.43.0.html | 1 + .../docs/git-pack-redundant/2.41.0.html | 1 + .../content/docs/git-pack-refs/2.45.0.html | 1 + .../content/docs/git-patch-id/2.39.0.html | 1 + .../content/docs/git-prune-packed/2.43.0.html | 1 + .../docs/content/docs/git-prune/2.43.0.html | 1 + external/docs/content/docs/git-pull.html | 9 +- .../docs/content/docs/git-pull/2.46.2.html | 1440 +++ .../docs/content/docs/git-push/2.45.0.html | 1 + .../content/docs/git-quiltimport/2.43.0.html | 1 + .../content/docs/git-range-diff/2.43.0.html | 1 + .../content/docs/git-read-tree/2.43.0.html | 1 + .../docs/content/docs/git-rebase/2.46.1.html | 1 + .../content/docs/git-receive-pack/2.43.0.html | 1 + .../docs/content/docs/git-reflog/2.45.0.html | 1 + .../docs/content/docs/git-refs/2.46.0.html | 1 + .../content/docs/git-remote-ext/2.43.0.html | 1 + .../content/docs/git-remote-fd/2.43.0.html | 1 + .../docs/content/docs/git-remote/2.45.0.html | 1 + .../docs/content/docs/git-repack/2.43.0.html | 1 + .../docs/content/docs/git-replace/2.44.0.html | 1 + .../docs/content/docs/git-replay/2.45.0.html | 1 + .../content/docs/git-request-pull/2.43.0.html | 1 + .../docs/content/docs/git-rerere/2.39.0.html | 1 + .../docs/content/docs/git-reset/2.39.3.html | 1 + .../docs/content/docs/git-restore/2.43.0.html | 1 + .../content/docs/git-rev-list/2.45.0.html | 1 + .../content/docs/git-rev-parse/2.46.0.html | 1 + .../docs/content/docs/git-revert/2.44.0.html | 1 + external/docs/content/docs/git-rm/2.43.0.html | 1 + .../content/docs/git-send-email/2.45.0.html | 1 + .../content/docs/git-send-pack/2.43.0.html | 1 + .../docs/git-sh-i18n--envsubst/2.0.5.html | 1 + .../docs/content/docs/git-sh-i18n/2.0.5.html | 1 + .../content/docs/git-sh-setup/2.43.0.html | 1 + .../docs/content/docs/git-shell/2.18.0.html | 1 + .../content/docs/git-shortlog/2.45.0.html | 1 + .../content/docs/git-show-branch/2.46.0.html | 1 + .../content/docs/git-show-index/2.42.0.html | 1 + .../content/docs/git-show-ref/2.46.0.html | 1 + .../docs/content/docs/git-show/2.46.0.html | 1 + .../docs/git-sparse-checkout/2.42.0.html | 1 + .../docs/content/docs/git-stage/2.35.0.html | 1 + .../docs/content/docs/git-stash/2.43.0.html | 1 + .../docs/content/docs/git-status/2.45.0.html | 1 + .../content/docs/git-stripspace/2.43.0.html | 1 + .../content/docs/git-submodule/2.44.0.html | 1 + .../docs/content/docs/git-svn/2.44.0.html | 1 + .../docs/content/docs/git-switch/2.44.0.html | 1 + .../content/docs/git-symbolic-ref/2.43.0.html | 1 + .../docs/content/docs/git-tag/2.46.0.html | 1 + .../docs/content/docs/git-tools/2.13.7.html | 1 + .../content/docs/git-unpack-file/2.0.5.html | 1 + .../docs/git-unpack-objects/2.11.4.html | 1 + .../content/docs/git-update-index/2.46.0.html | 1 + .../content/docs/git-update-ref/2.46.0.html | 1 + .../docs/git-update-server-info/2.43.0.html | 1 + .../docs/git-upload-archive/2.39.0.html | 1 + .../content/docs/git-upload-pack/2.45.1.html | 1 + .../docs/content/docs/git-var/2.43.0.html | 1 + .../docs/git-verify-commit/2.39.0.html | 1 + .../content/docs/git-verify-pack/2.43.0.html | 1 + .../content/docs/git-verify-tag/2.39.0.html | 1 + .../docs/content/docs/git-version/2.33.1.html | 1 + .../content/docs/git-web--browse/2.35.0.html | 1 + .../content/docs/git-whatchanged/2.43.0.html | 1 + .../content/docs/git-worktree/2.43.1.html | 1 + .../content/docs/git-write-tree/2.0.5.html | 1 + external/docs/content/docs/git/2.46.0.html | 1 + .../content/docs/gitattributes/2.46.0.html | 1 + external/docs/content/docs/gitcli/2.45.0.html | 1 + .../content/docs/gitcore-tutorial/2.43.1.html | 1 + .../content/docs/gitcredentials/2.42.0.html | 1 + .../content/docs/gitcvs-migration/2.12.5.html | 1 + .../docs/content/docs/gitdiffcore/2.44.0.html | 1 + .../docs/content/docs/giteveryday/2.43.0.html | 1 + external/docs/content/docs/gitfaq/2.46.0.html | 1 + .../content/docs/gitformat-bundle/2.43.0.html | 1 + .../content/docs/gitformat-chunk/2.43.0.html | 1 + .../docs/gitformat-commit-graph/2.46.0.html | 1 + .../content/docs/gitformat-index/2.44.0.html | 1 + .../content/docs/gitformat-pack/2.44.0.html | 1 + .../docs/gitformat-signature/2.40.0.html | 1 + .../docs/content/docs/gitglossary/2.46.0.html | 1 + .../docs/content/docs/githooks/2.46.1.html | 1 + .../docs/content/docs/gitignore/2.42.0.html | 1 + external/docs/content/docs/gitk/2.44.0.html | 1 + .../docs/content/docs/gitmailmap/2.32.0.html | 1 + .../docs/content/docs/gitmodules/2.42.0.html | 1 + .../content/docs/gitnamespaces/2.32.0.html | 1 + .../docs/content/docs/gitpacking/2.46.0.html | 1 + .../docs/gitprotocol-capabilities/2.44.0.html | 1 + .../docs/gitprotocol-common/2.43.0.html | 1 + .../content/docs/gitprotocol-http/2.44.0.html | 1 + .../content/docs/gitprotocol-pack/2.43.0.html | 1 + .../content/docs/gitprotocol-v2/2.45.0.html | 1 + .../docs/gitremote-helpers/2.45.0.html | 1 + .../docs/gitrepository-layout/2.45.0.html | 1 + .../content/docs/gitrevisions/2.42.0.html | 1 + .../content/docs/gitsubmodules/2.44.0.html | 1 + .../content/docs/gittutorial-2/2.23.0.html | 1 + .../docs/content/docs/gittutorial/2.46.1.html | 1 + .../docs/content/docs/gitweb.conf/2.44.0.html | 1 + external/docs/content/docs/gitweb/2.44.0.html | 1 + .../content/docs/gitworkflows/2.35.0.html | 1 + .../docs/hash-function-transition/2.40.0.html | 1 + .../long-running-process-protocol/2.38.0.html | 1 + .../content/docs/merge-options/2.43.1.html | 1 + .../content/docs/merge-strategies/2.34.0.html | 1 + .../content/docs/multi-pack-index/2.36.0.html | 1 + .../content/docs/pack-heuristics/2.0.5.html | 1 + .../content/docs/packfile-uri/2.38.0.html | 1 + .../docs/parallel-checkout/2.43.0.html | 1 + .../content/docs/partial-clone/2.43.0.html | 1 + .../content/docs/pretty-formats/2.45.0.html | 1 + .../content/docs/pretty-options/2.43.0.html | 1 + .../content/docs/pull-fetch-param/2.43.0.html | 1 + .../docs/content/docs/racy-git/2.43.0.html | 1 + .../docs/content/docs/reftable/2.43.0.html | 1 + .../docs/remembering-renames/2.42.0.html | 1 + .../docs/repository-version/2.45.0.html | 1 + external/docs/content/docs/rerere/2.43.0.html | 1 + .../docs/rev-list-description/2.29.0.html | 1 + .../content/docs/rev-list-options/2.45.0.html | 1 + .../docs/content/docs/revisions/2.42.0.html | 1 + external/docs/content/docs/scalar/2.42.1.html | 1 + .../docs/send-pack-pipeline/2.0.5.html | 1 + .../docs/content/docs/shallow/2.29.0.html | 1 + .../content/docs/sparse-checkout/2.39.0.html | 1 + .../content/docs/sparse-index/2.32.0.html | 1 + .../content/docs/trivial-merge/2.15.4.html | 1 + .../docs/content/docs/unit-tests/2.44.0.html | 1 + .../docs/content/docs/user-manual/2.46.0.html | 1 + .../docs/content/docs/vimdiff/2.45.0.html | 1 + external/docs/data/docs.yml | 770 +- 256 files changed, 23605 insertions(+), 261 deletions(-) create mode 100644 external/docs/asciidoc/35a8f8e1fb14cdf92baf4490ae1127a37dcf3bb9 create mode 100644 external/docs/asciidoc/8ce83a5e94562ab0e73c88ef4afd41ae6d2296a7 create mode 100644 external/docs/asciidoc/a13f478d7cb3fc25a95f0e14cff73cd5203e4b57 create mode 100644 external/docs/asciidoc/b6eb1ed05504fc766aabc581c310057c6a46f010 create mode 100644 external/docs/asciidoc/d470969260e7a605742fb34733463f6434be4872 create mode 100644 external/docs/content/docs/fetch-options/2.46.2.html create mode 100644 external/docs/content/docs/git-config/2.46.2.html create mode 100644 external/docs/content/docs/git-fetch/2.46.2.html create mode 100644 external/docs/content/docs/git-maintenance/2.46.2.html create mode 100644 external/docs/content/docs/git-pull/2.46.2.html diff --git a/external/docs/asciidoc/35a8f8e1fb14cdf92baf4490ae1127a37dcf3bb9 b/external/docs/asciidoc/35a8f8e1fb14cdf92baf4490ae1127a37dcf3bb9 new file mode 100644 index 0000000000..f3b44b5110 --- /dev/null +++ b/external/docs/asciidoc/35a8f8e1fb14cdf92baf4490ae1127a37dcf3bb9 @@ -0,0 +1,480 @@ +git-maintenance(1) +================== + +NAME +---- +git-maintenance - Run tasks to optimize Git repository data + + +SYNOPSIS +-------- +[verse] +'git maintenance' run [] +'git maintenance' start [--scheduler=] +'git maintenance' (stop|register|unregister) [] + + +DESCRIPTION +----------- +Run tasks to optimize Git repository data, speeding up other Git commands +and reducing storage requirements for the repository. + +Git commands that add repository data, such as `git add` or `git fetch`, +are optimized for a responsive user experience. These commands do not take +time to optimize the Git data, since such optimizations scale with the full +size of the repository while these user commands each perform a relatively +small action. + +The `git maintenance` command provides flexibility for how to optimize the +Git repository. + +SUBCOMMANDS +----------- + +run:: + Run one or more maintenance tasks. If one or more `--task` options + are specified, then those tasks are run in that order. Otherwise, + the tasks are determined by which `maintenance..enabled` + config options are true. By default, only `maintenance.gc.enabled` + is true. + +start:: + Start running maintenance on the current repository. This performs + the same config updates as the `register` subcommand, then updates + the background scheduler to run `git maintenance run --scheduled` + on an hourly basis. + +stop:: + Halt the background maintenance schedule. The current repository + is not removed from the list of maintained repositories, in case + the background maintenance is restarted later. + +register:: + Initialize Git config values so any scheduled maintenance will start + running on this repository. This adds the repository to the + `maintenance.repo` config variable in the current user's global config, + or the config specified by --config-file option, and enables some + recommended configuration values for `maintenance..schedule`. The + tasks that are enabled are safe for running in the background without + disrupting foreground processes. ++ +The `register` subcommand will also set the `maintenance.strategy` config +value to `incremental`, if this value is not previously set. The +`incremental` strategy uses the following schedule for each maintenance +task: ++ +-- +* `gc`: disabled. +* `commit-graph`: hourly. +* `prefetch`: hourly. +* `loose-objects`: daily. +* `incremental-repack`: daily. +-- ++ +`git maintenance register` will also disable foreground maintenance by +setting `maintenance.auto = false` in the current repository. This config +setting will remain after a `git maintenance unregister` command. + +unregister:: + Remove the current repository from background maintenance. This + only removes the repository from the configured list. It does not + stop the background maintenance processes from running. ++ +The `unregister` subcommand will report an error if the current repository +is not already registered. Use the `--force` option to return success even +when the current repository is not registered. + +TASKS +----- + +commit-graph:: + The `commit-graph` job updates the `commit-graph` files incrementally, + then verifies that the written data is correct. The incremental + write is safe to run alongside concurrent Git processes since it + will not expire `.graph` files that were in the previous + `commit-graph-chain` file. They will be deleted by a later run based + on the expiration delay. + +prefetch:: + The `prefetch` task updates the object directory with the latest + objects from all registered remotes. For each remote, a `git fetch` + command is run. The configured refspec is modified to place all + requested refs within `refs/prefetch/`. Also, tags are not updated. ++ +This is done to avoid disrupting the remote-tracking branches. The end users +expect these refs to stay unmoved unless they initiate a fetch. However, +with the prefetch task, the objects necessary to complete a later real fetch +would already be obtained, making the real fetch faster. In the ideal case, +it will just become an update to a bunch of remote-tracking branches without +any object transfer. ++ +The `remote..skipFetchAll` configuration can be used to +exclude a particular remote from getting prefetched. + +gc:: + Clean up unnecessary files and optimize the local repository. "GC" + stands for "garbage collection," but this task performs many + smaller tasks. This task can be expensive for large repositories, + as it repacks all Git objects into a single pack-file. It can also + be disruptive in some situations, as it deletes stale data. See + linkgit:git-gc[1] for more details on garbage collection in Git. + +loose-objects:: + The `loose-objects` job cleans up loose objects and places them into + pack-files. In order to prevent race conditions with concurrent Git + commands, it follows a two-step process. First, it deletes any loose + objects that already exist in a pack-file; concurrent Git processes + will examine the pack-file for the object data instead of the loose + object. Second, it creates a new pack-file (starting with "loose-") + containing a batch of loose objects. The batch size is limited to 50 + thousand objects to prevent the job from taking too long on a + repository with many loose objects. The `gc` task writes unreachable + objects as loose objects to be cleaned up by a later step only if + they are not re-added to a pack-file; for this reason it is not + advisable to enable both the `loose-objects` and `gc` tasks at the + same time. + +incremental-repack:: + The `incremental-repack` job repacks the object directory + using the `multi-pack-index` feature. In order to prevent race + conditions with concurrent Git commands, it follows a two-step + process. First, it calls `git multi-pack-index expire` to delete + pack-files unreferenced by the `multi-pack-index` file. Second, it + calls `git multi-pack-index repack` to select several small + pack-files and repack them into a bigger one, and then update the + `multi-pack-index` entries that refer to the small pack-files to + refer to the new pack-file. This prepares those small pack-files + for deletion upon the next run of `git multi-pack-index expire`. + The selection of the small pack-files is such that the expected + size of the big pack-file is at least the batch size; see the + `--batch-size` option for the `repack` subcommand in + linkgit:git-multi-pack-index[1]. The default batch-size is zero, + which is a special case that attempts to repack all pack-files + into a single pack-file. + +pack-refs:: + The `pack-refs` task collects the loose reference files and + collects them into a single file. This speeds up operations that + need to iterate across many references. See linkgit:git-pack-refs[1] + for more information. + +OPTIONS +------- +--auto:: + When combined with the `run` subcommand, run maintenance tasks + only if certain thresholds are met. For example, the `gc` task + runs when the number of loose objects exceeds the number stored + in the `gc.auto` config setting, or when the number of pack-files + exceeds the `gc.autoPackLimit` config setting. Not compatible with + the `--schedule` option. + +--schedule:: + When combined with the `run` subcommand, run maintenance tasks + only if certain time conditions are met, as specified by the + `maintenance..schedule` config value for each ``. + This config value specifies a number of seconds since the last + time that task ran, according to the `maintenance..lastRun` + config value. The tasks that are tested are those provided by + the `--task=` option(s) or those with + `maintenance..enabled` set to true. + +--quiet:: + Do not report progress or other information over `stderr`. + +--task=:: + If this option is specified one or more times, then only run the + specified tasks in the specified order. If no `--task=` + arguments are specified, then only the tasks with + `maintenance..enabled` configured as `true` are considered. + See the 'TASKS' section for the list of accepted `` values. + +--scheduler=auto|crontab|systemd-timer|launchctl|schtasks:: + When combined with the `start` subcommand, specify the scheduler + for running the hourly, daily and weekly executions of + `git maintenance run`. + Possible values for `` are `auto`, `crontab` + (POSIX), `systemd-timer` (Linux), `launchctl` (macOS), and + `schtasks` (Windows). When `auto` is specified, the + appropriate platform-specific scheduler is used; on Linux, + `systemd-timer` is used if available, otherwise + `crontab`. Default is `auto`. + + +TROUBLESHOOTING +--------------- +The `git maintenance` command is designed to simplify the repository +maintenance patterns while minimizing user wait time during Git commands. +A variety of configuration options are available to allow customizing this +process. The default maintenance options focus on operations that complete +quickly, even on large repositories. + +Users may find some cases where scheduled maintenance tasks do not run as +frequently as intended. Each `git maintenance run` command takes a lock on +the repository's object database, and this prevents other concurrent +`git maintenance run` commands from running on the same repository. Without +this safeguard, competing processes could leave the repository in an +unpredictable state. + +The background maintenance schedule runs `git maintenance run` processes +on an hourly basis. Each run executes the "hourly" tasks. At midnight, +that process also executes the "daily" tasks. At midnight on the first day +of the week, that process also executes the "weekly" tasks. A single +process iterates over each registered repository, performing the scheduled +tasks for that frequency. Depending on the number of registered +repositories and their sizes, this process may take longer than an hour. +In this case, multiple `git maintenance run` commands may run on the same +repository at the same time, colliding on the object database lock. This +results in one of the two tasks not running. + +If you find that some maintenance windows are taking longer than one hour +to complete, then consider reducing the complexity of your maintenance +tasks. For example, the `gc` task is much slower than the +`incremental-repack` task. However, this comes at a cost of a slightly +larger object database. Consider moving more expensive tasks to be run +less frequently. + +Expert users may consider scheduling their own maintenance tasks using a +different schedule than is available through `git maintenance start` and +Git configuration options. These users should be aware of the object +database lock and how concurrent `git maintenance run` commands behave. +Further, the `git gc` command should not be combined with +`git maintenance run` commands. `git gc` modifies the object database +but does not take the lock in the same way as `git maintenance run`. If +possible, use `git maintenance run --task=gc` instead of `git gc`. + +The following sections describe the mechanisms put in place to run +background maintenance by `git maintenance start` and how to customize +them. + +BACKGROUND MAINTENANCE ON POSIX SYSTEMS +--------------------------------------- + +The standard mechanism for scheduling background tasks on POSIX systems +is cron(8). This tool executes commands based on a given schedule. The +current list of user-scheduled tasks can be found by running `crontab -l`. +The schedule written by `git maintenance start` is similar to this: + +----------------------------------------------------------------------- +# BEGIN GIT MAINTENANCE SCHEDULE +# The following schedule was created by Git +# Any edits made in this region might be +# replaced in the future by a Git command. + +0 1-23 * * * "//git" --exec-path="/" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly +0 0 * * 1-6 "//git" --exec-path="/" for-each-repo --config=maintenance.repo maintenance run --schedule=daily +0 0 * * 0 "//git" --exec-path="/" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly + +# END GIT MAINTENANCE SCHEDULE +----------------------------------------------------------------------- + +The comments are used as a region to mark the schedule as written by Git. +Any modifications within this region will be completely deleted by +`git maintenance stop` or overwritten by `git maintenance start`. + +The `crontab` entry specifies the full path of the `git` executable to +ensure that the executed `git` command is the same one with which +`git maintenance start` was issued independent of `PATH`. If the same user +runs `git maintenance start` with multiple Git executables, then only the +latest executable is used. + +These commands use `git for-each-repo --config=maintenance.repo` to run +`git maintenance run --schedule=` on each repository listed in +the multi-valued `maintenance.repo` config option. These are typically +loaded from the user-specific global config. The `git maintenance` process +then determines which maintenance tasks are configured to run on each +repository with each `` using the `maintenance..schedule` +config options. These values are loaded from the global or repository +config values. + +If the config values are insufficient to achieve your desired background +maintenance schedule, then you can create your own schedule. If you run +`crontab -e`, then an editor will load with your user-specific `cron` +schedule. In that editor, you can add your own schedule lines. You could +start by adapting the default schedule listed earlier, or you could read +the crontab(5) documentation for advanced scheduling techniques. Please +do use the full path and `--exec-path` techniques from the default +schedule to ensure you are executing the correct binaries in your +schedule. + + +BACKGROUND MAINTENANCE ON LINUX SYSTEMD SYSTEMS +----------------------------------------------- + +While Linux supports `cron`, depending on the distribution, `cron` may +be an optional package not necessarily installed. On modern Linux +distributions, systemd timers are superseding it. + +If user systemd timers are available, they will be used as a replacement +of `cron`. + +In this case, `git maintenance start` will create user systemd timer units +and start the timers. The current list of user-scheduled tasks can be found +by running `systemctl --user list-timers`. The timers written by `git +maintenance start` are similar to this: + +----------------------------------------------------------------------- +$ systemctl --user list-timers +NEXT LEFT LAST PASSED UNIT ACTIVATES +Thu 2021-04-29 19:00:00 CEST 42min left Thu 2021-04-29 18:00:11 CEST 17min ago git-maintenance@hourly.timer git-maintenance@hourly.service +Fri 2021-04-30 00:00:00 CEST 5h 42min left Thu 2021-04-29 00:00:11 CEST 18h ago git-maintenance@daily.timer git-maintenance@daily.service +Mon 2021-05-03 00:00:00 CEST 3 days left Mon 2021-04-26 00:00:11 CEST 3 days ago git-maintenance@weekly.timer git-maintenance@weekly.service +----------------------------------------------------------------------- + +One timer is registered for each `--schedule=` option. + +The definition of the systemd units can be inspected in the following files: + +----------------------------------------------------------------------- +~/.config/systemd/user/git-maintenance@.timer +~/.config/systemd/user/git-maintenance@.service +~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer +~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer +~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer +----------------------------------------------------------------------- + +`git maintenance start` will overwrite these files and start the timer +again with `systemctl --user`, so any customization should be done by +creating a drop-in file, i.e. a `.conf` suffixed file in the +`~/.config/systemd/user/git-maintenance@.service.d` directory. + +`git maintenance stop` will stop the user systemd timers and delete +the above mentioned files. + +For more details, see `systemd.timer(5)`. + + +BACKGROUND MAINTENANCE ON MACOS SYSTEMS +--------------------------------------- + +While macOS technically supports `cron`, using `crontab -e` requires +elevated privileges and the executed process does not have a full user +context. Without a full user context, Git and its credential helpers +cannot access stored credentials, so some maintenance tasks are not +functional. + +Instead, `git maintenance start` interacts with the `launchctl` tool, +which is the recommended way to schedule timed jobs in macOS. Scheduling +maintenance through `git maintenance (start|stop)` requires some +`launchctl` features available only in macOS 10.11 or later. + +Your user-specific scheduled tasks are stored as XML-formatted `.plist` +files in `~/Library/LaunchAgents/`. You can see the currently-registered +tasks using the following command: + +----------------------------------------------------------------------- +$ ls ~/Library/LaunchAgents/org.git-scm.git* +org.git-scm.git.daily.plist +org.git-scm.git.hourly.plist +org.git-scm.git.weekly.plist +----------------------------------------------------------------------- + +One task is registered for each `--schedule=` option. To +inspect how the XML format describes each schedule, open one of these +`.plist` files in an editor and inspect the `` element following +the `StartCalendarInterval` element. + +`git maintenance start` will overwrite these files and register the +tasks again with `launchctl`, so any customizations should be done by +creating your own `.plist` files with distinct names. Similarly, the +`git maintenance stop` command will unregister the tasks with `launchctl` +and delete the `.plist` files. + +To create more advanced customizations to your background tasks, see +launchctl.plist(5) for more information. + + +BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS +----------------------------------------- + +Windows does not support `cron` and instead has its own system for +scheduling background tasks. The `git maintenance start` command uses +the `schtasks` command to submit tasks to this system. You can inspect +all background tasks using the Task Scheduler application. The tasks +added by Git have names of the form `Git Maintenance ()`. +The Task Scheduler GUI has ways to inspect these tasks, but you can also +export the tasks to XML files and view the details there. + +Note that since Git is a console application, these background tasks +create a console window visible to the current user. This can be changed +manually by selecting the "Run whether user is logged in or not" option +in Task Scheduler. This change requires a password input, which is why +`git maintenance start` does not select it by default. + +If you want to customize the background tasks, please rename the tasks +so future calls to `git maintenance (start|stop)` do not overwrite your +custom tasks. + +CONFIGURATION +------------- + +Everything below this line in this section is selectively included +from the linkgit:git-config[1] documentation. The content is the same +as what's found there: + + +maintenance.auto:: + This boolean config option controls whether some commands run + `git maintenance run --auto` after doing their normal work. Defaults + to true. + +maintenance.strategy:: + This string config option provides a way to specify one of a few + recommended schedules for background maintenance. This only affects + which tasks are run during `git maintenance run --schedule=X` + commands, provided no `--task=` arguments are provided. + Further, if a `maintenance..schedule` config value is set, + then that value is used instead of the one provided by + `maintenance.strategy`. The possible strategy strings are: ++ +* `none`: This default setting implies no tasks are run at any schedule. +* `incremental`: This setting optimizes for performing small maintenance + activities that do not delete any data. This does not schedule the `gc` + task, but runs the `prefetch` and `commit-graph` tasks hourly, the + `loose-objects` and `incremental-repack` tasks daily, and the `pack-refs` + task weekly. + +maintenance..enabled:: + This boolean config option controls whether the maintenance task + with name `` is run when no `--task` option is specified to + `git maintenance run`. These config values are ignored if a + `--task` option exists. By default, only `maintenance.gc.enabled` + is true. + +maintenance..schedule:: + This config option controls whether or not the given `` runs + during a `git maintenance run --schedule=` command. The + value must be one of "hourly", "daily", or "weekly". + +maintenance.commit-graph.auto:: + This integer config option controls how often the `commit-graph` task + should be run as part of `git maintenance run --auto`. If zero, then + the `commit-graph` task will not run with the `--auto` option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + reachable commits that are not in the commit-graph file is at least + the value of `maintenance.commit-graph.auto`. The default value is + 100. + +maintenance.loose-objects.auto:: + This integer config option controls how often the `loose-objects` task + should be run as part of `git maintenance run --auto`. If zero, then + the `loose-objects` task will not run with the `--auto` option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + loose objects is at least the value of `maintenance.loose-objects.auto`. + The default value is 100. + +maintenance.incremental-repack.auto:: + This integer config option controls how often the `incremental-repack` + task should be run as part of `git maintenance run --auto`. If zero, + then the `incremental-repack` task will not run with the `--auto` + option. A negative value will force the task to run every time. + Otherwise, a positive value implies the command should run when the + number of pack-files not in the multi-pack-index is at least the value + of `maintenance.incremental-repack.auto`. The default value is 10. + + + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/external/docs/asciidoc/8ce83a5e94562ab0e73c88ef4afd41ae6d2296a7 b/external/docs/asciidoc/8ce83a5e94562ab0e73c88ef4afd41ae6d2296a7 new file mode 100644 index 0000000000..80838fe37e --- /dev/null +++ b/external/docs/asciidoc/8ce83a5e94562ab0e73c88ef4afd41ae6d2296a7 @@ -0,0 +1,328 @@ +--[no-]all:: + Fetch all remotes, except for the ones that has the + `remote..skipFetchAll` configuration variable set. + This overrides the configuration variable fetch.all`. + +-a:: +--append:: + Append ref names and object names of fetched refs to the + existing contents of `.git/FETCH_HEAD`. Without this + option old data in `.git/FETCH_HEAD` will be overwritten. + +--atomic:: + Use an atomic transaction to update local refs. Either all refs are + updated, or on error, no refs are updated. + +--depth=:: + Limit fetching to the specified number of commits from the tip of + each remote branch history. If fetching to a 'shallow' repository + created by `git clone` with `--depth=` option (see + linkgit:git-clone[1]), deepen or shorten the history to the specified + number of commits. Tags for the deepened commits are not fetched. + +--deepen=:: + Similar to --depth, except it specifies the number of commits + from the current shallow boundary instead of from the tip of + each remote branch history. + +--shallow-since=:: + Deepen or shorten the history of a shallow repository to + include all reachable commits after . + +--shallow-exclude=:: + Deepen or shorten the history of a shallow repository to + exclude commits reachable from a specified remote branch or tag. + This option can be specified multiple times. + +--unshallow:: + If the source repository is complete, convert a shallow + repository to a complete one, removing all the limitations + imposed by shallow repositories. ++ +If the source repository is shallow, fetch as much as possible so that +the current repository has the same history as the source repository. + +--update-shallow:: + By default when fetching from a shallow repository, + `git fetch` refuses refs that require updating + .git/shallow. This option updates .git/shallow and accepts such + refs. + +--negotiation-tip=:: + By default, Git will report, to the server, commits reachable + from all local refs to find common commits in an attempt to + reduce the size of the to-be-received packfile. If specified, + Git will only report commits reachable from the given tips. + This is useful to speed up fetches when the user knows which + local ref is likely to have commits in common with the + upstream ref being fetched. ++ +This option may be specified more than once; if so, Git will report +commits reachable from any of the given commits. ++ +The argument to this option may be a glob on ref names, a ref, or the (possibly +abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying +this option multiple times, one for each matching ref name. ++ +See also the `fetch.negotiationAlgorithm` and `push.negotiate` +configuration variables documented in linkgit:git-config[1], and the +`--negotiate-only` option below. + +--negotiate-only:: + Do not fetch anything from the server, and instead print the + ancestors of the provided `--negotiation-tip=*` arguments, + which we have in common with the server. ++ +This is incompatible with `--recurse-submodules=[yes|on-demand]`. +Internally this is used to implement the `push.negotiate` option, see +linkgit:git-config[1]. + +--dry-run:: + Show what would be done, without making any changes. + +--porcelain:: + Print the output to standard output in an easy-to-parse format for + scripts. See section OUTPUT in linkgit:git-fetch[1] for details. ++ +This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes +precedence over the `fetch.output` config option. + +ifndef::git-pull[] +--[no-]write-fetch-head:: + Write the list of remote refs fetched in the `FETCH_HEAD` + file directly under `$GIT_DIR`. This is the default. + Passing `--no-write-fetch-head` from the command line tells + Git not to write the file. Under `--dry-run` option, the + file is never written. +endif::git-pull[] + +-f:: +--force:: + When 'git fetch' is used with `:` refspec, it may + refuse to update the local branch as discussed +ifdef::git-pull[] + in the `` part of the linkgit:git-fetch[1] + documentation. +endif::git-pull[] +ifndef::git-pull[] + in the `` part below. +endif::git-pull[] + This option overrides that check. + +-k:: +--keep:: + Keep downloaded pack. + +ifndef::git-pull[] +--multiple:: + Allow several and arguments to be + specified. No s may be specified. + +--[no-]auto-maintenance:: +--[no-]auto-gc:: + Run `git maintenance run --auto` at the end to perform automatic + repository maintenance if needed. (`--[no-]auto-gc` is a synonym.) + This is enabled by default. + +--[no-]write-commit-graph:: + Write a commit-graph after fetching. This overrides the config + setting `fetch.writeCommitGraph`. +endif::git-pull[] + +--prefetch:: + Modify the configured refspec to place all refs into the + `refs/prefetch/` namespace. See the `prefetch` task in + linkgit:git-maintenance[1]. + +-p:: +--prune:: + Before fetching, remove any remote-tracking references that no + longer exist on the remote. Tags are not subject to pruning + if they are fetched only because of the default tag + auto-following or due to a --tags option. However, if tags + are fetched due to an explicit refspec (either on the command + line or in the remote configuration, for example if the remote + was cloned with the --mirror option), then they are also + subject to pruning. Supplying `--prune-tags` is a shorthand for + providing the tag refspec. +ifndef::git-pull[] ++ +See the PRUNING section below for more details. + +-P:: +--prune-tags:: + Before fetching, remove any local tags that no longer exist on + the remote if `--prune` is enabled. This option should be used + more carefully, unlike `--prune` it will remove any local + references (local tags) that have been created. This option is + a shorthand for providing the explicit tag refspec along with + `--prune`, see the discussion about that in its documentation. ++ +See the PRUNING section below for more details. + +endif::git-pull[] + +ifndef::git-pull[] +-n:: +endif::git-pull[] +--no-tags:: + By default, tags that point at objects that are downloaded + from the remote repository are fetched and stored locally. + This option disables this automatic tag following. The default + behavior for a remote may be specified with the remote..tagOpt + setting. See linkgit:git-config[1]. + +ifndef::git-pull[] +--refetch:: + Instead of negotiating with the server to avoid transferring commits and + associated objects that are already present locally, this option fetches + all objects as a fresh clone would. Use this to reapply a partial clone + filter from configuration or using `--filter=` when the filter + definition has changed. Automatic post-fetch maintenance will perform + object database pack consolidation to remove any duplicate objects. +endif::git-pull[] + +--refmap=:: + When fetching refs listed on the command line, use the + specified refspec (can be given more than once) to map the + refs to remote-tracking branches, instead of the values of + `remote.*.fetch` configuration variables for the remote + repository. Providing an empty `` to the + `--refmap` option causes Git to ignore the configured + refspecs and rely entirely on the refspecs supplied as + command-line arguments. See section on "Configured Remote-tracking + Branches" for details. + +-t:: +--tags:: + Fetch all tags from the remote (i.e., fetch remote tags + `refs/tags/*` into local tags with the same name), in addition + to whatever else would otherwise be fetched. Using this + option alone does not subject tags to pruning, even if --prune + is used (though tags may be pruned anyway if they are also the + destination of an explicit refspec; see `--prune`). + +ifndef::git-pull[] +--recurse-submodules[=(yes|on-demand|no)]:: + This option controls if and under what conditions new commits of + submodules should be fetched too. When recursing through submodules, + `git fetch` always attempts to fetch "changed" submodules, that is, a + submodule that has commits that are referenced by a newly fetched + superproject commit but are missing in the local submodule clone. A + changed submodule can be fetched as long as it is present locally e.g. + in `$GIT_DIR/modules/` (see linkgit:gitsubmodules[7]); if the upstream + adds a new submodule, that submodule cannot be fetched until it is + cloned e.g. by `git submodule update`. ++ +When set to 'on-demand', only changed submodules are fetched. When set +to 'yes', all populated submodules are fetched and submodules that are +both unpopulated and changed are fetched. When set to 'no', submodules +are never fetched. ++ +When unspecified, this uses the value of `fetch.recurseSubmodules` if it +is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset. +When this option is used without any value, it defaults to 'yes'. +endif::git-pull[] + +-j:: +--jobs=:: + Number of parallel children to be used for all forms of fetching. ++ +If the `--multiple` option was specified, the different remotes will be fetched +in parallel. If multiple submodules are fetched, they will be fetched in +parallel. To control them independently, use the config settings +`fetch.parallel` and `submodule.fetchJobs` (see linkgit:git-config[1]). ++ +Typically, parallel recursive and multi-remote fetches will be faster. By +default fetches are performed sequentially, not in parallel. + +ifndef::git-pull[] +--no-recurse-submodules:: + Disable recursive fetching of submodules (this has the same effect as + using the `--recurse-submodules=no` option). +endif::git-pull[] + +--set-upstream:: + If the remote is fetched successfully, add upstream + (tracking) reference, used by argument-less + linkgit:git-pull[1] and other commands. For more information, + see `branch..merge` and `branch..remote` in + linkgit:git-config[1]. + +ifndef::git-pull[] +--submodule-prefix=:: + Prepend to paths printed in informative messages + such as "Fetching submodule foo". This option is used + internally when recursing over submodules. + +--recurse-submodules-default=[yes|on-demand]:: + This option is used internally to temporarily provide a + non-negative default value for the --recurse-submodules + option. All other methods of configuring fetch's submodule + recursion (such as settings in linkgit:gitmodules[5] and + linkgit:git-config[1]) override this option, as does + specifying --[no-]recurse-submodules directly. + +-u:: +--update-head-ok:: + By default 'git fetch' refuses to update the head which + corresponds to the current branch. This flag disables the + check. This is purely for the internal use for 'git pull' + to communicate with 'git fetch', and unless you are + implementing your own Porcelain you are not supposed to + use it. +endif::git-pull[] + +--upload-pack :: + When given, and the repository to fetch from is handled + by 'git fetch-pack', `--exec=` is passed to + the command to specify non-default path for the command + run on the other end. + +ifndef::git-pull[] +-q:: +--quiet:: + Pass --quiet to git-fetch-pack and silence any other internally + used git commands. Progress is not reported to the standard error + stream. + +-v:: +--verbose:: + Be verbose. +endif::git-pull[] + +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. + +-o