From: Jean-Noël Avila Date: Wed, 19 Nov 2025 21:40:02 +0000 (+0000) Subject: doc: convert git fetch to synopsis style X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=903b04a3e721f4afb337bd48890b69e16c04c5d6;p=thirdparty%2Fgit.git doc: convert git fetch to synopsis style - Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use __ instead of in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- diff --git a/Documentation/config/fetch.adoc b/Documentation/config/fetch.adoc index d7dc461bd1..cd40db0cad 100644 --- a/Documentation/config/fetch.adoc +++ b/Documentation/config/fetch.adoc @@ -1,32 +1,32 @@ -fetch.recurseSubmodules:: +`fetch.recurseSubmodules`:: This option controls whether `git fetch` (and the underlying fetch in `git pull`) will recursively fetch into populated submodules. - This option can be set either to a boolean value or to 'on-demand'. + This option can be set either to a boolean value or to `on-demand`. Setting it to a boolean changes the behavior of fetch and pull to recurse unconditionally into submodules when set to true or to not - recurse at all when set to false. When set to 'on-demand', fetch and + recurse at all when set to false. When set to `on-demand`, fetch and pull will only recurse into a populated submodule when its superproject retrieves a commit that updates the submodule's reference. - Defaults to 'on-demand', or to the value of 'submodule.recurse' if set. + Defaults to `on-demand`, or to the value of `submodule.recurse` if set. -fetch.fsckObjects:: +`fetch.fsckObjects`:: If it is set to true, git-fetch-pack will check all fetched objects. See `transfer.fsckObjects` for what's - checked. Defaults to false. If not set, the value of + checked. Defaults to `false`. If not set, the value of `transfer.fsckObjects` is used instead. -fetch.fsck.:: +`fetch.fsck.`:: Acts like `fsck.`, but is used by linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See the `fsck.` documentation for details. -fetch.fsck.skipList:: +`fetch.fsck.skipList`:: Acts like `fsck.skipList`, but is used by linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See the `fsck.skipList` documentation for details. -fetch.unpackLimit:: +`fetch.unpackLimit`:: If the number of objects fetched over the Git native transfer is below this limit, then the objects will be unpacked into loose object @@ -37,12 +37,12 @@ fetch.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. -fetch.prune:: +`fetch.prune`:: If true, fetch will automatically behave as if the `--prune` option was given on the command line. See also `remote..prune` and the PRUNING section of linkgit:git-fetch[1]. -fetch.pruneTags:: +`fetch.pruneTags`:: If true, fetch will automatically behave as if the `refs/tags/*:refs/tags/*` refspec was provided when pruning, if not set already. This allows for setting both this option @@ -50,41 +50,41 @@ fetch.pruneTags:: refs. See also `remote..pruneTags` and the PRUNING section of linkgit:git-fetch[1]. -fetch.all:: +`fetch.all`:: If true, fetch will attempt to update all available remotes. This behavior can be overridden by passing `--no-all` or by explicitly specifying one or more remote(s) to fetch from. - Defaults to false. + Defaults to `false`. -fetch.output:: +`fetch.output`:: Control how ref update status is printed. Valid values are `full` and `compact`. Default value is `full`. See the OUTPUT section in linkgit:git-fetch[1] for details. -fetch.negotiationAlgorithm:: +`fetch.negotiationAlgorithm`:: Control how information about the commits in the local repository is sent when negotiating the contents of the packfile to be sent by - the server. Set to "consecutive" to use an algorithm that walks - over consecutive commits checking each one. Set to "skipping" to + the server. Set to `consecutive` to use an algorithm that walks + over consecutive commits checking each one. Set to `skipping` to use an algorithm that skips commits in an effort to converge faster, but may result in a larger-than-necessary packfile; or set - to "noop" to not send any information at all, which will almost + to `noop` to not send any information at all, which will almost certainly result in a larger-than-necessary packfile, but will skip - the negotiation step. Set to "default" to override settings made + the negotiation step. Set to `default` to override settings made previously and use the default behaviour. The default is normally - "consecutive", but if `feature.experimental` is true, then the - default is "skipping". Unknown values will cause 'git fetch' to + `consecutive`, but if `feature.experimental` is `true`, then the + default is `skipping`. Unknown values will cause `git fetch` to error out. + See also the `--negotiate-only` and `--negotiation-tip` options to linkgit:git-fetch[1]. -fetch.showForcedUpdates:: - Set to false to enable `--no-show-forced-updates` in +`fetch.showForcedUpdates`:: + Set to `false` to enable `--no-show-forced-updates` in linkgit:git-fetch[1] and linkgit:git-pull[1] commands. - Defaults to true. + Defaults to `true`. -fetch.parallel:: +`fetch.parallel`:: Specifies the maximal number of fetch operations to be run in parallel at a time (submodules, or remotes when the `--multiple` option of linkgit:git-fetch[1] is in effect). @@ -94,16 +94,16 @@ A value of 0 will give some reasonable default. If unset, it defaults to 1. For submodules, this setting can be overridden using the `submodule.fetchJobs` config setting. -fetch.writeCommitGraph:: +`fetch.writeCommitGraph`:: Set to true to write a commit-graph after every `git fetch` command that downloads a pack-file from a remote. Using the `--split` option, most executions will create a very small commit-graph file on top of the existing commit-graph file(s). Occasionally, these files will merge and the write may take longer. Having an updated commit-graph file helps performance of many Git commands, including `git merge-base`, - `git push -f`, and `git log --graph`. Defaults to false. + `git push -f`, and `git log --graph`. Defaults to `false`. -fetch.bundleURI:: +`fetch.bundleURI`:: This value stores a URI for downloading Git object data from a bundle URI before performing an incremental fetch from the origin Git server. This is similar to how the `--bundle-uri` option behaves in @@ -115,9 +115,9 @@ If you modify this value and your repository has a `fetch.bundleCreationToken` value, then remove that `fetch.bundleCreationToken` value before fetching from the new bundle URI. -fetch.bundleCreationToken:: +`fetch.bundleCreationToken`:: When using `fetch.bundleURI` to fetch incrementally from a bundle - list that uses the "creationToken" heuristic, this config value + list that uses the "`creationToken`" heuristic, this config value stores the maximum `creationToken` value of the downloaded bundles. This value is used to prevent downloading bundles in the future if the advertised `creationToken` is not strictly larger than this diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index ad1e1f49be..35a84a1ef2 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -1,41 +1,41 @@ ---all:: ---no-all:: +`--all`:: +`--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:: +`-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:: +`--atomic`:: Use an atomic transaction to update local refs. Either all refs are updated, or on error, no refs are updated. ---depth=:: +`--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 +`--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=:: +`--shallow-since=`:: Deepen or shorten the history of a shallow repository to - include all reachable commits after . + include all reachable commits after __. ---shallow-exclude=:: +`--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:: +`--unshallow`:: If the source repository is complete, convert a shallow repository to a complete one, removing all the limitations imposed by shallow repositories. @@ -43,13 +43,13 @@ 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:: +`--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 + `.git/shallow`. This option updates `.git/shallow` and accepts such refs. ---negotiation-tip=:: +`--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, @@ -69,28 +69,28 @@ See also the `fetch.negotiationAlgorithm` and `push.negotiate` configuration variables documented in linkgit:git-config[1], and the `--negotiate-only` option below. ---negotiate-only:: +`--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]`. +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:: +`--dry-run`:: Show what would be done, without making any changes. ---porcelain:: +`--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 +This is incompatible with `--recurse-submodules=(yes|on-demand)` and takes precedence over the `fetch.output` config option. ifndef::git-pull[] ---write-fetch-head:: ---no-write-fetch-head:: +`--write-fetch-head`:: +`--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 @@ -98,64 +98,65 @@ ifndef::git-pull[] 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 +`-f`:: +`--force`:: ifdef::git-pull[] - in the `` part of the linkgit:git-fetch[1] - documentation. +When `git fetch` is used with `:` refspec, it may +refuse to update the local branch as discussed +in the __ part of the linkgit:git-fetch[1] +documentation. endif::git-pull[] ifndef::git-pull[] - in the `` part below. +When `git fetch` is used with `:` refspec, it may +refuse to update the local branch as discussed in the __ part below. endif::git-pull[] - This option overrides that check. +This option overrides that check. --k:: ---keep:: +`-k`:: +`--keep`:: Keep downloaded pack. ifndef::git-pull[] ---multiple:: - Allow several and arguments to be - specified. No s may be specified. - ---auto-maintenance:: ---no-auto-maintenance:: ---auto-gc:: ---no-auto-gc:: +`--multiple`:: + Allow several __ and __ arguments to be + specified. No ____s may be specified. + +`--auto-maintenance`:: +`--no-auto-maintenance`:: +`--auto-gc`:: +`--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. ---write-commit-graph:: ---no-write-commit-graph:: +`--write-commit-graph`:: +`--no-write-commit-graph`:: Write a commit-graph after fetching. This overrides the config setting `fetch.writeCommitGraph`. endif::git-pull[] ---prefetch:: +`--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:: +`-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 + 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 + 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:: +`-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 @@ -168,17 +169,17 @@ See the PRUNING section below for more details. endif::git-pull[] ifndef::git-pull[] --n:: +`-n`:: endif::git-pull[] ---no-tags:: +`--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 + behavior for a remote may be specified with the `remote..tagOpt` setting. See linkgit:git-config[1]. ifndef::git-pull[] ---refetch:: +`--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 @@ -187,19 +188,19 @@ ifndef::git-pull[] object database pack consolidation to remove any duplicate objects. endif::git-pull[] ---refmap=:: +`--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 + `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:: +`-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 @@ -208,8 +209,8 @@ endif::git-pull[] 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 +`--recurse-submodules[=(yes|on-demand|no)]`:: + Control 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 @@ -219,19 +220,19 @@ ifndef::git-pull[] 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 +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'. +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. +`-j `:: +`--jobs=`:: + Parallelize all forms of fetching up to __ jobs at a time. + If the `--multiple` option was specified, the different remotes will be fetched in parallel. If multiple submodules are fetched, they will be fetched in @@ -242,12 +243,12 @@ 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:: +`--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:: +`--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, @@ -255,55 +256,55 @@ endif::git-pull[] linkgit:git-config[1]. ifndef::git-pull[] ---submodule-prefix=:: - Prepend to paths printed in informative messages +`--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]:: +`--recurse-submodules-default=(yes|on-demand)`:: This option is used internally to temporarily provide a - non-negative default value for the --recurse-submodules + 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. + specifying `--[no-]recurse-submodules` directly. --u:: ---update-head-ok:: - By default 'git fetch' refuses to update the head which +`-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 + 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 :: +`--upload-pack `:: When given, and the repository to fetch from is handled - by 'git fetch-pack', `--exec=` is passed to + 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 +`-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:: +`-v`:: +`--verbose`:: Be verbose. endif::git-pull[] ---progress:: +`--progress`:: Progress status is reported on the standard error stream - by default when it is attached to a terminal, unless -q + 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