Re: [RFC PATCH 1/2] docs: reflect supported fetch options of git pull

[Duy Nguyen <pclouds@gmail.com>]

On Mon, Jun 4, 2018 at 11:50 PM, Rafael Ascensão <rafa.almas@gmail.com> wrote:
> `git pull` understands some options of `git fetch` which then uses in
> its operation. The documentation of `git pull` doesn't reflect this
> clearly, showing options that are not yet supported (e.g. `--deepen`)
> and omitting options that are supported (e.g. `--prune`).
>
> Make the documentation consistent with present behaviour by hiding
> unavailable options only.

A better option may be making git-pull accept those options as well. I
see no reason git-pull should support options that git-fetch does (at
least most of them). But I would understand if you would not want to
go touch the code. It's basically a couple of OPT_PASSTRHU though so
not very hard to do.

PS. Anybody up to making parse-options accept multiple struct option
arrays? This way we can have much better option passthru without
specifying them again and again.

>
> Reported-by: Marius Giurgi <marius.giurgi@gmail.com>
> Signed-off-by: Rafael Ascensão <rafa.almas@gmail.com>
> ---
>
> Marius asked on freenode.#git if pull supported `--prune`, upon
> inspection seems like the man page was missing some of the supported
> options and listing others that are not supported via pull.
>
> Here's a quick summary of the changes to pull's documentation:
>
> add:                      remove:
>   --dry-run                 --deepen=<depth>
>   -p, --prune               --shallow-since=<date>
>   --refmap=<refspec>        --shallow-exclude=<revision>
>   -t, --tags                -u, --update-head-ok
>   -j, --jobs=<n>
>
>  Documentation/fetch-options.txt | 20 +++++++++++++-------
>  1 file changed, 13 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index 8631e365f..da17d27c1 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -14,6 +14,7 @@
>         linkgit:git-clone[1]), deepen or shorten the history to the specified
>         number of commits. Tags for the deepened commits are not fetched.
>
> +ifndef::git-pull[]
>  --deepen=<depth>::
>         Similar to --depth, except it specifies the number of commits
>         from the current shallow boundary instead of from the tip of
> @@ -27,6 +28,7 @@
>         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.
> +endif::git-pull[]
>
>  --unshallow::
>         If the source repository is complete, convert a shallow
> @@ -42,10 +44,8 @@ the current repository has the same history as the source repository.
>         .git/shallow. This option updates .git/shallow and accept such
>         refs.
>
> -ifndef::git-pull[]
>  --dry-run::
>         Show what would be done, without making any changes.
> -endif::git-pull[]
>
>  -f::
>  --force::
> @@ -63,6 +63,7 @@ ifndef::git-pull[]
>  --multiple::
>         Allow several <repository> and <group> arguments to be
>         specified. No <refspec>s may be specified.
> +endif::git-pull[]
>
>  -p::
>  --prune::
> @@ -76,8 +77,14 @@ ifndef::git-pull[]
>         subject to pruning. Supplying `--prune-tags` is a shorthand for
>         providing the tag refspec.
>  +
> +ifdef::git-pull[]
> +See the PRUNING section on linkgit:git-fetch[1] for more details.
> +endif::git-pull[]
> +ifndef::git-pull[]
>  See the PRUNING section below for more details.
> +endif::git-pull[]
>
> +ifndef::git-pull[]
>  -P::
>  --prune-tags::
>         Before fetching, remove any local tags that no longer exist on
> @@ -89,9 +96,6 @@ See the PRUNING section below for more details.
>  +
>  See the PRUNING section below for more details.
>
> -endif::git-pull[]
> -
> -ifndef::git-pull[]
>  -n::
>  endif::git-pull[]
>  --no-tags::
> @@ -101,7 +105,6 @@ endif::git-pull[]
>         behavior for a remote may be specified with the remote.<name>.tagOpt
>         setting. See linkgit:git-config[1].
>
> -ifndef::git-pull[]
>  --refmap=<refspec>::
>         When fetching refs listed on the command line, use the
>         specified refspec (can be given more than once) to map the
> @@ -119,6 +122,7 @@ ifndef::git-pull[]
>         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
>         populated submodules should be fetched too. It can be used as a
> @@ -129,6 +133,7 @@ ifndef::git-pull[]
>         when the superproject retrieves a commit that updates the submodule's
>         reference to a commit that isn't already in the local submodule
>         clone.
> +endif::git-pull[]
>
>  -j::
>  --jobs=<n>::
> @@ -137,6 +142,7 @@ ifndef::git-pull[]
>         submodules will be faster. By default submodules will be fetched
>         one at a time.
>
> +ifndef::git-pull[]
>  --no-recurse-submodules::
>         Disable recursive fetching of submodules (this has the same effect as
>         using the `--recurse-submodules=no` option).
> @@ -153,7 +159,6 @@ ifndef::git-pull[]
>         recursion (such as settings in linkgit:gitmodules[5] and
>         linkgit:git-config[1]) override this option, as does
>         specifying --[no-]recurse-submodules directly.
> -endif::git-pull[]
>
>  -u::
>  --update-head-ok::
> @@ -163,6 +168,7 @@ endif::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
> --
> 2.17.1
>



-- 
Duy