git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Wink Saville" <wink@saville.com>,
	"Jacob Keller" <jacob.keller@gmail.com>,
	"Bryan Turner" <bturner@atlassian.com>,
	"Junio C Hamano" <gitster@pobox.com>,
	"Uwe Kleine-König" <u.kleine-koenig@pengutronix.de>,
	"Jeff King" <peff@peff.net>,
	"SZEDER Gábor" <szeder.dev@gmail.com>,
	"Kaartic Sivaraam" <kaartic.sivaraam@gmail.com>,
	"Kristian Høgsberg" <krh@redhat.com>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v4 4/6] push doc: correct lies about how push refspecs work
Date: Thu, 30 Aug 2018 20:12:42 +0000	[thread overview]
Message-ID: <20180830201244.25759-5-avarab@gmail.com> (raw)
In-Reply-To: <20180813192249.27585-1-avarab@gmail.com>

There's complex rules governing whether a push is allowed to take
place depending on whether we're pushing to refs/heads/*, refs/tags/*
or refs/not-that/*. See is_branch() in refs.c, and the various
assertions in refs/files-backend.c. (e.g. "trying to write non-commit
object %s to branch '%s'").

This documentation has never been quite correct, but went downhill
after dbfeddb12e ("push: require force for refs under refs/tags/",
2012-11-29) when we started claiming that <dst> couldn't be a tag
object, which is incorrect. After some of the logic in that patch was
changed in 256b9d70a4 ("push: fix "refs/tags/ hierarchy cannot be
updated without --force"", 2013-01-16) the docs weren't updated, and
we've had some version of documentation that confused whether <src>
was a tag or not with whether <dst> would accept either an annotated
tag object or the commit it points to.

This makes the intro somewhat more verbose & complex, perhaps we
should have a shorter description here and split the full complexity
into a dedicated section. Very few users will find themselves needing
to e.g. push blobs or trees to refs/custom-namespace/* (or blobs or
trees at all), and that could be covered separately as an advanced
topic.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-push.txt     | 41 +++++++++++++++++++++++++++++-----
 Documentation/gitrevisions.txt |  7 +++---
 2 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 55277a9781..0f03d36f1e 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -74,12 +74,41 @@ without any `<refspec>` on the command line.  Otherwise, missing
 `:<dst>` means to update the same ref as the `<src>`.
 +
 The object referenced by <src> is used to update the <dst> reference
-on the remote side.  By default this is only allowed if <dst> is not
-a tag (annotated or lightweight), and then only if it can fast-forward
-<dst>.  By having the optional leading `+`, you can tell Git to update
-the <dst> ref even if it is not allowed by default (e.g., it is not a
-fast-forward.)  This does *not* attempt to merge <src> into <dst>.  See
-EXAMPLES below for details.
+on the remote side. Whether this is allowed depends on where in
+`refs/*` the <dst> reference lives as described in detail below. Any
+such update does *not* attempt to merge <src> into <dst>. See EXAMPLES
+below for details.
++
+The `refs/heads/*` namespace will only accept commit objects, and only
+if they can be fast-forwarded.
++
+The `refs/tags/*` namespace will accept any kind of object (as
+commits, trees and blobs can be tagged), and any changes to them will
+be rejected.
++
+It's possible to push any type of object to any namespace outside of
+`refs/{tags,heads}/*`. In the case of tags and commits, these will be
+treated as if they were the commits inside `refs/heads/*` for the
+purposes of whether the update is allowed.
++
+I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*`
+is allowed, even in cases where what's being fast-forwarded is not a
+commit, but a tag object which happens to point to a new commit which
+is a fast-forward of the commit the last tag (or commit) it's
+replacing. Replacing a tag with an entirely different tag is also
+allowed, if it points to the same commit, as well as pushing a peeled
+tag, i.e. pushing the commit that existing tag object points to, or a
+new tag object which an existing commit points to.
++
+Tree and blob objects outside of `refs/{tags,heads}/*` will be treated
+the same way as if they were inside `refs/tags/*`, any modification of
+them will be rejected.
++
+All of the rules described above about what's not allowed as an update
+can be overridden by adding an the optional leading `+` to a refspec
+(or using `--force` command line option). The only exception to this
+is that no amount of forcing will make the `refs/heads/*` namespace
+accept a non-commit object.
 +
 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
 +
diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index 1f6cceaefb..d407b7dee1 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -19,9 +19,10 @@ walk the revision graph (such as linkgit:git-log[1]), all commits which are
 reachable from that commit. For commands that walk the revision graph one can
 also specify a range of revisions explicitly.
 
-In addition, some Git commands (such as linkgit:git-show[1]) also take
-revision parameters which denote other objects than commits, e.g. blobs
-("files") or trees ("directories of files").
+In addition, some Git commands (such as linkgit:git-show[1] and
+linkgit:git-push[1]) can also take revision parameters which denote
+other objects than commits, e.g. blobs ("files") or trees
+("directories of files").
 
 include::revisions.txt[]
 
-- 
2.19.0.rc1.350.ge57e33dbd1


  parent reply	other threads:[~2018-08-30 20:13 UTC|newest]

Thread overview: 101+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-04-24 19:57 Fetching tags overwrites existing tags Wink Saville
2018-04-24 23:48 ` Jacob Keller
2018-04-25  0:52 ` Junio C Hamano
2018-04-25  1:29   ` Jacob Keller
2018-04-25  1:31   ` Wink Saville
2018-04-26 19:39     ` Wink Saville
2018-04-26 22:50       ` Junio C Hamano
2018-04-26 23:24         ` Junio C Hamano
2018-04-27 18:50           ` [RFC PATCH v2] Teach remote add the --prefix-tags option Wink Saville
2018-04-27 19:08           ` Fetching tags overwrites existing tags Wink Saville
2018-04-27 19:13             ` Bryan Turner
2018-05-04 15:56               ` Jacob Keller
2018-04-28  7:26             ` Jacob Keller
2018-04-28 18:27           ` [RFC PATCH v3] Teach remote add the --remote-tags option Wink Saville
2018-04-28 19:00             ` Wink Saville
2018-04-28 21:27               ` Wink Saville
2018-05-01 16:59           ` [RFC PATCH v4 0/3] Optional sub hierarchy for remote tags Wink Saville
2018-05-01 19:24             ` Ævar Arnfjörð Bjarmason
2018-05-01 19:45               ` Jacob Keller
2018-05-01 20:34                 ` Wink Saville
2018-05-01 23:24                 ` Junio C Hamano
2018-05-02  0:08                   ` Jacob Keller
2018-05-01 23:28               ` Junio C Hamano
2018-05-01 16:59           ` [RFC PATCH v4 1/3] Teach remote add the --remote-tags option Wink Saville
2018-05-01 18:50             ` Ævar Arnfjörð Bjarmason
2018-05-08 10:26             ` Kaartic Sivaraam
2018-05-01 16:59           ` [RFC PATCH v4 2/3] Teach tag to list remote-tags Wink Saville
2018-05-01 16:59           ` [RFC PATCH v4 3/3] Test git remote add -f --remote-tags Wink Saville
2018-04-27 19:46 ` Fetching tags overwrites existing tags Ævar Arnfjörð Bjarmason
2018-04-29 20:20   ` [PATCH 0/8] "git fetch" should not clobber existing tags without --force Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 00/10] " Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 0/7] Prep for " Ævar Arnfjörð Bjarmason
2018-08-13 20:29         ` Junio C Hamano
2018-08-13 20:37           ` Ævar Arnfjörð Bjarmason
2018-08-30 20:12         ` [PATCH v4 0/6] " Ævar Arnfjörð Bjarmason
2018-08-31 20:09           ` [PATCH v5 0/9] git " Ævar Arnfjörð Bjarmason
2018-08-31 20:09           ` [PATCH v5 1/9] fetch: change "branch" to "reference" in --force -h output Ævar Arnfjörð Bjarmason
2018-08-31 20:09           ` [PATCH v5 2/9] push tests: make use of unused $1 in test description Ævar Arnfjörð Bjarmason
2018-08-31 21:07             ` Junio C Hamano
2018-08-31 22:02               ` Ævar Arnfjörð Bjarmason
2018-08-31 20:09           ` [PATCH v5 3/9] push tests: use spaces in interpolated string Ævar Arnfjörð Bjarmason
2018-08-31 20:09           ` [PATCH v5 4/9] fetch tests: add a test for clobbering tag behavior Ævar Arnfjörð Bjarmason
2018-08-31 20:10           ` [PATCH v5 5/9] push doc: remove confusing mention of remote merger Ævar Arnfjörð Bjarmason
2018-08-31 20:10           ` [PATCH v5 6/9] push doc: move mention of "tag <tag>" later in the prose Ævar Arnfjörð Bjarmason
2018-08-31 20:10           ` [PATCH v5 7/9] push doc: correct lies about how push refspecs work Ævar Arnfjörð Bjarmason
2018-08-31 20:10           ` [PATCH v5 8/9] fetch: document local ref updates with/without --force Ævar Arnfjörð Bjarmason
2018-08-31 20:10           ` [PATCH v5 9/9] fetch: stop clobbering existing tags without --force Ævar Arnfjörð Bjarmason
2018-08-30 20:12         ` [PATCH v4 1/6] fetch: change "branch" to "reference" in --force -h output Ævar Arnfjörð Bjarmason
2018-08-30 20:12         ` [PATCH v4 2/6] push tests: correct quoting in interpolated string Ævar Arnfjörð Bjarmason
2018-08-30 21:20           ` Junio C Hamano
2018-08-30 20:12         ` [PATCH v4 3/6] fetch tests: add a test for clobbering tag behavior Ævar Arnfjörð Bjarmason
2018-08-30 21:22           ` Junio C Hamano
2018-08-30 20:12         ` Ævar Arnfjörð Bjarmason [this message]
2018-08-30 21:31           ` [PATCH v4 4/6] push doc: correct lies about how push refspecs work Junio C Hamano
2018-08-30 22:34           ` Ævar Arnfjörð Bjarmason
2018-08-31 16:24             ` Junio C Hamano
2018-08-31 16:35               ` Ævar Arnfjörð Bjarmason
2018-08-30 20:12         ` [PATCH v4 5/6] fetch: document local ref updates with/without --force Ævar Arnfjörð Bjarmason
2018-08-30 20:12         ` [PATCH v4 6/6] fetch: stop clobbering existing tags without --force Ævar Arnfjörð Bjarmason
2018-08-30 21:43           ` Junio C Hamano
2018-08-13 19:22       ` [PATCH v3 1/7] fetch tests: change "Tag" test tag to "testTag" Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 2/7] push tests: remove redundant 'git push' invocation Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 3/7] push tests: fix logic error in "push" test assertion Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 4/7] push tests: add more testing for forced tag pushing Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 5/7] push tests: assert re-pushing annotated tags Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 6/7] fetch tests: correct a comment "remove it" -> "remove them" Ævar Arnfjörð Bjarmason
2018-08-13 19:22       ` [PATCH v3 7/7] pull doc: fix a long-standing grammar error Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 01/10] fetch tests: change "Tag" test tag to "testTag" Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 02/10] push tests: remove redundant 'git push' invocation Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 03/10] push tests: fix logic error in "push" test assertion Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 04/10] push tests: add more testing for forced tag pushing Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 05/10] push tests: assert re-pushing annotated tags Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 06/10] push doc: correct lies about how push refspecs work Ævar Arnfjörð Bjarmason
2018-07-31 17:40       ` Junio C Hamano
2018-08-30 14:52         ` Ævar Arnfjörð Bjarmason
2018-08-30 15:23           ` Junio C Hamano
2018-08-30 16:59             ` Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 07/10] fetch tests: correct a comment "remove it" -> "remove them" Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 08/10] fetch tests: add a test clobbering tag behavior Ævar Arnfjörð Bjarmason
2018-07-31 17:48       ` Junio C Hamano
2018-07-31 13:07     ` [PATCH v2 09/10] pull doc: fix a long-standing grammar error Ævar Arnfjörð Bjarmason
2018-07-31 13:07     ` [PATCH v2 10/10] fetch: stop clobbering existing tags without --force Ævar Arnfjörð Bjarmason
2018-07-31 18:03       ` Junio C Hamano
2018-04-29 20:20   ` [PATCH 1/8] push tests: remove redundant 'git push' invocation Ævar Arnfjörð Bjarmason
2018-04-29 20:20   ` [PATCH 2/8] push tests: fix logic error in "push" test assertion Ævar Arnfjörð Bjarmason
2018-04-29 20:20   ` [PATCH 3/8] push tests: add more testing for forced tag pushing Ævar Arnfjörð Bjarmason
2018-05-07 10:09     ` Kaartic Sivaraam
2018-05-08  2:35     ` Junio C Hamano
2018-05-08  3:19       ` Junio C Hamano
2018-05-08  9:52         ` Kaartic Sivaraam
2018-05-08 10:19     ` Kaartic Sivaraam
2018-04-29 20:20   ` [PATCH 4/8] push tests: assert re-pushing annotated tags Ævar Arnfjörð Bjarmason
2018-05-08  4:30     ` Junio C Hamano
2018-05-08 14:05     ` SZEDER Gábor
2018-04-29 20:20   ` [PATCH 5/8] push doc: correct lies about how push refspecs work Ævar Arnfjörð Bjarmason
2018-05-08  5:14     ` Junio C Hamano
2018-04-29 20:20   ` [PATCH 6/8] fetch tests: correct a comment "remove it" -> "remove them" Ævar Arnfjörð Bjarmason
2018-04-29 20:20   ` [PATCH 7/8] fetch tests: add a test clobbering tag behavior Ævar Arnfjörð Bjarmason
2018-04-29 20:21   ` [PATCH 8/8] fetch: stop clobbering existing tags without --force Ævar Arnfjörð Bjarmason
2018-05-08  5:37     ` Junio C Hamano
2018-05-01 17:11 ` Fetching tags overwrites existing tags Wink Saville

Reply instructions:

You may reply publicly 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=20180830201244.25759-5-avarab@gmail.com \
    --to=avarab@gmail.com \
    --cc=bturner@atlassian.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jacob.keller@gmail.com \
    --cc=kaartic.sivaraam@gmail.com \
    --cc=krh@redhat.com \
    --cc=peff@peff.net \
    --cc=szeder.dev@gmail.com \
    --cc=u.kleine-koenig@pengutronix.de \
    --cc=wink@saville.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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).