git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Ævar Arnfjörð Bjarmason  <avarab@gmail.com>
To: git@vger.kernel.org
Cc: Junio C Hamano <gitster@pobox.com>, Jeff King <peff@peff.net>,
	Stefan Beller <sbeller@google.com>,
	Ævar Arnfjörð Bjarmason  <avarab@gmail.com>
Subject: [PATCH v3 8/8] push doc: document the DWYM behavior pushing to unqualified <dst>
Date: Fri, 26 Oct 2018 23:07:41 +0000
Message-ID: <20181026230741.23321-9-avarab@gmail.com> (raw)
In-Reply-To: <20181026192734.9609-1-avarab@gmail.com>

Document the DWYM behavior that kicks in when pushing to an
unqualified <dst> reference.

This behavior was added in f88395ac23 ("Renaming push.", 2005-08-03)
and f8aae12034 ("push: allow unqualified dest refspecs to DWIM",
2008-04-23), and somewhat documented in bb9fca80ce ("git-push: Update
description of refspecs and add examples", 2007-06-09), but has never
been fully documented.

The closest we got to having documented it was the description in the
commit message for f8aae12034, which I've borrowed from in writing
this documentation.

Let's also refer to this new documentation from the existing
documentation we had (added in bb9fca80ce).

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-push.txt | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a5fc54aeab..fb95c2e395 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -73,6 +73,30 @@ be omitted--such a push will update a ref that `<src>` normally updates
 without any `<refspec>` on the command line.  Otherwise, missing
 `:<dst>` means to update the same ref as the `<src>`.
 +
+If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will
+try to infer where in `refs/*` on the destination <repository> it
+belongs based on the the type of <src> being pushed and whether <dst>
+is ambiguous.
++
+--
+* If <dst> unambiguously refers to a ref on the <repository> remote,
+  then push to that ref.
+
+* If <src> resolves to a ref starting with refs/heads/ or refs/tags/,
+  then prepend that to <dst>.
+
+* If <src> starts with refs/remotes/ check if that reference refers to
+  a commit or tag, then refs/heads/ or refs/tags/ to <dst> as
+  appropriate.
+
+* Other ambiguity resolutions might be added in the future, but for
+  now any other cases will error out with an error indicating what we
+  tried, and depending on the `advice.pushUnqualifiedRefname`
+  configuration (see linkgit:git-config[1]) suggest what refs/
+  namespace you may have wanted to push to.
+
+--
++
 The object referenced by <src> is used to update the <dst> reference
 on the remote side. Whether this is allowed depends on where in
 `refs/*` the <dst> reference lives as described in detail below, in
@@ -591,6 +615,9 @@ the ones in the examples below) can be configured as the default for
 	`refs/remotes/satellite/master`) in the `mothership` repository;
 	do the same for `dev` and `satellite/dev`.
 +
+See the section describing `<refspec>...` above for a discussion of
+the matching semantics.
++
 This is to emulate `git fetch` run on the `mothership` using `git
 push` that is run in the opposite direction in order to integrate
 the work done on `satellite`, and is often necessary when you can
-- 
2.19.1.759.g500967bb5e


  parent reply index

