# [PATCH 0/4] Clarifying the refspec documentation 6 messages from 2009-01-18 to 2009-01-19. Participants: Anders Melchiorsen, Junio C Hamano. Thread: https://gitlist.dev/t/17237 ## Anders Melchiorsen, 2009-01-18 14:36 Subject: [PATCH 0/4] Clarifying the refspec documentation Message-ID: <1232289418-25627-1-git-send-email-mail@cup.kalibalik.dk> URL: https://gitlist.dev/e/1232289418-25627-1-git-send-email-mail%40cup.kalibalik.dk ``` 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, 2009-01-18 14:36 Subject: [PATCH 1/4] Documentation: git push repository can also be a remote Message-ID: <1232289418-25627-2-git-send-email-mail@cup.kalibalik.dk> URL: https://gitlist.dev/e/1232289418-25627-2-git-send-email-mail%40cup.kalibalik.dk In-Reply-To: <1232289418-25627-1-git-send-email-mail@cup.kalibalik.dk> ``` 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 --- 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 ------- :: The "remote" repository that is destination of a push - operation. See the section <> below. + operation. This parameter can be either a URL + (see the section <> below) or the name + of a remote (see the section <> below). ...:: The canonical format of a parameter is -- 1.6.0.2.514.g23abd3 ``` ## Anders Melchiorsen, 2009-01-18 14:36 Subject: [PATCH 2/4] Documentation: remove a redundant elaboration Message-ID: <1232289418-25627-3-git-send-email-mail@cup.kalibalik.dk> URL: https://gitlist.dev/e/1232289418-25627-3-git-send-email-mail%40cup.kalibalik.dk In-Reply-To: <1232289418-25627-2-git-send-email-mail@cup.kalibalik.dk> ``` The comment in parentheses is wrong, as one has to leave out both the colon and . This situation is covered by the section a few lines down: A parameter without a colon pushes the from the source repository to the destination repository under the same name. So, just remove the parentheses. Signed-off-by: Anders Melchiorsen --- 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 side represents the destination location. + The local ref that matches is used -to fast forward the remote ref that matches (or, if no was -specified, the same ref that referred to locally). If +to fast forward the remote ref that matches . 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, 2009-01-18 14:36 Subject: [PATCH 3/4] Documentation: mention branches rather than heads Message-ID: <1232289418-25627-4-git-send-email-mail@cup.kalibalik.dk> URL: https://gitlist.dev/e/1232289418-25627-4-git-send-email-mail%40cup.kalibalik.dk In-Reply-To: <1232289418-25627-3-git-send-email-mail@cup.kalibalik.dk> ``` Most of the git push page talks about branches, so make it consistent also in this paragraph. Signed-off-by: Anders Melchiorsen --- 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 allows you to delete the 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, 2009-01-18 14:36 Subject: [PATCH 4/4] Documentation: avoid using undefined parameters Message-ID: <1232289418-25627-5-git-send-email-mail@cup.kalibalik.dk> URL: https://gitlist.dev/e/1232289418-25627-5-git-send-email-mail%40cup.kalibalik.dk In-Reply-To: <1232289418-25627-4-git-send-email-mail@cup.kalibalik.dk> ``` The parameter has not been introduced, so rewrite to avoid it. Signed-off-by: Anders Melchiorsen --- 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 ` means the same as `refs/tags/:refs/tags/`. + -A parameter without a colon pushes the from the source -repository to the destination repository under the same name. +A lonely parameter (without a colon and a destination) pushes +the to the same name in the destination repository. + Pushing an empty allows you to delete the ref from the remote repository. -- 1.6.0.2.514.g23abd3 ``` ## Junio C Hamano, 2009-01-19 03:46 Subject: Re: [PATCH 3/4] Documentation: mention branches rather than heads Message-ID: <7vhc3wrm9x.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vhc3wrm9x.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1232289418-25627-4-git-send-email-mail@cup.kalibalik.dk> ``` Anders Melchiorsen writes: > Most of the git push page talks about branches, so make it consistent > also in this paragraph. > Signed-off-by: Anders Melchiorsen > --- > 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 allows you to delete the 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 : 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. ```