One Sentence Per Line: Writing Markdown That Diffs Cleanly in Git
Quick answer
Put one sentence on its own line in your Markdown source. Nothing changes about how the page renders — Markdown treats a single newline inside a paragraph as a soft break, so the sentences still flow together as one paragraph. What changes is the diff: edit one sentence, and only that line shows up as changed in git diff, instead of the whole reflowed paragraph.
This convention has a name — "semantic line breaks," sometimes just "one sentence per line" — and it isn't a Carets invention. John Gruber's original Markdown spec already treats a bare newline as a no-op, which is exactly the property that makes the technique safe. If you've read why Markdown line breaks don't show up the way you expect, you already understand the mechanism. This article is about putting it to work.
Step-by-step
Why git diffs get noisy in the first place
Git's diff algorithms — Myers is the default, with Patience, Histogram, and Minimal available via --diff-algorithm — all compare files line by line. The line, not the word or the sentence, is the unit of comparison.
That's fine for code. It's a problem for hard-wrapped prose. Take a paragraph wrapped at 80 columns:
Markdown treats a single newline as a soft break, which means you can
hard-wrap your prose at any column width and it will still render as one
continuous paragraph on the page.Now change one word in the first line — say, "soft break" to "space." Every word after it reflows, so git diff shows something like this:
-Markdown treats a single newline as a soft break, which means you can
-hard-wrap your prose at any column width and it will still render as one
-continuous paragraph on the page.
+Markdown treats a single newline as a space in the output, which means you
+can hard-wrap your prose at any column width and it will still render as
+one continuous paragraph on the page.Three lines removed, three lines added, for a two-word edit. A reviewer has to read the whole block just to find what actually changed.
Converting an existing paragraph
Take that same paragraph and rewrap it at sentence boundaries instead of column width. However long the sentence runs, it becomes a single line:
Markdown treats a single newline as a soft break, which means you can hard-wrap your prose at any column width and it will still render as one continuous paragraph on the page.There's no manual reflowing afterward — you just stop wrapping at a column count and start wrapping at a period. The one-word edit from before now touches exactly one line:
-Markdown treats a single newline as a soft break, which means you can hard-wrap your prose at any column width and it will still render as one continuous paragraph on the page.
+Markdown treats a single newline as a space in the output, which means you can hard-wrap your prose at any column width and it will still render as one continuous paragraph on the page.Still one line removed, one line added. But it's the only line now, not three, and the page reads identically either way. Nick Groenen calls this "no reflow": a change early in a paragraph no longer repositions everything after it, in the source or in the diff.
Where this pays off most
Docs, READMEs, changelogs, PR descriptions, notes tracked in Git — anywhere prose gets reviewed and revised the way code does. It also changes how granular a review can get. With one sentence per line, a collaborator can propose an edit to a single sentence in a pull request without folding unrelated changes into the same suggestion.
If you're keeping notes in a Git repository at all, for backup, history, or collaboration, pairing that with version-controlling Markdown files and one-sentence-per-line formatting is what makes the history actually readable.
Common problems and fixes
"My line broke where I didn't want it to"
You probably have two trailing spaces or a stray backslash at the end of a line. Both force a real <br /> in the rendered output — the opposite of what one-sentence-per-line writing needs. Strip the trailing whitespace and the backslash. A plain newline is the safe, invisible option.
"My editor keeps re-wrapping my sentences into one paragraph line"
Some editors auto-join or auto-format Markdown on save, collapsing your sentence breaks back into a single wrapped block. Turn off format-on-save for Markdown, or use an editor that keeps the source line breaks exactly as you typed them.
"GitHub renders my newline as a break in a PR comment but not in the file"
That's expected, not a bug. GitHub's own docs confirm the behavior is context-dependent: a bare newline auto-breaks in issue and PR comments, but inside an actual .md file in a repository it follows the standard CommonMark rule and stays a soft break. Know which context you're writing in.
"One sentence is genuinely too long for one line"
Take that as a signal, not a flaw in the convention. Wikipedia's own editing guidance documents a case where a hard-wrapped paragraph obscured a minor edit in a diff — the fix was breaking it into one line per sentence. A sentence that resists that split is usually one that should be split in two. The constraint doubles as an editing tool: an unwieldy single-line sentence is easier to spot and shorten than the same sentence buried inside a wrapped block.
Doing this with Carets
Carets renders Markdown the same way any CommonMark/GFM-compliant tool does, so writing one sentence per line in a Carets note behaves exactly as described above. The newline stays invisible on the page, and if that note lives in a Git-tracked project, the diff benefit carries straight through.
A few features make the habit easier to keep. Files, projects, and tags keep long-form docs organized as they grow past a single note, so a style guide or a running changelog doesn't turn into an unmanageable wall of text. Carets is native and fast on iPhone, iPad, and Mac, so jumping between sentence-length lines while editing doesn't feel like fighting the app. And because your notes stay plain text, they're the same portable format that makes diffing possible in the first place — no proprietary export step between what you write and what Git can compare.
Get Carets on iPhone, iPad, and Mac to write Markdown, plain text, and code the way that keeps your history — and your reviewers — honest.
Frequently Asked Questions
Does writing one sentence per line change how my Markdown looks when it renders?
No. CommonMark and GitHub Flavored Markdown both treat a single newline inside a paragraph as a soft break — it renders as a space, not a line break. A paragraph written with one sentence per line in the source renders as one continuous flowing paragraph, identical to the same text hard-wrapped at 80 columns.
How does one sentence per line actually make git diffs cleaner?
Git's diff algorithms compare files line by line, not word by word. In a hard-wrapped paragraph, editing one word can push every following word onto a different line, so the diff marks the whole block as changed. With one sentence per line, a sentence-level edit stays inside that sentence's own line, so the diff shows exactly the line that changed and nothing else.
Do I need two trailing spaces or a backslash if I'm using one sentence per line?
No — that's for the opposite case. Two trailing spaces or a backslash force a real, rendered line break. One-sentence-per-line writing relies on the newline staying invisible to the reader, so you leave sentences as plain, un-suffixed newlines.
Does this work the same way in Carets?
Yes. Carets renders Markdown files the same way any CommonMark/GFM-compliant renderer does, so a bare newline between sentences never shows up as a break in the note. If you keep your notes or code docs in a Carets project tracked with Git, the same diff benefits apply.
Is one sentence per line only useful for Git-tracked files?
The diff benefit is specific to version control, but the editorial benefit isn't — isolating each sentence on its own line makes rambling sentences and repetitive structure easier to spot even in notes you never plan to commit anywhere.