[PATCH] docs: Explain the purpose of fetch's and pull's <refspec> parameter.
From: Marc Branchaud <hidden>
Date: 2016-06-15 23:01:35
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-15 · [PATCH] docs: Explain the purpose of fetch's and pull's <refspec> parameter. · Marc Branchaud <hidden>
Signed-off-by: Marc Branchaud <redacted> --- Documentation/git-fetch.txt | 4 ++-- Documentation/pull-fetch-param.txt | 18 ++++++++++++++---- 2 files changed, 16 insertions(+), 6 deletions(-) On 14-06-05 06:12 PM, Junio C Hamano wrote:
quoted
+ <refspec> parameters are not normally specified on the command + line, but instead are read from `remote.<repository>.fetch`I however am not sure if this is an improvement, especially the "normally" part. Those who respond to a git-pull-request output might be fewer than those who send pull requests, but that does not mean they are abnormal. The command line often omit <refspec> parameters when fetching or pulling from a remote you regularly interact with, in which case `remote.<repository>.fetch` values are used instead. would be OK, though. Later today I'll push out the series on 'pu' after amending them with your comments so far. It would be nice if you can reroll this on top of the updated one ("git log --oneline --first-parent master..pu" and find jc/fetch-pull-refmap in there).
Here's the reroll. I used completely different phrasing but I think I still captured the gist of what you said. (Apologies for the delay -- I was looking for jc/fetch-pull-refmap on pu, not jc/fetch-push-refmap on next!) M.
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 629a1cf..8deb614 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt@@ -51,8 +51,8 @@ include::pull-fetch-param.txt[] include::urls-remotes.txt[] -CONFIGURED REMOTE-TRACKING BRANCHES ------------------------------------ +CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]] +------------------------------------------- You often interact with the same remote repository by regularly and repeatedly fetching from it. In order to keep track
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 4bff65b..1ebbf1d 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt@@ -12,10 +12,20 @@ ifndef::git-pull[] endif::git-pull[] <refspec>:: - The format of a <refspec> parameter is an optional plus - `+`, followed by the source ref <src>, followed - by a colon `:`, followed by the destination ref <dst>. - The colon can be omitted when <dst> is empty. + Specifies which refs to fetch and which local refs to update. + When no <refspec>s appear on the command line, the refs to fetch + are read from `remote.<repository>.fetch` variables instead +ifndef::git-pull[] + (see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below). +endif::git-pull[] +ifdef::git-pull[] + (see linkgit:git-fetch[1]). +endif::git-pull[] ++ +The format of a <refspec> parameter is an optional plus +`+`, followed by the source ref <src>, followed +by a colon `:`, followed by the destination ref <dst>. +The colon can be omitted when <dst> is empty. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; it requests fetching everything up to the given tag.
--
2.0.0.dirty