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

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

[Rafael Ascensão]

`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.

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

[RFC PATCH 2/2] pull: allow -e as a synonym for --edit

[Rafael Ascensão]

`git pull`'s documentation mentions that `--edit` can be used with short
option `-e`. But `git pull` doesn't understand `-e`.

To make things consistent, teach `git pull` `-e` for `--edit`

Signed-off-by: Rafael Ascensão <rafa.almas@gmail.com>
---
 builtin/pull.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/builtin/pull.c b/builtin/pull.c
index e32d6cd5b..dd54f2e57 100644
--- a/builtin/pull.c
+++ b/builtin/pull.c
@@ -154,7 +154,7 @@ static struct option pull_options[] = {
 	OPT_PASSTHRU(0, "commit", &opt_commit, NULL,
 		N_("perform a commit if the merge succeeds (default)"),
 		PARSE_OPT_NOARG),
-	OPT_PASSTHRU(0, "edit", &opt_edit, NULL,
+	OPT_PASSTHRU('e', "edit", &opt_edit, NULL,
 		N_("edit message before committing"),
 		PARSE_OPT_NOARG),
 	OPT_PASSTHRU(0, "ff", &opt_ff, NULL,
-- 
2.17.1

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

[Duy Nguyen]

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

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

[Rafael Ascensão]

On Tue, Jun 05, 2018 at 06:05:56PM +0200, Duy Nguyen wrote:
> 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).

I sent this as a RFC, mostly to discuss what is the correct path to
follow. Updating the documentation was trivial and would still be useful
if nothing came out from this.

> It's basically a couple of OPT_PASSTRHU though so not very hard to do.

My impression was that in the past git was very permissive on adding new
options but nowadays it tries exercise more restraint. But not sure how
relevant this is anyways, as pull already supports the majority of the
options from both `fetch` and `merge`.

> 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.

If the path is adding just couple of OPT_PASSTRHU, I could do it. But
I'll wait and see if someone picks your parse-options suggestion.

Thanks for the review.

--
Rafael Ascensão