[PATCH 0/4] Clarifying the refspec documentation

[PATCH 0/4] Clarifying the refspec documentation

[Anders Melchiorsen]

This is a partial resend of some small updates to the git-push
refspec documentation. I have removed the parts of the patch
series that had comments last time, and will rework those later.

Meanwhile, I think that these simple modification do help in
making things more readable. Once you understand the refspec, it
is hard to realize how hard those few paragraphs are to digest.


Anders Melchiorsen (4):
  Documentation: git push repository can also be a remote
  Documentation: remove a redundant elaboration
  Documentation: mention branches rather than heads
  Documentation: avoid using undefined parameters

 Documentation/git-push.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

[PATCH 1/4] Documentation: git push repository can also be a remote

[Anders Melchiorsen]

This is copied from pull-fetch-param.txt and helps the reader
to not get stuck in the URL section.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 3321966..8bfa7cb 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -28,7 +28,9 @@ OPTIONS
 -------
 <repository>::
 	The "remote" repository that is destination of a push
-	operation.  See the section <<URLS,GIT URLS>> below.
+	operation.  This parameter can be either a URL
+	(see the section <<URLS,GIT URLS>> below) or the name
+	of a remote (see the section <<REMOTES,REMOTES>> below).
 
 <refspec>...::
 	The canonical format of a <refspec> parameter is
-- 
1.6.0.2.514.g23abd3

[PATCH 2/4] Documentation: remove a redundant elaboration

[Anders Melchiorsen]

The comment in parentheses is wrong, as one has to leave out both the
colon and <dst>. This situation is covered by the section a few lines
down:

  A parameter <ref> without a colon pushes the <ref> from the source
  repository to the destination repository under the same name.

So, just remove the parentheses.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 8bfa7cb..6d3c711 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -44,8 +44,7 @@ tip of `master` branch); see linkgit:git-rev-parse[1]) that you
 want to push.  The <dst> side represents the destination location.
 +
 The local ref that matches <src> is used
-to fast forward the remote ref that matches <dst> (or, if no <dst> was
-specified, the same ref that <src> referred to locally).  If
+to fast forward the remote ref that matches <dst>.  If
 the optional leading plus `+` is used, the remote ref is updated
 even if it does not result in a fast forward update.
 +
-- 
1.6.0.2.514.g23abd3

[PATCH 3/4] Documentation: mention branches rather than heads

[Anders Melchiorsen]

Most of the git push page talks about branches, so make it consistent
also in this paragraph.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 6d3c711..a7a6f4c 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -57,8 +57,8 @@ Pushing an empty <src> allows you to delete the <dst> ref from
 the remote repository.
 +
 The special refspec `:` (or `+:` to allow non-fast forward updates)
-directs git to push "matching" heads: for every head that exists on
-the local side, the remote side is updated if a head of the same name
+directs git to push "matching" branches: for every branch that exists on
+the local side, the remote side is updated if a branch of the same name
 already exists on the remote side.  This is the default operation mode
 if no explicit refspec is found (that is neither on the command line
 nor in any Push line of the corresponding remotes file---see below).
-- 
1.6.0.2.514.g23abd3

[PATCH 4/4] Documentation: avoid using undefined parameters

[Anders Melchiorsen]

The <ref> parameter has not been introduced, so rewrite to
avoid it.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a7a6f4c..7b27dc6 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -50,8 +50,8 @@ even if it does not result in a fast forward update.
 +
 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
 +
-A parameter <ref> without a colon pushes the <ref> from the source
-repository to the destination repository under the same name.
+A lonely <src> parameter (without a colon and a destination) pushes
+the <src> to the same name in the destination repository.
 +
 Pushing an empty <src> allows you to delete the <dst> ref from
 the remote repository.
-- 
1.6.0.2.514.g23abd3

Re: [PATCH 3/4] Documentation: mention branches rather than heads

[Junio C Hamano]

Anders Melchiorsen <mail@cup.kalibalik.dk> writes:

> Most of the git push page talks about branches, so make it consistent
> also in this paragraph.

> Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
> ---
>  Documentation/git-push.txt |    4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 6d3c711..a7a6f4c 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -57,8 +57,8 @@ Pushing an empty <src> allows you to delete the <dst> ref from
>  the remote repository.
>  +
>  The special refspec `:` (or `+:` to allow non-fast forward updates)
> -directs git to push "matching" heads: for every head that exists on
> -the local side, the remote side is updated if a head of the same name
> +directs git to push "matching" branches: for every branch that exists on
> +the local side, the remote side is updated if a branch of the same name
>  already exists on the remote side.  This is the default operation mode
>  if no explicit refspec is found (that is neither on the command line
>  nor in any Push line of the corresponding remotes file---see below).

Consistency is good, and I agree "head" may be suboptimal here as this
part tries to give formal semantics to what various refspecs do.

I first thought it would make more sense to say "ref" instead, just like
the previous paragraph that talks about :<dst> form explains it is a way
to remove a "ref".  But we do only matching branches with : syntax these
days since 098e711 ("git-push $URL" without refspecs pushes only matching
branches, 2007-07-01); I agree with the updated text for that reason, but
I think the commit log message is wrong.

Thanks.