Document the actual behavior of remote push mirroring

The documentation of remote push mirroring doesn't reflect the actual
behavior of the feature. The documentation describes that by default the
mirroring would fail if there are any diverged refs in the mirror. This
doesn't match reality and the mirroring functionality by default force
pushes over the refs in the mirror. The keep divergent refs option then
actually avoids force pushing over the diverged refs but has no effect
on non-diverged refs.

app/views/projects/mirrors/_mirror_repos_push.html.haml

@@ -11,5 +11,5 @@
     = check_box_tag :keep_divergent_refs, '1', false, class: 'js-mirror-keep-divergent-refs form-check-input'
     = label_tag :keep_divergent_refs, _('Keep divergent refs'), class: 'form-check-label'
     .form-text.text-muted
-      = _('By default, if any ref (branch, tag, or commit) on the remote mirror has diverged from the local repository, the entire push will fail, and nothing will be updated. Choose this option to override this behavior. After the mirror is created, this can only be modified via the API.')
-      = link_to _('Learn more.'), help_page_path('user/project/repository/repository_mirroring', anchor: 'keep-divergent-refs'), target: '_blank', rel: 'noopener noreferrer'
+      - link_opening_tag = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe
+      = html_escape(_('Do not force push over diverged refs. After the mirror is created, this setting can only be modified using the API. %{mirroring_docs_link_start}Learn more about this option%{link_closing_tag} and %{mirroring_api_docs_link_start}the API.%{link_closing_tag}')) % { mirroring_docs_link_start: link_opening_tag % {url: help_page_path('user/project/repository/repository_mirroring', anchor: 'keep-divergent-refs')}, mirroring_api_docs_link_start: link_opening_tag % {url: help_page_path('api/remote_mirrors')}, link_closing_tag: '</a>'.html_safe }

doc/user/project/repository/repository_mirroring.md

@@ -92,19 +92,18 @@ You can also create and modify project push mirrors through the
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0.
 
-By default, if any ref on the remote mirror has diverged from the local
-repository, the *entire push* fails, and no updates occur.
+By default, if any ref (branch or tag) on the remote mirror has diverged from the local repository, the local differences are forced to the remote.
 
-For example, if a repository has `main`, `develop`, and `stable` branches that
+For example, if a repository has `main` and `develop` branches that
 have been mirrored to a remote, and then a new commit is added to `develop` on
-the mirror, the next push attempt fails, leaving `main` and `stable`
-out-of-date despite not having diverged. No change on any branch can be mirrored
-until the divergence is resolved.
+the remote mirror. The next push updates all of the references on the remote mirror to match
+the local repository, and the new commit added to the remote `develop` branch is lost.
 
 With the **Keep divergent refs** option enabled, the `develop` branch is
-skipped, allowing `main` and `stable` to be updated. The mirror status
-reflects that `develop` has diverged and was skipped, and be marked as a failed
-update.
+skipped, causing only `main` to be updated. The mirror status
+reflects that `develop` has diverged and was skipped, and be marked as a
+failed update. Refs that exist in the mirror repository but not in the local
+repository are left untouched.
 
 NOTE:
 After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md).

locale/gitlab.pot

@@ -5781,9 +5781,6 @@ msgstr ""
 msgid "By default, all projects and groups will use the global notifications setting."
 msgstr ""
 
-msgid "By default, if any ref (branch, tag, or commit) on the remote mirror has diverged from the local repository, the entire push will fail, and nothing will be updated. Choose this option to override this behavior. After the mirror is created, this can only be modified via the API."
-msgstr ""
-
 msgid "ByAuthor|by"
 msgstr ""
 
@@ -11657,6 +11654,9 @@ msgstr ""
 msgid "Do not display offers from third parties"
 msgstr ""
 
+msgid "Do not force push over diverged refs. After the mirror is created, this setting can only be modified using the API. %{mirroring_docs_link_start}Learn more about this option%{link_closing_tag} and %{mirroring_api_docs_link_start}the API.%{link_closing_tag}"
+msgstr ""
+
 msgid "Do you want to remove this deploy key?"
 msgstr ""