From 95df920070f4b906237e99828b169793c331c50c Mon Sep 17 00:00:00 2001 From: Scott Taylor Date: Mon, 27 Jan 2025 08:41:16 -0600 Subject: [PATCH] docs: explain `[noeol]` conflict marker comment The meaning of `[noeol]` might not be immediately clear to a user, so it would be good to document it on our documentation page for conflicts. We may also want to improve the conflict marker comments we use for this case in the future (possibly after receiving user feedback). --- docs/conflicts.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/conflicts.md b/docs/conflicts.md index d2573f48e..53d39c6bf 100644 --- a/docs/conflicts.md +++ b/docs/conflicts.md @@ -184,3 +184,36 @@ New Heading =========== >>>>>>>>>>>>>>> Conflict 1 of 1 ends ``` + +## Conflicts with missing terminating newline (`[noeol]`) + +When materializing conflicts, `jj` outputs them in a line-based format. This +format is easiest to interpret for text files that consist of a series of lines, +with each line terminated by a newline character (`\n`). This means that a text +file should either be empty, or it should end with a newline character. + +While most text files follow this convention, some do not. To handle this case, +when `jj` encounters a missing terminating newline character in a conflict, it +will add a `[noeol]` comment to the conflict markers to indicate that the +"end-of-line" (EOL) character was missing. If you don't care about whether your +file ends with a terminating newline character, you can generally ignore this +comment and resolve the conflict normally. + +For instance, if a file originally contained `grape` with no terminating newline +character, and one person changed `grape` to `grapefruit`, while another person +added the missing newline character to make `grape\n`, the resulting conflict +would look like this: + +``` +<<<<<<< Conflict 1 of 1 ++++++++ Contents of side #1 [noeol] +grapefruit +%%%%%%% Changes from base to side #2 [-noeol] +-grape ++grape +>>>>>>> Conflict 1 of 1 ends +``` + +The `[-noeol]` comment for the diff section indicates that the base (`-`) was +missing a terminating newline character. A resolution of this conflict could be +`grapefruit\n`, with the terminating newline character added.