Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes: > diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt > index 97d3217df9..5b624caf58 100644 > --- a/Documentation/fetch-options.txt > +++ b/Documentation/fetch-options.txt > @@ -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. Ah, that's tricky. I could not locate "the `<refspec>` part" in Documentation/git-fetch.txt and was scratching my head, but it comes from pull-fetch-param.txt by inclusion ;-) > diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt > index f1fb08dc68..acb8e1a4f0 100644 > --- a/Documentation/pull-fetch-param.txt > +++ b/Documentation/pull-fetch-param.txt > @@ -33,11 +33,21 @@ 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, and the type of object being > +fetched. If it's a commit under `refs/heads/*` only fast-forwards are > +allowed. > ++ > +By having the optional leading `+` to a refspec (or using `--force` > +command line option) you can tell Git to update the local ref even if > +it is not allowed by its respective namespace clobbering rules. The above two paragraphs imply that I can "fetch +blob:refs/heads/master" to cause havoc locally? > +Before Git version 2.19 tag objects under `refs/tags/*` would not be > +protected from updates, but since then the `+` (or `--force`) syntax > +is required to clobber them. I think that is a good change; it belongs more to the b/c notes in the release notes; while I do not think it is wrong describe "it used to be that way" just after a drastic change in the immediate past, we shouldn't carry that forever, so perhaps we can leave a "NEEDSWORK: remove the 'it used to be this way' in 2020" comment around here?
