doc: git-push: create PUSH RULES section
Right now the rules for when a `git push` is allowed are buried at the bottom of the description of `<refspec>`. Put them in their own section so that we can reference them from `--force` and give some context for why they exist. Having the "PUSH RULES" section also lets us be a little bit more specific with the rule in `--force`: we can just focus on the rule for pushing for a branch (which is likely the one that's most relevant) and leave the details about what happens when you push to a tag or a ref that isn't a branch to the later section. Signed-off-by: Julia Evans <julia@jvns.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Julia Evans committed
Sep 23, 2025 at 18:10 UTC
cc1cc31e2a46e33941840bbb2026fff2d0532b2b
1 file changed
+45
-49
Documentation/git-push.adoc
+45
-49
@@ -91,48 +91,6 @@ is ambiguous.
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
99
-those sections "update" means any modifications except deletes, which
100
-as noted after the next few sections are treated differently.
101
-+
102
-The `refs/heads/*` namespace will only accept commit objects, and
103
-updates only if they can be fast-forwarded.
104
-+
105
-The `refs/tags/*` namespace will accept any kind of object (as
106
-commits, trees and blobs can be tagged), and any updates to them will
107
-be rejected.
108
-+
109
-It's possible to push any type of object to any namespace outside of
110
-`refs/{tags,heads}/*`. In the case of tags and commits, these will be
111
-treated as if they were the commits inside `refs/heads/*` for the
112
-purposes of whether the update is allowed.
113
-+
114
-I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*`
115
-is allowed, even in cases where what's being fast-forwarded is not a
116
-commit, but a tag object which happens to point to a new commit which
117
-is a fast-forward of the commit the last tag (or commit) it's
118
-replacing. Replacing a tag with an entirely different tag is also
119
-allowed, if it points to the same commit, as well as pushing a peeled
120
-tag, i.e. pushing the commit that existing tag object points to, or a
121
-new tag object which an existing commit points to.
122
-+
123
-Tree and blob objects outside of `refs/{tags,heads}/*` will be treated
124
-the same way as if they were inside `refs/tags/*`, any update of them
125
-will be rejected.
126
-+
127
-All of the rules described above about what's not allowed as an update
128
-can be overridden by adding an the optional leading `+` to a refspec
129
-(or using `--force` command line option). The only exception to this
130
-is that no amount of forcing will make the `refs/heads/*` namespace
131
-accept a non-commit object. Hooks and configuration can also override
132
-or amend these rules, see e.g. `receive.denyNonFastForwards` in
133
-linkgit:git-config[1] and `pre-receive` and `update` in
134
-linkgit:githooks[5].
135
-+
94
Pushing an empty <src> allows you to delete the <dst> ref from the
95
remote repository. Deletions are always accepted without a leading `+`
96
in the refspec (or `--force`), except when forbidden by configuration
@@ -145,6 +103,7 @@ the local side, the remote side is updated if a branch of the same name
103
already exists on the remote side.
104
+
105
`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
106
+Not all updates are allowed: see PUSH RULES below for the details.
107
108
--all::
109
--branches::
@@ -335,14 +294,12 @@ allowing a forced update.
294
295
-f::
296
--force::
338
- Usually, the command refuses to update a remote ref that is
339
- not an ancestor of the local ref used to overwrite it.
340
- Also, when `--force-with-lease` option is used, the command refuses
341
- to update a remote ref whose current value does not match
342
- what is expected.
297
+ Usually, `git push` will refuse to update a branch that is not an
298
+ ancestor of the commit being pushed.
299
+
344
-This flag disables these checks, and can cause the remote repository
345
-to lose commits; use it with care.
300
+This flag disables that check, the other safety checks in PUSH RULES
301
+below, and the checks in --force-with-lease. It can cause the remote
302
+repository to lose commits; use it with care.
303
+
304
Note that `--force` applies to all the refs that are pushed, hence
305
using it with `push.default` set to `matching` or with multiple push
@@ -514,6 +471,45 @@ reason::
471
refs, no explanation is needed. For a failed ref, the reason for
472
failure is described.
473
474
+PUSH RULES
475
+----------
476
+
477
+As a safety feature, the `git push` command only allows certain kinds of
478
+updates to prevent you from accidentally losing data on the remote.
479
+
480
+Because branches and tags are intended to be used differently, the
481
+safety rules for pushing to a branch are different from the rules
482
+for pushing to a tag. In the following rules "update" means any
483
+modifications except deletions and creations. Deletions and creations
484
+are always allowed, except when forbidden by configuration or hooks.
485
+
486
+1. If the push destination is a **branch** (`refs/heads/*`): only
487
+ fast-forward updates are allowed, which means the destination must be
488
+ an ancestor of the source commit. The source must be a commit.
489
+2. If the push destination is a **tag** (`refs/tags/*`): all updates will
490
+ be rejected. The source can be any object.
491
+3. If the push destination is not a branch or tag:
492
+ * If the source is a tree or blob object, any updates will be rejected
493
+ * If the source is a tag or commit object, any fast-forward update
494
+ is allowed, even in cases where what's being fast-forwarded is not a
495
+ commit, but a tag object which happens to point to a new commit which
496
+ is a fast-forward of the commit the last tag (or commit) it's
497
+ replacing. Replacing a tag with an entirely different tag is also
498
+ allowed, if it points to the same commit, as well as pushing a peeled
499
+ tag, i.e. pushing the commit that existing tag object points to, or a
500
+ new tag object which an existing commit points to.
501
+
502
+You can override these rules by passing `--force` or by adding the
503
+optional leading `+` to a refspec. The only exceptions are that no
504
+amount of forcing will make a branch accept a non-commit object,
505
+and forcing won't make the remote repository accept a push that it's
506
+configured to deny.
507
+
508
+Hooks and configuration can also override or amend these rules,
509
+see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
510
+in linkgit:git-config[1] and `pre-receive` and `update` in
511
+linkgit:githooks[5].
512
+
513
NOTE ABOUT FAST-FORWARDS
514
------------------------
515