Re: Documented option "--deepen" is unknown to git-pull

["René Scharfe" <l.s.r@web.de>]

Am 08.03.20 um 20:17 schrieb 天几:
> Option "--deepen" is documented in online doc of git-pull, Sec.
> _Options related to fetching_, see
>     https://git-scm.com/docs/git-pull#Documentation/git-pull.txt---deepenltdepthgt
> But executing "git pull --deepen=100 origin master" returns
>     error: unknown option `deepen'
>
> More tests show option "--deepen" is known to git-fetch but not
> git-pull, although the doc of git-pull says
>     git pull runs git fetch with the given parameters and calls git
>     merge to merge the retrieved branch heads into the current branch.
>     https://git-scm.com/docs/git-pull#_description
> which suggests that every valid option of "git fetch" would also valid
> for "git pull".
>
> Is this a documentation or an implementation problem? (I use git v2.25.1.)

Looks like an oversight to me: pull has --depth, so why not --deepen as well?

Are there more?  Let's take compare short help and manpage:

   LANG=C git pull -h | awk '
      /^Options related to fetching/ {show=1}
      /^ *-/ && show {sub(/^ */, ""); sub(/, /, "\n"); sub(/[ [=].*/, ""); print}
   ' | sort >shorthelp
   awk -v pull=1 -v show=1 '
      /^ifdef::git-pull/ {show=pull; next}
      /^ifndef::git-pull/ {show=!pull; next}
      /^endif/ {show=1; next}
      /::/ && show {sub(/::/, ""); sub(/[ [=].*/, ""); print}
   ' Documentation/fetch-options.txt | sort >longhelp
   diff shorthelp longhelp | grep '^[<>]' | LANG=C sort

   < --dry-run
   < --jobs
   < --prune
   < --refmap
   < --set-upstream
   < --tags
   < -j
   < -p
   < -t
   > --deepen
   > --negotiation-tip
   > --no-show-forced-updates
   > --no-tags
   > --progress
   > --server-option
   > --shallow-exclude
   > --shallow-since
   > --update-head-ok
   > -o
   > -u

Hmm, that shows a few false positives: -t/--tags actually pairs with
--no-tags and --show-forced-updates from the short help is mentioned in
the manpage along with --no-show-forced-updates.  And --progress is
actually mentioned in pull's short help, just not in the fetching
section.

If we ignore those cases, the following options are documented in its
manpage but not actually accepted by git pull:

   --deepen
   --negotiation-tip
   --server-option
   --shallow-exclude
   --shallow-since
   --update-head-ok
   -o
   -u

Side note: There must be a better way to keep short help and manpage
in sync than the above ad-hoc AWK scripts.

Here's a patch to fix the easy part:

-- >8 --
Subject: [PATCH] pull: document more passthru options

git pull accepts the options --dry-run, -p/--prune, --refmap, and
-t/--tags since a32975f516 (pull: pass git-fetch's options to git-fetch,
2015-06-18), -j/--jobs since 62104ba14a (submodules: allow parallel
fetching, add tests and documentation, 2015-12-15), and --set-upstream
since 24bc1a1292 (pull, fetch: add --set-upstream option, 2019-08-19).
Update its documentation to match.

Signed-off-by: René Scharfe <l.s.r@web.de>
---
 Documentation/fetch-options.txt | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index a115a1ae0e..00d03ec8c3 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -61,10 +61,8 @@ this option multiple times, one for each matching ref name.
 See also the `fetch.negotiationAlgorithm` configuration variable
 documented in linkgit:git-config[1].

-ifndef::git-pull[]
 --dry-run::
 	Show what would be done, without making any changes.
-endif::git-pull[]

 -f::
 --force::
@@ -95,6 +93,7 @@ ifndef::git-pull[]
 --[no-]write-commit-graph::
 	Write a commit-graph after fetching. This overrides the config
 	setting `fetch.writeCommitGraph`.
+endif::git-pull[]

 -p::
 --prune::
@@ -107,6 +106,7 @@ ifndef::git-pull[]
 	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.

@@ -133,7 +133,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
@@ -154,6 +153,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
@@ -164,6 +164,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>::
@@ -177,9 +178,11 @@ parallel. To control them independently, use the config settings
 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, pull and add upstream
@@ -188,6 +191,7 @@ default fetches are performed sequentially, not in parallel.
 	see `branch.<name>.merge` and `branch.<name>.remote` in
 	linkgit:git-config[1].

+ifndef::git-pull[]
 --submodule-prefix=<path>::
 	Prepend <path> to paths printed in informative messages
 	such as "Fetching submodule foo".  This option is used
--
2.25.1