freshlybakedca.ke
Git fork
Merge branch 'je/doc-push'
Doc updates.
* je/doc-push:
doc: git-push: rewrite refspec specification
doc: git-push: create PUSH RULES section
+98
-91
+98
-91
Documentation/git-push.adoc
+98
-91
Documentation/git-push.adoc
···
55
55
56
56
<refspec>...::
57
57
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
58
+
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]).
59
+
The format for a refspec is [+]<src>[:<dst>], for example `main`,
60
+
`main:other`, or `HEAD^:refs/heads/main`.
65
61
+
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>`.
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]).
75
64
+
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.
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.
80
67
+
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
-
--
68
+
The `+` is optional and does the same thing as `--force`.
95
69
+
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.
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:
101
75
+
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>`.
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.
148
118
149
119
--all::
150
120
--branches::
···
335
305
336
306
-f::
337
307
--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.
343
310
+
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.
346
314
+
347
315
Note that `--force` applies to all the refs that are pushed, hence
348
316
using it with `push.default` set to `matching` or with multiple push
···
513
481
A human-readable explanation. In the case of successfully pushed
514
482
refs, no explanation is needed. For a failed ref, the reason for
515
483
failure is described.
484
+
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
+
You can override these rules by passing `--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].
516
523
517
524
NOTE ABOUT FAST-FORWARDS
518
525
------------------------