path: root/Documentation/git-push.txt
diff options
authorÆvar Arnfjörð Bjarmason <>2018-11-13 19:52:45 (GMT)
committerJunio C Hamano <>2018-11-14 06:27:56 (GMT)
commit2219c09e23c39aed7c869c1f4dda28aec46da984 (patch)
treeb90be899ea7c9fd01bf7a23fae593d7b16a7f8ff /Documentation/git-push.txt
parentbf70636fd7b9014e7320260b0221c84061447917 (diff)
push doc: document the DWYM behavior pushing to unqualified <dst>
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 <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-push.txt')
1 files changed, 23 insertions, 0 deletions
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index a5fc54a..6a8a0d9 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -73,6 +73,26 @@ 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>.
+* 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 +611,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