undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fetch: document local ref updates with/without --force

Browse Source 
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>
This commit is contained in:
Ævar Arnfjörð Bjarmason 2018-08-31 20:10:03 +00:00 committed by Junio C Hamano
parent fe802bd21e
commit ae6a470334
2 changed files with 37 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
Documentation/fetch-options.txt
View File

@ -49,11 +49,16 @@ endif::git-pull[]
-f::
--force::
When 'git fetch' is used with `<rbranch>:<lbranch>`
refspec, it refuses to update the local branch
`<lbranch>` unless the remote branch `<rbranch>` it
fetches is a descendant of `<lbranch>`. This option
overrides that check.
When 'git fetch' is used with `<src>:<dst>` refspec it may
refuse to update the local branch as discussed
ifdef::git-pull[]
in the `<refspec>` part of the linkgit:git-fetch[1]
documentation.
endif::git-pull[]
ifndef::git-pull[]
in the `<refspec>` part below.
endif::git-pull[]
This option overrides that check.
-k::
--keep::

32
Documentation/pull-fetch-param.txt
View File

@ -33,11 +33,33 @@ name.
it requests fetching everything up to the given tag.
+
The remote ref that matches <src>
is fetched, and if <dst> is not an empty string, the local
ref that matches it is fast-forwarded using <src>.
If the optional plus `+` is used, the local ref
is updated even if it does not result in a fast-forward
update.
is fetched, and if <dst> is not an empty string, an attempt
is made to update the local ref that matches it.
+
Whether that update is allowed without `--force` depends on the ref
namespace it's being fetched to, the type of object being fetched, and
whether the update is considered to be a fast-forward. Generally, the
same rules apply for fetching as when pushing, see the `<refspec>...`
section of linkgit:git-push[1] for what those are. Exceptions to those
rules particular to 'git fetch' are noted below.
+
Unlike when pushing with linkgit:git-push[1], any updates to
`refs/tags/*` will be accepted without `+` in the refspec (or
`--force`). The receiving promiscuously considers all tag updates from
a remote to be forced fetches.
+
Unlike when pushing with linkgit:git-push[1], any updates outside of
`refs/{tags,heads}/*` will be accepted without `+` in the refspec (or
`--force`), whether that's swapping e.g. a tree object for a blob, or
a commit for another commit that's doesn't have the previous commit as
an ancestor etc.
+
As with pushing with linkgit:git-push[1], 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.
+
[NOTE]
When the remote branch you want to fetch is known to