[PATCH] docs: Explain the purpose of fetch's and pull's <refspec> parameter.
- From
Marc Branchaud <marcnarc@xiplink.com>
- Date
- Jun 5, 2014, 15:40 UTC
- Message-ID
- <1401982803-22346-1-git-send-email-marcnarc@xiplink.com>
- In-Reply-To
- <53908CE3.6080106@xiplink.com>
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com> --- Documentation/git-fetch.txt | 4 ++-- Documentation/pull-fetch-param.txt | 17 ++++++++++++++--- 2 files changed, 16 insertions(+), 5 deletions(-)
On 14-06-04 06:17 PM, Junio C Hamano wrote:
Show 8 quoted lines
> > Perhaps > > ... `remote.<repository>.fetch` values are used as the refspecs, > i.e. they specify what refs to fetch and what local refs to > update. > > or something?
In fact, I like that so much I think it should be *the* description of the <refspec> parameter. Much better than just jumping straight into the syntax.
This patch applies atop your 8/9. I feel strongly that some kind of reference should accompany this description, and your new CONFIGURED REMOTE-TRACKING BRANCHES section seems like a good one for the fetch variant, but since pull's variant doesn't have that section I just made it link to fetch's doc.
(Also, I'm not sure if "CRTB" is a good link ID for your new section.)
M.
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 4a735ab..a4cafa3 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -49,8 +49,8 @@ include::pull-fetch-param.txt[] include::urls-remotes.txt[] -CONFIGURED REMOTE-TRACKING BRANCHES ------------------------------------ +CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]] +------------------------------------------- You would 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 18cffc2..40304c6 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -12,9 +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>. + Specifies which refs to fetch and which local refs to update. + <refspec> parameters are not normally specified on the command + line, but instead are read from `remote.<repository>.fetch` + configuration variables +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 remote ref that matches <src> is fetched, and if <dst> is not empty string, the local
-- 2.0.0.dirty