Thread overview: 53+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-10-10 10:41 [PATCH 0/2] add an advice on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-10-10 10:41 ` [PATCH 1/2] i18n: remote.c: mark error(...) messages for translation Ævar Arnfjörð Bjarmason
2018-10-10 20:55   ` Jeff King
2018-10-10 10:41 ` [PATCH 2/2] push: add an advice on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-10-10 20:55   ` Jeff King
2018-10-10 21:23     ` Ævar Arnfjörð Bjarmason
2018-10-11  0:16       ` Jeff King
2018-10-11 22:45       ` Junio C Hamano
2018-10-26 15:45         ` Ævar Arnfjörð Bjarmason
2018-10-29  1:00           ` Junio C Hamano
2018-10-29  4:17             ` Junio C Hamano
2018-10-26 19:27         ` [PATCH v2 0/7] fixes for " Ævar Arnfjörð Bjarmason
2018-10-26 23:07           ` [PATCH v3 0/8] " Ævar Arnfjörð Bjarmason
2018-11-02  6:52             ` Jeff King
2018-11-13 19:52             ` [PATCH v4 0/7] " Ævar Arnfjörð Bjarmason
2018-11-14  7:00               ` Junio C Hamano
2018-11-13 19:52             ` [PATCH v4 1/7] remote.c: add braces in anticipation of a follow-up change Ævar Arnfjörð Bjarmason
2018-11-13 19:52             ` [PATCH v4 2/7] i18n: remote.c: mark error(...) messages for translation Ævar Arnfjörð Bjarmason
2018-11-13 19:52             ` [PATCH v4 3/7] push: improve the error shown on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-11-13 19:52             ` [PATCH v4 4/7] push: move unqualified refname error into a function Ævar Arnfjörð Bjarmason
2018-11-13 19:52             ` [PATCH v4 5/7] push: add an advice on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-11-13 19:52             ` [PATCH v4 6/7] push: test that <src> doesn't DWYM if <dst> is unqualified Ævar Arnfjörð Bjarmason
2018-11-13 19:52             ` [PATCH v4 7/7] push doc: document the DWYM behavior pushing to unqualified <dst> Ævar Arnfjörð Bjarmason
2018-10-26 23:07           ` [PATCH v3 1/8] remote.c: add braces in anticipation of a follow-up change Ævar Arnfjörð Bjarmason
2018-10-26 23:07           ` [PATCH v3 2/8] i18n: remote.c: mark error(...) messages for translation Ævar Arnfjörð Bjarmason
2018-10-26 23:07           ` [PATCH v3 3/8] push: improve the error shown on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-10-29  5:03             ` Junio C Hamano
2018-10-26 23:07           ` [PATCH v3 4/8] push: move unqualified refname error into a function Ævar Arnfjörð Bjarmason
2018-10-26 23:07           ` [PATCH v3 5/8] push: add an advice on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-10-29  5:14             ` Junio C Hamano
2018-11-02  6:47               ` Jeff King
2018-10-26 23:07           ` [PATCH v3 6/8] push: test that <src> doesn't DWYM if <dst> is unqualified Ævar Arnfjörð Bjarmason
2018-10-29  5:19             ` Junio C Hamano
2018-10-26 23:07           ` [PATCH v3 7/8] push: add DWYM support for "git push refs/remotes/...:<dst>" Ævar Arnfjörð Bjarmason
2018-10-29  5:24             ` Junio C Hamano
2018-10-29  8:13               ` Ævar Arnfjörð Bjarmason
2018-11-01  4:18                 ` Junio C Hamano
2018-11-05 11:31                   ` Ævar Arnfjörð Bjarmason
2018-11-05 12:29                     ` Junio C Hamano
2018-10-29  7:06             ` Junio C Hamano
2018-10-29  7:57               ` Junio C Hamano
2018-10-29  8:05               ` Ævar Arnfjörð Bjarmason
2018-10-26 23:07           ` Ævar Arnfjörð Bjarmason [this message]
2018-10-26 19:27         ` [PATCH v2 1/7] remote.c: add braces in anticipation of a follow-up change Ævar Arnfjörð Bjarmason
2018-10-26 21:05           ` Stefan Beller
2018-10-26 19:27         ` [PATCH v2 2/7] i18n: remote.c: mark error(...) messages for translation Ævar Arnfjörð Bjarmason
2018-10-26 19:27         ` [PATCH v2 3/7] push: improve the error shown on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-10-26 19:27         ` [PATCH v2 4/7] push: move unqualified refname error into a function Ævar Arnfjörð Bjarmason
2018-10-26 19:27         ` [PATCH v2 5/7] push: add an advice on unqualified <dst> push Ævar Arnfjörð Bjarmason
2018-10-26 19:27         ` [PATCH v2 6/7] push: test that <src> doesn't DWYM if <dst> is unqualified Ævar Arnfjörð Bjarmason
2018-10-26 19:27         ` [PATCH v2 7/7] push: add DWYM support for "git push refs/remotes/...:<dst>" Ævar Arnfjörð Bjarmason
2018-10-10 21:54     ` [PATCH 2/2] push: add an advice on unqualified <dst> push Junio C Hamano
2018-10-11  0:19       ` Jeff King

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20181026230741.23321-9-avarab@gmail.com \
    --to=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=peff@peff.net \
    --cc=sbeller@google.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox