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).
This commit is contained in:
Scott Taylor 2025-01-27 08:41:16 -06:00 committed by Scott Taylor
parent 3293a1aa97
commit 95df920070

View file

@ -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.