Re: [PATCH 1/3] Documentation: simplify refspec format description
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:46:02
Anders Melchiorsen [off-list ref] writes:
quoted hunk
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index ebdd948..820c140 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt@@ -5,10 +5,10 @@ of a remote (see the section <<REMOTES,REMOTES>> below). <refspec>:: - The canonical format of a <refspec> parameter is - `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed - by the source ref, followed by a colon `:`, followed by - the destination ref. + The format of a <refspec> parameter is an optional plus + `{plus}`, followed by the source ref <src>, followed + by a colon `:`, followed by the destination ref <dst>. + Find various forms of refspecs in examples section. + The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local
I think this is *much* nicer, but I do not think git-fetch.txt has examples to fall back on. The patch to git-push.txt would not have this issue; the exmaple is there in the page itself. But I think it might be even better to briefly describe what it means, like this patch on top of yours does to git-push.txt. The fetch/pull side already has the corresponding description immediately after that, so I'd suggest just removing the reference to non-existing examples section. I found your 2/3 and 3/3 good improvements. Documentation/git-push.txt | 3 ++- Documentation/pull-fetch-param.txt | 3 +-- 2 files changed, 3 insertions(+), 3 deletions(-)
diff --git i/Documentation/git-push.txt w/Documentation/git-push.txt
index 3fd4bbb..ea45935 100644
--- i/Documentation/git-push.txt
+++ w/Documentation/git-push.txt@@ -36,7 +36,8 @@ OPTIONS The format of a <refspec> parameter is an optional plus `{plus}`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. - Find various forms of refspecs in examples section. + It is used to specify with what <src> object the <dst> ref + in the remote repository is to be updated. + The <src> side represents the source branch (or arbitrary "SHA1 expression", such as `master~4` (four parents before the
diff --git i/Documentation/pull-fetch-param.txt w/Documentation/pull-fetch-param.txt
index 820c140..f9811f2 100644
--- i/Documentation/pull-fetch-param.txt
+++ w/Documentation/pull-fetch-param.txt@@ -8,12 +8,11 @@ The format of a <refspec> parameter is an optional plus `{plus}`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. - Find various forms of refspecs in examples section. + The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>. -Again, if the optional plus `+` is used, the local ref +If the optional plus `+` is used, the local ref is updated even if it does not result in a fast forward update. +