threads / patch / 17237

patch, 4 partsClarifying the refspec documentation

Subject: [PATCH 0/4] Clarifying the refspec documentation

## tl;dr

6 messages between Jan 18, 2009 and Jan 19, 2009. Diffs are folded; open one to read it.

replies: 5people: 2as markdown or json

Anders Melchiorsen· Jan 18, 2009, 14:36 UTC · lore

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(-)

Anders Melchiorsen· Jan 18, 2009, 14:36 UTC · re: Anders Melchiorsen · lore

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

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(-)

Show changes to Documentation/git-push.txt +3 −1

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

Anders Melchiorsen· Jan 18, 2009, 14:36 UTC · re: Anders Melchiorsen · lore

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

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(-)

Show changes to Documentation/git-push.txt +1 −2

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

Anders Melchiorsen· Jan 18, 2009, 14:36 UTC · re: Anders Melchiorsen · lore

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

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(-)

Show changes to Documentation/git-push.txt +2 −2

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

Anders Melchiorsen· Jan 18, 2009, 14:36 UTC · re: Anders Melchiorsen · lore

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

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(-)

Show changes to Documentation/git-push.txt +2 −2

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

Junio C Hamano· Jan 19, 2009, 03:46 UTC · re: Anders Melchiorsen · lore

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

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

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

Show 20 quoted lines

> 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.