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@xxxxxxxxx>
---
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
