diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md
index a90b96d66b9ca1603ca2dfb5ff274895e83dcdf7..749090efc525818555017402dc28946fb5f18370 100644
--- a/doc/user/project/merge_requests/revert_changes.md
+++ b/doc/user/project/merge_requests/revert_changes.md
@@ -12,6 +12,7 @@ DETAILS:
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
You can revert individual commits or an entire merge request in GitLab.
+
When you revert a commit in Git, you create a new commit that reverses all actions
taken in the original commit. The new commit:
@@ -32,22 +33,30 @@ Prerequisites:
- Your project must use the [merge method](methods/index.md#fast-forward-merge) **Merge Commit**,
set in your project's **Settings > Merge requests**.
- [In GitLab 16.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/142152), you can revert
- fast-forwarded commits from the GitLab UI only when they are squashed, or when the
- merge request contains a single commit.
+ [In GitLab 16.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22236), you can revert
+ fast-forwarded commits from the GitLab UI if either:
-To do this:
+ - The commits are squashed, or
+ - The merge request contains a single commit.
+
+To revert merge request `Example`:
1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Code > Merge requests** and identify your merge request.
+1. Select **Code > Merge requests**.
+1. From the secondary menu, select **Merged**, and select your merge request (here, `Example`).
1. Scroll to the merge request reports area, and find the report showing the
- merge date of the merge request.
+ **Merged by** information.
1. Select **Revert**.
1. In **Revert in branch**, select the branch to revert your changes into.
-1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit.
-1. Select **Revert**.
+1. To revert immediately, without a merge request:
+ 1. Clear **Start a new merge request**.
+ 1. Select **Revert**, and the revert of `Example` is complete.
+1. To review the revert in a new merge request instead of reverting immediately,
+ select **Start a new merge request**, then:
+ 1. Fill in the fields for your revert merge request, then select **Create merge request**.
+ 1. When the merge request merges, the revert of `Example` is complete.
-The option to **Revert** is no longer shown after a merge request is reverted.
+After you revert the `Example` merge request, the option to **Revert** is no longer shown on it.
## Revert a commit
@@ -58,7 +67,7 @@ You can revert any commit in a repository into either:
Prerequisites:
-- You must have a role in the project that allows you to edit merge requests, and add
+- Your role in the project must allow you to edit merge requests, and add
code to the repository.
- The commit must not have already been reverted, as the **Revert** option is not
shown in this case.
@@ -70,7 +79,7 @@ To do this:
1. Select **Code > Merge requests**, then select your merge request.
1. Select **Commits**, then select the title of the commit you want to revert.
This displays the commit in the context of your merge request.
- 1. Below the secondary menu, the message **Viewing commit `00001111`** is shown,
+ 1. Below the secondary menu, GitLab shows the message **Viewing commit `00001111`**,
where `00001111` is the hash of the commit. Select the commit hash to show
the commit's page.
1. If you don't know the merge request the commit originated from:
@@ -78,17 +87,22 @@ To do this:
1. Select the title of the commit to display full information about the commit.
1. In the upper-right corner, select **Options**, then select **Revert**.
1. In **Revert in branch**, select the branch to revert your changes into.
-1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit.
-1. Select **Revert**.
+1. To revert immediately, without a merge request:
+ 1. Clear **Start a new merge request**.
+ 1. Select **Revert**.
+1. To review the revert in a new merge request instead of reverting immediately,
+ select **Start a new merge request**, then:
+ 1. Fill in the fields for your revert merge request, then select **Create merge request**.
+ 1. When the merge request merges, the commit revert is complete.
### Revert a merge commit to a different parent commit
-When you revert a merge commit, the branch you merged to (usually `main`) is always the
+When you revert a merge commit, the branch you merged to (often `main`) is always the
first parent. To revert a merge commit to a different parent,
you must revert the commit from the command line:
1. Identify the SHA of the parent commit you want to revert to.
-1. Identify the parent number of the commit you want to revert to. (Defaults to 1, for the first parent.)
+1. Identify the parent number of the commit you want to revert to. (Defaults to `1`, for the first parent.)
1. Run this command, replacing `2` with the parent number, and `7a39eb0` with the commit SHA:
```shell
@@ -98,15 +112,6 @@ you must revert the commit from the command line:
## Related topics
- [Official `git revert` documentation](https://git-scm.com/docs/git-revert)
-
-<!-- ## Troubleshooting
-
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that might go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
-
-Each scenario can be a third-level heading, for example `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+- [Undo changes by using Git](../../../topics/git/undo.md)
+- [Revert a commit](../../../api/commits.md#revert-a-commit) with the Commits API
+- How changelogs [handle reverted commits](../changelogs.md#reverted-commit-handling)