fetch: document local ref updates with/without --force
Refer to the new git-push(1) documentation about when ref updates are and aren't allowed with and without --force, noting how "git-fetch" differs from the behavior of "git-push". Perhaps it would be better to split this all out into a new gitrefspecs(7) man page, or present this information using tables. In lieu of that, this is accurate, and fixes a big omission in the existing refspec docs. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Aug 31, 2018 at 20:10 UTC
ae6a470334d7d0e086e289f0c7e492e3366b66aa
2 files changed
+37
-10
Documentation/fetch-options.txt
+10
-5
@@ -49,11 +49,16 @@ endif::git-pull[]
49
50
-f::
51
--force::
52
- When 'git fetch' is used with `<rbranch>:<lbranch>`
53
- refspec, it refuses to update the local branch
54
- `<lbranch>` unless the remote branch `<rbranch>` it
55
- fetches is a descendant of `<lbranch>`. This option
56
- overrides that check.
52
+ When 'git fetch' is used with `<src>:<dst>` refspec it may
53
+ refuse to update the local branch as discussed
54
+ifdef::git-pull[]
55
+ in the `<refspec>` part of the linkgit:git-fetch[1]
56
+ documentation.
57
+endif::git-pull[]
58
+ifndef::git-pull[]
59
+ in the `<refspec>` part below.
60
+endif::git-pull[]
61
+ This option overrides that check.
62
63
-k::
64
--keep::
Documentation/pull-fetch-param.txt
+27
-5
@@ -33,11 +33,33 @@ name.
33
it requests fetching everything up to the given tag.
34
+
35
The remote ref that matches <src>
36
-is fetched, and if <dst> is not an empty string, the local
37
-ref that matches it is fast-forwarded using <src>.
38
-If the optional plus `+` is used, the local ref
39
-is updated even if it does not result in a fast-forward
40
-update.
36
+is fetched, and if <dst> is not an empty string, an attempt
37
+is made to update the local ref that matches it.
38
++
39
+Whether that update is allowed without `--force` depends on the ref
40
+namespace it's being fetched to, the type of object being fetched, and
41
+whether the update is considered to be a fast-forward. Generally, the
42
+same rules apply for fetching as when pushing, see the `<refspec>...`
43
+section of linkgit:git-push[1] for what those are. Exceptions to those
44
+rules particular to 'git fetch' are noted below.
45
++
46
+Unlike when pushing with linkgit:git-push[1], any updates to
47
+`refs/tags/*` will be accepted without `+` in the refspec (or
48
+`--force`). The receiving promiscuously considers all tag updates from
49
+a remote to be forced fetches.
50
++
51
+Unlike when pushing with linkgit:git-push[1], any updates outside of
52
+`refs/{tags,heads}/*` will be accepted without `+` in the refspec (or
53
+`--force`), whether that's swapping e.g. a tree object for a blob, or
54
+a commit for another commit that's doesn't have the previous commit as
55
+an ancestor etc.
56
++
57
+As with pushing with linkgit:git-push[1], all of the rules described
58
+above about what's not allowed as an update can be overridden by
59
+adding an the optional leading `+` to a refspec (or using `--force`
60
+command line option). The only exception to this is that no amount of
61
+forcing will make the `refs/heads/*` namespace accept a non-commit
62
+object.
63
+
64
[NOTE]
65
When the remote branch you want to fetch is known to