@matheusbsbs / matheus-bagliano / commits / 2219c09e23

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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Ævar Arnfjörð Bjarmason committed Nov 13, 2018 at 19:52 UTC 2219c09e23c39aed7c869c1f4dda28aec46da984
1 file changed +23
Documentation/git-push.txt
+23
@@ -73,6 +73,26 @@ be omitted--such a push will update a ref that `<src>` normally updates
73 without any `<refspec>` on the command line. Otherwise, missing
74 `:<dst>` means to update the same ref as the `<src>`.
75 +
76 +If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will
77 +try to infer where in `refs/*` on the destination <repository> it
78 +belongs based on the the type of <src> being pushed and whether <dst>
79 +is ambiguous.
80 ++
81 +--
82 +* If <dst> unambiguously refers to a ref on the <repository> remote,
83 + then push to that ref.
84 +
85 +* If <src> resolves to a ref starting with refs/heads/ or refs/tags/,
86 + then prepend that to <dst>.
87 +
88 +* Other ambiguity resolutions might be added in the future, but for
89 + now any other cases will error out with an error indicating what we
90 + tried, and depending on the `advice.pushUnqualifiedRefname`
91 + configuration (see linkgit:git-config[1]) suggest what refs/
92 + namespace you may have wanted to push to.
93 +
94 +--
95 ++
96 The object referenced by <src> is used to update the <dst> reference
97 on the remote side. Whether this is allowed depends on where in
98 `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
611 `refs/remotes/satellite/master`) in the `mothership` repository;
612 do the same for `dev` and `satellite/dev`.
613 +
614 +See the section describing `<refspec>...` above for a discussion of
615 +the matching semantics.
616 ++
617 This is to emulate `git fetch` run on the `mothership` using `git
618 push` that is run in the opposite direction in order to integrate
619 the work done on `satellite`, and is often necessary when you can