Web lists-archives.com

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




`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@xxxxxxxxx>
Signed-off-by: Rafael Ascensão <rafa.almas@xxxxxxxxx>
---

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