Improve conflict marker recovery

15 files changed, 189 insertions, 95 deletions

diff --git a/compiler/rustc_parse/src/parser/diagnostics.rs b/compiler/rustc_parse/src/parser/diagnostics.rs
index c1aac84bcae..e4630bbceb9 100644
--- a/compiler/rustc_parse/src/parser/diagnostics.rs
+++ b/compiler/rustc_parse/src/parser/diagnostics.rs
@@ -2990,14 +2990,18 @@ impl<'a> Parser<'a> {
     }
 
     pub(crate) fn err_vcs_conflict_marker(&mut self) -> PResult<'a, ()> {
+        // <<<<<<<
         let Some(start) = self.conflict_marker(&TokenKind::BinOp(token::Shl), &TokenKind::Lt)
         else {
             return Ok(());
         };
         let mut spans = Vec::with_capacity(3);
         spans.push(start);
+        // |||||||
         let mut middlediff3 = None;
+        // =======
         let mut middle = None;
+        // >>>>>>>
         let mut end = None;
         loop {
             if self.token.kind == TokenKind::Eof {
@@ -3018,29 +3022,50 @@ impl<'a> Parser<'a> {
             }
             self.bump();
         }
+
         let mut err = self.dcx().struct_span_err(spans, "encountered diff marker");
-        err.span_label(start, "after this is the code before the merge");
-        if let Some(middle) = middlediff3 {
-            err.span_label(middle, "");
-        }
+        match middlediff3 {
+            // We're using diff3
+            Some(middlediff3) => {
+                err.span_label(
+                    start,
+                    "between this marker and `|||||||` is the code that we're merging into",
+                );
+                err.span_label(middlediff3, "between this marker and `=======` is the base code (what the two refs diverged from)");
+            }
+            None => {
+                err.span_label(
+                    start,
+                    "between this marker and `=======` is the code that we're merging into",
+                );
+            }
+        };
+
         if let Some(middle) = middle {
-            err.span_label(middle, "");
+            err.span_label(middle, "between this marker and `>>>>>>>` is the incoming code");
         }
         if let Some(end) = end {
-            err.span_label(end, "above this are the incoming code changes");
+            err.span_label(end, "this marker concludes the conflict region");
         }
-        err.help(
-            "if you're having merge conflicts after pulling new code, the top section is the code \
-             you already had and the bottom section is the remote code",
+        err.note(
+            "conflict markers indicate that a merge was started but could not be completed due \
+             to merge conflicts\n\
+             to resolve a conflict, keep only the code you want and then delete the lines \
+             containing conflict markers",
         );
         err.help(
-            "if you're in the middle of a rebase, the top section is the code being rebased onto \
-             and the bottom section is the code coming from the current commit being rebased",
+            "if you're having merge conflicts after pulling new code:\n\
+             the top section is the code you already had and the bottom section is the remote code\n\
+             if you're in the middle of a rebase:\n\
+             the top section is the code being rebased onto and the bottom section is the code \
+             coming from the current commit being rebased",
         );
+
         err.note(
-            "for an explanation on these markers from the `git` documentation, visit \
-             <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>",
+            "for an explanation on these markers from the `git` documentation:\n\
+             visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>",
         );
+
         Err(err)
     }
 
diff --git a/tests/ui/parser/diff-markers/enum-2.stderr b/tests/ui/parser/diff-markers/enum-2.stderr
index 20e551c2f95..b76cf5d5a01 100644
--- a/tests/ui/parser/diff-markers/enum-2.stderr
+++ b/tests/ui/parser/diff-markers/enum-2.stderr
@@ -2,20 +2,25 @@ error: encountered diff marker
   --> $DIR/enum-2.rs:3:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `|||||||` is the code that we're merging into
 LL |         x: u8,
 LL | |||||||
-   | -------
+   | ------- between this marker and `=======` is the base code (what the two refs diverged from)
 LL |         z: (),
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |         y: i8,
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/enum.stderr b/tests/ui/parser/diff-markers/enum.stderr
index be94331dce5..0ce473bc702 100644
--- a/tests/ui/parser/diff-markers/enum.stderr
+++ b/tests/ui/parser/diff-markers/enum.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/enum.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |     Foo(u8),
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     Bar(i8),
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/fn-arg.stderr b/tests/ui/parser/diff-markers/fn-arg.stderr
index aabcb826c12..24521ffa626 100644
--- a/tests/ui/parser/diff-markers/fn-arg.stderr
+++ b/tests/ui/parser/diff-markers/fn-arg.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/fn-arg.rs:3:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |         x: u8,
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |         x: i8,
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/item-with-attr.stderr b/tests/ui/parser/diff-markers/item-with-attr.stderr
index eefb2792e90..432673cd551 100644
--- a/tests/ui/parser/diff-markers/item-with-attr.stderr
+++ b/tests/ui/parser/diff-markers/item-with-attr.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/item-with-attr.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL | fn foo() {}
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL | fn bar() {}
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/item.stderr b/tests/ui/parser/diff-markers/item.stderr
index a3092ebfcfd..180c74e5d69 100644
--- a/tests/ui/parser/diff-markers/item.stderr
+++ b/tests/ui/parser/diff-markers/item.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/item.rs:1:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL | fn foo() {}
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL | fn bar() {}
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/statement.stderr b/tests/ui/parser/diff-markers/statement.stderr
index c6c6cae8765..6dccce4a48e 100644
--- a/tests/ui/parser/diff-markers/statement.stderr
+++ b/tests/ui/parser/diff-markers/statement.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/statement.rs:10:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |     S::foo();
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     S::bar();
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/struct-expr.stderr b/tests/ui/parser/diff-markers/struct-expr.stderr
index bdea8c841c6..3733cdd3496 100644
--- a/tests/ui/parser/diff-markers/struct-expr.stderr
+++ b/tests/ui/parser/diff-markers/struct-expr.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/struct-expr.rs:6:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |         x: 42,
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |         x: 0,
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/struct.stderr b/tests/ui/parser/diff-markers/struct.stderr
index 749941290cb..44f8346613e 100644
--- a/tests/ui/parser/diff-markers/struct.stderr
+++ b/tests/ui/parser/diff-markers/struct.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/struct.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |     x: u8,
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     x: i8,
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/trait-item.stderr b/tests/ui/parser/diff-markers/trait-item.stderr
index f01bbe8ba03..4361542c774 100644
--- a/tests/ui/parser/diff-markers/trait-item.stderr
+++ b/tests/ui/parser/diff-markers/trait-item.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/trait-item.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |     fn foo() {}
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     fn bar() {}
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/tuple-struct.stderr b/tests/ui/parser/diff-markers/tuple-struct.stderr
index 8dae123c96d..7fda24ba485 100644
--- a/tests/ui/parser/diff-markers/tuple-struct.stderr
+++ b/tests/ui/parser/diff-markers/tuple-struct.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/tuple-struct.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |     u8,
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     i8,
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/unclosed-delims-in-macro.stderr b/tests/ui/parser/diff-markers/unclosed-delims-in-macro.stderr
index 6995b8e6f23..927821ddfae 100644
--- a/tests/ui/parser/diff-markers/unclosed-delims-in-macro.stderr
+++ b/tests/ui/parser/diff-markers/unclosed-delims-in-macro.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/unclosed-delims-in-macro.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 ...
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     () { //
 LL | >>>>>>> 7a4f13c blah blah blah
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/unclosed-delims.rs b/tests/ui/parser/diff-markers/unclosed-delims.rs
index 653a605c28c..7d400c3827b 100644
--- a/tests/ui/parser/diff-markers/unclosed-delims.rs
+++ b/tests/ui/parser/diff-markers/unclosed-delims.rs
@@ -2,13 +2,17 @@ mod tests {
     #[test]
 <<<<<<< HEAD
 //~^ ERROR encountered diff marker
-//~| NOTE after this is the code before the merge
+//~| NOTE between this marker and `=======`
+
+//~| NOTE conflict markers indicate that
+//~| HELP if you're having merge conflicts
 //~| NOTE for an explanation on these markers
+
     fn test1() {
 =======
-//~^ NOTE
+//~^ NOTE between this marker and `>>>>>>>`
     fn test2() {
 >>>>>>> 7a4f13c blah blah blah
-//~^ NOTE above this are the incoming code changes
+//~^ NOTE this marker concludes the conflict region
     }
 }
diff --git a/tests/ui/parser/diff-markers/unclosed-delims.stderr b/tests/ui/parser/diff-markers/unclosed-delims.stderr
index d4636150e66..1eab96442b4 100644
--- a/tests/ui/parser/diff-markers/unclosed-delims.stderr
+++ b/tests/ui/parser/diff-markers/unclosed-delims.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/unclosed-delims.rs:3:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 ...
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 ...
 LL | >>>>>>> 7a4f13c blah blah blah
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error
 
diff --git a/tests/ui/parser/diff-markers/use-statement.stderr b/tests/ui/parser/diff-markers/use-statement.stderr
index 6d376166a7f..3eac7bebb5a 100644
--- a/tests/ui/parser/diff-markers/use-statement.stderr
+++ b/tests/ui/parser/diff-markers/use-statement.stderr
@@ -2,17 +2,22 @@ error: encountered diff marker
   --> $DIR/use-statement.rs:2:1
    |
 LL | <<<<<<< HEAD
-   | ^^^^^^^ after this is the code before the merge
+   | ^^^^^^^ between this marker and `=======` is the code that we're merging into
 LL |     bar,
 LL | =======
-   | -------
+   | ------- between this marker and `>>>>>>>` is the incoming code
 LL |     baz,
 LL | >>>>>>> branch
-   | ^^^^^^^ above this are the incoming code changes
+   | ^^^^^^^ this marker concludes the conflict region
    |
-   = help: if you're having merge conflicts after pulling new code, the top section is the code you already had and the bottom section is the remote code
-   = help: if you're in the middle of a rebase, the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
-   = note: for an explanation on these markers from the `git` documentation, visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
+   = note: conflict markers indicate that a merge was started but could not be completed due to merge conflicts
+           to resolve a conflict, keep only the code you want and then delete the lines containing conflict markers
+   = help: if you're having merge conflicts after pulling new code:
+           the top section is the code you already had and the bottom section is the remote code
+           if you're in the middle of a rebase:
+           the top section is the code being rebased onto and the bottom section is the code coming from the current commit being rebased
+   = note: for an explanation on these markers from the `git` documentation:
+           visit <https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_checking_out_conflicts>
 
 error: aborting due to 1 previous error