{"thread":{"id":"52957","subject":"Documented option \"--deepen\" is unknown to git-pull","startedAt":"2020-03-08T19:17:59Z","lastAt":"2020-03-31T23:21:39Z","messageCount":6,"participants":["天几","René Scharfe","Taylor Blau"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"392955","messageId":"CAEg0tHTMHD1+3QaSe3Z+ymRKvOkbHnVqv-Xp2xhOT56SoHTmwA@mail.gmail.com","threadId":"52957","inReplyTo":null,"subject":"Documented option \"--deepen\" is unknown to git-pull","fromName":"天几","fromEmail":"muzimuzhi@gmail.com","sentAt":"2020-03-08T19:17:46Z","receivedAt":"2020-03-08T19:17:59Z","isPatch":false,"sender":{"key":"muzimuzhi@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6376638?v=4"},"body":"Option \"--deepen\" is documented in online doc of git-pull, Sec.\n_Options related to fetching_, see\n    https://git-scm.com/docs/git-pull#Documentation/git-pull.txt---deepenltdepthgt\nBut executing \"git pull --deepen=100 origin master\" returns\n    error: unknown option `deepen'\n\nMore tests show option \"--deepen\" is known to git-fetch but not\ngit-pull, although the doc of git-pull says\n    git pull runs git fetch with the given parameters and calls git\n    merge to merge the retrieved branch heads into the current branch.\n    https://git-scm.com/docs/git-pull#_description\nwhich suggests that every valid option of \"git fetch\" would also valid\nfor \"git pull\".\n\nIs this a documentation or an implementation problem? (I use git v2.25.1.)\n\n\nmuzimuzhi\n"},{"id":"392974","messageId":"a406c273-9a2c-72ed-c5e3-4c19848f0f94@web.de","threadId":"52957","inReplyTo":"CAEg0tHTMHD1+3QaSe3Z+ymRKvOkbHnVqv-Xp2xhOT56SoHTmwA@mail.gmail.com","subject":"Re: Documented option \"--deepen\" is unknown to git-pull","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2020-03-09T21:51:39Z","receivedAt":"2020-03-09T21:51:51Z","isPatch":false,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 08.03.20 um 20:17 schrieb 天几:\n> Option \"--deepen\" is documented in online doc of git-pull, Sec.\n> _Options related to fetching_, see\n>     https://git-scm.com/docs/git-pull#Documentation/git-pull.txt---deepenltdepthgt\n> But executing \"git pull --deepen=100 origin master\" returns\n>     error: unknown option `deepen'\n>\n> More tests show option \"--deepen\" is known to git-fetch but not\n> git-pull, although the doc of git-pull says\n>     git pull runs git fetch with the given parameters and calls git\n>     merge to merge the retrieved branch heads into the current branch.\n>     https://git-scm.com/docs/git-pull#_description\n> which suggests that every valid option of \"git fetch\" would also valid\n> for \"git pull\".\n>\n> Is this a documentation or an implementation problem? (I use git v2.25.1.)\n\nLooks like an oversight to me: pull has --depth, so why not --deepen as well?\n\nAre there more?  Let's take compare short help and manpage:\n\n   LANG=C git pull -h | awk '\n      /^Options related to fetching/ {show=1}\n      /^ *-/ && show {sub(/^ */, \"\"); sub(/, /, \"\\n\"); sub(/[ [=].*/, \"\"); print}\n   ' | sort >shorthelp\n   awk -v pull=1 -v show=1 '\n      /^ifdef::git-pull/ {show=pull; next}\n      /^ifndef::git-pull/ {show=!pull; next}\n      /^endif/ {show=1; next}\n      /::/ && show {sub(/::/, \"\"); sub(/[ [=].*/, \"\"); print}\n   ' Documentation/fetch-options.txt | sort >longhelp\n   diff shorthelp longhelp | grep '^[<>]' | LANG=C sort\n\n   < --dry-run\n   < --jobs\n   < --prune\n   < --refmap\n   < --set-upstream\n   < --tags\n   < -j\n   < -p\n   < -t\n   > --deepen\n   > --negotiation-tip\n   > --no-show-forced-updates\n   > --no-tags\n   > --progress\n   > --server-option\n   > --shallow-exclude\n   > --shallow-since\n   > --update-head-ok\n   > -o\n   > -u\n\nHmm, that shows a few false positives: -t/--tags actually pairs with\n--no-tags and --show-forced-updates from the short help is mentioned in\nthe manpage along with --no-show-forced-updates.  And --progress is\nactually mentioned in pull's short help, just not in the fetching\nsection.\n\nIf we ignore those cases, the following options are documented in its\nmanpage but not actually accepted by git pull:\n\n   --deepen\n   --negotiation-tip\n   --server-option\n   --shallow-exclude\n   --shallow-since\n   --update-head-ok\n   -o\n   -u\n\nSide note: There must be a better way to keep short help and manpage\nin sync than the above ad-hoc AWK scripts.\n\nHere's a patch to fix the easy part:\n\n-- >8 --\nSubject: [PATCH] pull: document more passthru options\n\ngit pull accepts the options --dry-run, -p/--prune, --refmap, and\n-t/--tags since a32975f516 (pull: pass git-fetch's options to git-fetch,\n2015-06-18), -j/--jobs since 62104ba14a (submodules: allow parallel\nfetching, add tests and documentation, 2015-12-15), and --set-upstream\nsince 24bc1a1292 (pull, fetch: add --set-upstream option, 2019-08-19).\nUpdate its documentation to match.\n\nSigned-off-by: René Scharfe <l.s.r@web.de>\n---\n Documentation/fetch-options.txt | 10 +++++++---\n 1 file changed, 7 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex a115a1ae0e..00d03ec8c3 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -61,10 +61,8 @@ this option multiple times, one for each matching ref name.\n See also the `fetch.negotiationAlgorithm` configuration variable\n documented in linkgit:git-config[1].\n\n-ifndef::git-pull[]\n --dry-run::\n \tShow what would be done, without making any changes.\n-endif::git-pull[]\n\n -f::\n --force::\n@@ -95,6 +93,7 @@ ifndef::git-pull[]\n --[no-]write-commit-graph::\n \tWrite a commit-graph after fetching. This overrides the config\n \tsetting `fetch.writeCommitGraph`.\n+endif::git-pull[]\n\n -p::\n --prune::\n@@ -107,6 +106,7 @@ ifndef::git-pull[]\n \twas cloned with the --mirror option), then they are also\n \tsubject to pruning. Supplying `--prune-tags` is a shorthand for\n \tproviding the tag refspec.\n+ifndef::git-pull[]\n +\n See the PRUNING section below for more details.\n\n@@ -133,7 +133,6 @@ endif::git-pull[]\n \tbehavior for a remote may be specified with the remote.<name>.tagOpt\n \tsetting. See linkgit:git-config[1].\n\n-ifndef::git-pull[]\n --refmap=<refspec>::\n \tWhen fetching refs listed on the command line, use the\n \tspecified refspec (can be given more than once) to map the\n@@ -154,6 +153,7 @@ ifndef::git-pull[]\n \tis used (though tags may be pruned anyway if they are also the\n \tdestination of an explicit refspec; see `--prune`).\n\n+ifndef::git-pull[]\n --recurse-submodules[=yes|on-demand|no]::\n \tThis option controls if and under what conditions new commits of\n \tpopulated submodules should be fetched too. It can be used as a\n@@ -164,6 +164,7 @@ ifndef::git-pull[]\n \twhen the superproject retrieves a commit that updates the submodule's\n \treference to a commit that isn't already in the local submodule\n \tclone.\n+endif::git-pull[]\n\n -j::\n --jobs=<n>::\n@@ -177,9 +178,11 @@ parallel. To control them independently, use the config settings\n Typically, parallel recursive and multi-remote fetches will be faster. By\n default fetches are performed sequentially, not in parallel.\n\n+ifndef::git-pull[]\n --no-recurse-submodules::\n \tDisable recursive fetching of submodules (this has the same effect as\n \tusing the `--recurse-submodules=no` option).\n+endif::git-pull[]\n\n --set-upstream::\n \tIf the remote is fetched successfully, pull and add upstream\n@@ -188,6 +191,7 @@ default fetches are performed sequentially, not in parallel.\n \tsee `branch.<name>.merge` and `branch.<name>.remote` in\n \tlinkgit:git-config[1].\n\n+ifndef::git-pull[]\n --submodule-prefix=<path>::\n \tPrepend <path> to paths printed in informative messages\n \tsuch as \"Fetching submodule foo\".  This option is used\n--\n2.25.1\n"},{"id":"394231","messageId":"c94f8c43-625c-8e99-fa04-aafb0c7cdd78@web.de","threadId":"52957","inReplyTo":"a406c273-9a2c-72ed-c5e3-4c19848f0f94@web.de","subject":"[PATCH 2/1] pull: remove --update-head-ok from documentation","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2020-03-28T14:48:33Z","receivedAt":"2020-03-28T14:48:45Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"'git pull' implicitly passes --update-head-ok to 'git fetch', but\ndoesn't itself accept that option from users.  That makes sense, as it\nwouldn't work without the possibility to update HEAD.  Remove the option\nfrom the command's documentation to match its actual behavior.\n\nSigned-off-by: René Scharfe <l.s.r@web.de>\n---\n Documentation/fetch-options.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex 00d03ec8c3..05709f67a1 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -204,7 +204,6 @@ ifndef::git-pull[]\n \trecursion (such as settings in linkgit:gitmodules[5] and\n \tlinkgit:git-config[1]) override this option, as does\n \tspecifying --[no-]recurse-submodules directly.\n-endif::git-pull[]\n\n -u::\n --update-head-ok::\n@@ -214,6 +213,7 @@ endif::git-pull[]\n \tto communicate with 'git fetch', and unless you are\n \timplementing your own Porcelain you are not supposed to\n \tuse it.\n+endif::git-pull[]\n\n --upload-pack <upload-pack>::\n \tWhen given, and the repository to fetch from is handled\n--\n2.26.0\n"},{"id":"394232","messageId":"631d4c1b-b3f8-bb55-129e-7285ca19fe09@web.de","threadId":"52957","inReplyTo":"a406c273-9a2c-72ed-c5e3-4c19848f0f94@web.de","subject":"[PATCH 3/1] pull: pass documented fetch options on","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2020-03-28T14:48:41Z","receivedAt":"2020-03-28T14:48:48Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"The fetch options --deepen, --negotiation-tip, --server-option,\n--shallow-exclude, and --shallow-since are documented for git pull as\nwell, but are not actually accepted by that command.  Pass them on to\nmake the code match its documentation.\n\nReported-by: 天几 <muzimuzhi@gmail.com>\nSigned-off-by: René Scharfe <l.s.r@web.de>\n---\n builtin/pull.c | 18 ++++++++++++++++++\n 1 file changed, 18 insertions(+)\n\ndiff --git a/builtin/pull.c b/builtin/pull.c\nindex e42665b681..880eb29852 100644\n--- a/builtin/pull.c\n+++ b/builtin/pull.c\n@@ -110,6 +110,7 @@ static char *opt_ipv4;\n static char *opt_ipv6;\n static int opt_show_forced_updates = -1;\n static char *set_upstream;\n+static struct argv_array opt_fetch = ARGV_ARRAY_INIT;\n\n static struct option pull_options[] = {\n \t/* Shared options */\n@@ -207,6 +208,15 @@ static struct option pull_options[] = {\n \tOPT_PASSTHRU(0, \"depth\", &opt_depth, N_(\"depth\"),\n \t\tN_(\"deepen history of shallow clone\"),\n \t\t0),\n+\tOPT_PASSTHRU_ARGV(0, \"shallow-since\", &opt_fetch, N_(\"time\"),\n+\t\tN_(\"deepen history of shallow repository based on time\"),\n+\t\t0),\n+\tOPT_PASSTHRU_ARGV(0, \"shallow-exclude\", &opt_fetch, N_(\"revision\"),\n+\t\tN_(\"deepen history of shallow clone, excluding rev\"),\n+\t\t0),\n+\tOPT_PASSTHRU_ARGV(0, \"deepen\", &opt_fetch, N_(\"n\"),\n+\t\tN_(\"deepen history of shallow clone\"),\n+\t\t0),\n \tOPT_PASSTHRU(0, \"unshallow\", &opt_unshallow, NULL,\n \t\tN_(\"convert to a complete repository\"),\n \t\tPARSE_OPT_NONEG | PARSE_OPT_NOARG),\n@@ -216,12 +226,19 @@ static struct option pull_options[] = {\n \tOPT_PASSTHRU(0, \"refmap\", &opt_refmap, N_(\"refmap\"),\n \t\tN_(\"specify fetch refmap\"),\n \t\tPARSE_OPT_NONEG),\n+\tOPT_PASSTHRU_ARGV('o', \"server-option\", &opt_fetch,\n+\t\tN_(\"server-specific\"),\n+\t\tN_(\"option to transmit\"),\n+\t\t0),\n \tOPT_PASSTHRU('4',  \"ipv4\", &opt_ipv4, NULL,\n \t\tN_(\"use IPv4 addresses only\"),\n \t\tPARSE_OPT_NOARG),\n \tOPT_PASSTHRU('6',  \"ipv6\", &opt_ipv6, NULL,\n \t\tN_(\"use IPv6 addresses only\"),\n \t\tPARSE_OPT_NOARG),\n+\tOPT_PASSTHRU_ARGV(0, \"negotiation-tip\", &opt_fetch, N_(\"revision\"),\n+\t\tN_(\"report that we have only objects reachable from this object\"),\n+\t\t0),\n \tOPT_BOOL(0, \"show-forced-updates\", &opt_show_forced_updates,\n \t\t N_(\"check for forced-updates on all updated branches\")),\n \tOPT_PASSTHRU(0, \"set-upstream\", &set_upstream, NULL,\n@@ -567,6 +584,7 @@ static int run_fetch(const char *repo, const char **refspecs)\n \t\targv_array_push(&args, \"--no-show-forced-updates\");\n \tif (set_upstream)\n \t\targv_array_push(&args, set_upstream);\n+\targv_array_pushv(&args, opt_fetch.argv);\n\n \tif (repo) {\n \t\targv_array_push(&args, repo);\n--\n2.26.0\n"},{"id":"394440","messageId":"20200331214851.GB95875@syl.local","threadId":"52957","inReplyTo":"c94f8c43-625c-8e99-fa04-aafb0c7cdd78@web.de","subject":"Re: [PATCH 2/1] pull: remove --update-head-ok from documentation","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2020-03-31T21:48:51Z","receivedAt":"2020-03-31T21:48:55Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"Hi René,\n\nThis patch (and the other one attached to this thread) both look good.\nHowever, the numbering on this patch is a little weird, (2/1? 3/1?). Is\nthere a third patch missing, and/or are your subject lines mangled?\n\nPlease share if there is more, or if I should be interpreting this\nseries differently. Otherwise this patch makes sense.\n\nOn Sat, Mar 28, 2020 at 03:48:33PM +0100, René Scharfe wrote:\n> 'git pull' implicitly passes --update-head-ok to 'git fetch', but\n> doesn't itself accept that option from users.  That makes sense, as it\n> wouldn't work without the possibility to update HEAD.  Remove the option\n> from the command's documentation to match its actual behavior.\n>\n> Signed-off-by: René Scharfe <l.s.r@web.de>\n> ---\n>  Documentation/fetch-options.txt | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\n> index 00d03ec8c3..05709f67a1 100644\n> --- a/Documentation/fetch-options.txt\n> +++ b/Documentation/fetch-options.txt\n> @@ -204,7 +204,6 @@ ifndef::git-pull[]\n>  \trecursion (such as settings in linkgit:gitmodules[5] and\n>  \tlinkgit:git-config[1]) override this option, as does\n>  \tspecifying --[no-]recurse-submodules directly.\n> -endif::git-pull[]\n>\n>  -u::\n>  --update-head-ok::\n> @@ -214,6 +213,7 @@ endif::git-pull[]\n>  \tto communicate with 'git fetch', and unless you are\n>  \timplementing your own Porcelain you are not supposed to\n>  \tuse it.\n> +endif::git-pull[]\n>\n>  --upload-pack <upload-pack>::\n>  \tWhen given, and the repository to fetch from is handled\n> --\n> 2.26.0\n\nThanks,\nTaylor\n"},{"id":"394447","messageId":"82876e28-ede5-ad1b-856e-e2267268e7c7@web.de","threadId":"52957","inReplyTo":"20200331214851.GB95875@syl.local","subject":"Re: [PATCH 2/1] pull: remove --update-head-ok from documentation","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2020-03-31T23:21:29Z","receivedAt":"2020-03-31T23:21:39Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 31.03.20 um 23:48 schrieb Taylor Blau:\n> This patch (and the other one attached to this thread) both look good.\n> However, the numbering on this patch is a little weird, (2/1? 3/1?). Is\n> there a third patch missing, and/or are your subject lines mangled?\n>\n> Please share if there is more, or if I should be interpreting this\n> series differently. Otherwise this patch makes sense.\n\nThe first patch was\nhttps://lore.kernel.org/git/a406c273-9a2c-72ed-c5e3-4c19848f0f94@web.de/\nand I meant to only send that one.  A few weeks later I couldn't help\nbut follow up with two more patches.  I don't plan to continue the\nseries any further.\n\nRené\n"}]}