@@ -55,96 +55,66 @@ OPTIONS[[OPTIONS]]
5555
5656<refspec >... ::
5757 Specify what destination ref to update with what source object.
58- The format of a <refspec > parameter is an optional plus
59- `+` , followed by the source object <src >, followed
60- by a colon `:` , followed by the destination ref <dst >.
61- +
62- The <src > is often the name of the branch you would want to push, but
63- it can be any arbitrary "SHA-1 expression", such as `master~4` or
64- `HEAD` (see linkgit:gitrevisions[7]).
65- +
66- The <dst > tells which ref on the remote side is updated with this
67- push. Arbitrary expressions cannot be used here, an actual ref must
68- be named.
69- If `git push [<repository>]` without any `<refspec>` argument is set to
70- update some ref at the destination with `<src>` with
71- `remote.<repository>.push` configuration variable, `:<dst>` part can
72- 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 type of <src > being pushed and whether <dst >
79- is ambiguous.
8058+
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
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- +
136- Pushing an empty <src > allows you to delete the <dst > ref from the
137- remote repository. Deletions are always accepted without a leading `+`
138- in the refspec (or `--force` ), except when forbidden by configuration
139- or hooks. See `receive.denyDeletes` in linkgit:git-config[1] and
140- `pre-receive` and `update` in linkgit:githooks[5].
141- +
142- The special refspec `:` (or `+:` to allow non-fast-forward updates)
143- directs Git to push "matching" branches: for every branch that exists on
144- the local side, the remote side is updated if a branch of the same name
145- already exists on the remote side.
146- +
147- `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>` .
59+ The format for a refspec is [+]<src >[:<dst >], for example `main` ,
60+ `main:other` , or `HEAD^:refs/heads/main` .
61+ +
62+ The `<src>` is often the name of the local branch to push, but it can be
63+ any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]).
64+ +
65+ The `<dst>` determines what ref to update on the remote side. It must be the
66+ name of a branch, tag, or other ref, not an arbitrary expression.
67+ +
68+ The `+` is optional and does the same thing as `--force` .
69+ +
70+ You can write a refspec using the fully expanded form (for
71+ example `refs/heads/main:refs/heads/main` ) which specifies the exact source
72+ and destination, or with a shorter form (for example `main` or
73+ `main:other` ). Here are the rules for how refspecs are expanded,
74+ as well as various other special refspec forms:
75+ +
76+ * `<src>` without a `:<dst>` means to update the same ref as the
77+ `<src>` , unless the `remote.<repository>.push` configuration specifies a
78+ different <dst >. For example, if `main` is a branch, then the refspec
79+ `main` expands to `main:refs/heads/main` .
80+ * If `<dst>` unambiguously refers to a ref on the <repository > remote,
81+ then expand it to that ref. For example, if `v1.0` is a tag on the
82+ remote, then `HEAD:v1.0` expands to `HEAD:refs/tags/v1.0` .
83+ * If `<src>` resolves to a ref starting with `refs/heads/` or `refs/tags/` ,
84+ then prepend that to <dst >. For example, if `main` is a branch, then
85+ `main:other` expands to `main:refs/heads/other`
86+ * The special refspec `:` (or `+:` to allow non-fast-forward updates)
87+ directs Git to push "matching" branches: for every branch that exists on
88+ the local side, the remote side is updated if a branch of the same name
89+ already exists on the remote side.
90+ * <src > may contain a * to indicate a simple pattern match.
91+ This works like a glob that matches any ref matching the pattern.
92+ There must be only one * in both the `<src>` and `<dst>` .
93+ It will map refs to the destination by replacing the * with the
94+ contents matched from the source. For example, `refs/heads/*:refs/heads/*`
95+ will push all branches.
96+ * A refspec starting with `^` is a negative refspec.
97+ This specifies refs to exclude. A ref will be considered to
98+ match if it matches at least one positive refspec, and does not
99+ match any negative refspec. Negative refspecs can be pattern refspecs.
100+ They must only contain a `<src>` .
101+ Fully spelled out hex object names are also not supported.
102+ For example, `git push origin 'refs/heads/*' '^refs/heads/dev-*'`
103+ will push all branches except for those starting with `dev-`
104+ * If `<src>` is empty, it deletes the `<dst>` ref from the remote
105+ repository. For example, `git push origin :dev` will
106+ delete the `dev` branch.
107+ * `tag <tag>` expands to `refs/tags/<tag>:refs/tags/<tag>` .
108+ This is technically a special syntax for `git push` and not a refspec,
109+ since in `git push origin tag v1.0` the arguments `tag` and `v1.0`
110+ are separate.
111+ * If the refspec can't be expanded unambiguously, error out
112+ with an error indicating what was tried, and depending
113+ on the `advice.pushUnqualifiedRefname` configuration (see
114+ linkgit:git-config[1]) suggest what refs/ namespace you may have
115+ wanted to push to.
116+
117+ Not all updates are allowed: see PUSH RULES below for the details.
148118
149119-- all::
150120-- branches::
@@ -335,14 +305,12 @@ allowing a forced update.
335305
336306-f::
337307-- 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.
308+ Usually, `git push` will refuse to update a branch that is not an
309+ ancestor of the commit being pushed.
343310+
344- This flag disables these checks, and can cause the remote repository
345- to lose commits; use it with care.
311+ This flag disables that check, the other safety checks in PUSH RULES
312+ below, and the checks in -- force-with-lease. It can cause the remote
313+ repository to lose commits; use it with care.
346314+
347315Note that `--force` applies to all the refs that are pushed, hence
348316using it with `push.default` set to `matching` or with multiple push
@@ -514,6 +482,45 @@ reason::
514482 refs, no explanation is needed. For a failed ref, the reason for
515483 failure is described.
516484
485+ PUSH RULES
486+ ----------
487+
488+ As a safety feature, the `git push` command only allows certain kinds of
489+ updates to prevent you from accidentally losing data on the remote.
490+
491+ Because branches and tags are intended to be used differently, the
492+ safety rules for pushing to a branch are different from the rules
493+ for pushing to a tag. In the following rules "update" means any
494+ modifications except deletions and creations. Deletions and creations
495+ are always allowed, except when forbidden by configuration or hooks.
496+
497+ 1. If the push destination is a **branch** (`refs/heads/*` ): only
498+ fast-forward updates are allowed, which means the destination must be
499+ an ancestor of the source commit. The source must be a commit.
500+ 2. If the push destination is a **tag** (`refs/tags/*` ): all updates will
501+ be rejected. The source can be any object.
502+ 3. If the push destination is not a branch or tag:
503+ * If the source is a tree or blob object, any updates will be rejected
504+ * If the source is a tag or commit object, any fast-forward update
505+ is allowed, even in cases where what's being fast-forwarded is not a
506+ commit, but a tag object which happens to point to a new commit which
507+ is a fast-forward of the commit the last tag (or commit) it's
508+ replacing. Replacing a tag with an entirely different tag is also
509+ allowed, if it points to the same commit, as well as pushing a peeled
510+ tag, i.e. pushing the commit that existing tag object points to, or a
511+ new tag object which an existing commit points to.
512+
513+ `--force` or by adding the
514+ optional leading `+` to a refspec. The only exceptions are that no
515+ amount of forcing will make a branch accept a non-commit object,
516+ and forcing won't make the remote repository accept a push that it's
517+ configured to deny.
518+
519+ Hooks and configuration can also override or amend these rules,
520+ see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
521+ in linkgit:git-config[1] and `pre-receive` and `update` in
522+ linkgit:githooks[5].
523+
517524NOTE ABOUT FAST-FORWARDS
518525------------------------
519526
0 commit comments