--- title: "Seeing what changed in a Markdown file: git, diff tools, and readers" slug: see-what-changed-in-a-markdown-file excerpt: How to see what changed in a Markdown file, with git or without it. Line diffs, word diffs, rendered diffs, and the save habits that keep a Markdown diff small enough to read. quickAnswer: In a git project, run git diff HEAD on the file, and add --word-diff when a changed paragraph shows up as one long red and green line. Outside git, run git diff --no-index old.md new.md, or plain diff -u, on a saved copy and the new file. A rendered diff shows the changes on the formatted page instead of as raw lines. To keep diffs small, save without reformatting the whole file, keep line endings the same, and start each sentence on its own line. keyTakeaways: - git diff HEAD -- file.md shows everything that changed since the last commit. Add --word-diff to see changed words inside a long line. - You do not need a git project to diff two files. git diff --no-index old.md new.md works on any two files on disk. - Line diffs show the raw text. Rendered diffs show the changes on the formatted page. Use rendered to read, raw to check. - Most noisy Markdown diffs come from saves, not edits. Reformat-on-save, line endings and trimmed trailing spaces all add changed lines nobody meant. - Skimmark is a Markdown reader in development. Its Changes View, which shows what changed since you last looked with no git, is planned for v1. publishedDate: 2026-10-06 dateModified: 2026-10-06 author: Bobby Huang cluster: D role: pillar status: published faq: - q: How do I see what changed in a Markdown file? a: If the file is in a git project, run git diff HEAD -- path/to/file.md to see everything that changed since the last commit. Add --word-diff to see the changed words inside a long paragraph. If the file is not in git, save a copy when you finish reading and compare it with the new file later. - q: How do I diff two versions of a .md file without git? a: Run git diff --no-index old.md new.md. It works on any two files, even outside a git project, as long as git is installed. Without git, diff -u old.md new.md does the same job with line diffs only. - q: Why does my editor reformat the whole Markdown file on save? a: A formatter or a save setting is rewriting it. Common causes are format-on-save, a change of list marker or emphasis style, line wrapping, trimmed trailing spaces, and a switch between Windows and Unix line endings. Turn off format-on-save for Markdown, then save again and check the diff. - q: How do I keep Markdown git diffs small? a: Start each sentence on its own line, so an edit changes one line instead of a whole paragraph. Turn off format-on-save for Markdown. Keep one line ending style for the project. Before you commit, run git diff and check that only the lines you meant to change show up. - q: Does Skimmark use git to show changes? a: No. Skimmark is in development, and its Changes View is planned for v1. It is designed to compare the file with the copy you last marked as seen, so no git is needed. The app has no AI features. related: - how-to-review-markdown-your-ai-agents-write --- A Markdown file changed. Maybe your AI agent rewrote a plan, or a teammate edited a doc. You read it yesterday. Now you want only the new part, not the whole file again. This guide covers the ways to see that change: git, plain diff tools, and readers that show changes on the page. It also covers why some Markdown diffs are so noisy, and how to keep yours small. ## Three ways to look at a Markdown diff There are three kinds of diff you can use on a Markdown file. Each one answers a slightly different question. **A line diff** shows which lines of raw text changed. Removed lines are marked with `-` and added lines with `+`. This is what `git diff` and `diff -u` print. It is exact, and it is what you want before a commit. **A word diff** shows which words changed inside a line. This matters for Markdown, because one paragraph is often one long line. Change one word in it, and a line diff marks the whole paragraph as removed and added again. **A rendered diff** shows the changes on the formatted page. Headings look like headings, tables line up, and the changed parts are marked. It reads faster, but it can hide changes that do not show on the page, such as a space at the end of a line. ## See what changed with git If the file is tracked in a git project, git already keeps the old version for you. ### Changes since the last commit ``` git diff HEAD -- docs/plan.md ``` This shows everything that changed in the file since the last commit. Plain `git diff` without `HEAD` shows only the changes you have not staged yet. Add `--staged` to see only the staged ones. ### Changed words, not whole lines ``` git diff HEAD --word-diff -- docs/plan.md ``` Git marks removed words as `[-old-]` and added words as `{+new+}`, inside the line. For prose, this is often the easiest view to read. ### Changes across commits To see every change to one file over time, run `git log -p -- docs/plan.md`. To compare the file with how it looked one commit ago, run `git diff HEAD~1 -- docs/plan.md`. ## See what changed without git Not every Markdown file is in a git project. Agent handoffs, notes and drafts often sit in a plain folder. ### Keep a copy of what you read The simple fix is to save a copy when you finish reading: ``` cp plan.md plan.seen.md ``` That copy marks the point where you stopped. When the file changes, compare against it. When you finish reading the new version, copy it again. ### Diff two files If git is installed, it can diff any two files, even outside a git project: ``` git diff --no-index --word-diff plan.seen.md plan.md ``` Without git, the standard `diff` tool works on macOS and Linux: ``` diff -u plan.seen.md plan.md ``` The `-u` flag prints the familiar `-` and `+` format with a few lines of context. It works line by line, so long paragraphs still show as whole lines. ### Use an editor's diff view As of 2026-10-05, VS Code has a Markdown diff preview. If you already work in VS Code, that is a fine way to see changes on the formatted page. ## Why Markdown diffs get noisy A diff should show what someone meant to change. Many Markdown diffs show much more. Most of that noise comes from how a file is saved, not from what was edited. ### Reformat on save Some editors and formatters rewrite the whole file when you save. They may change every `*` list marker to `-`, switch emphasis from `*word*` to `_word_`, or wrap and unwrap long lines. The text means the same thing. The diff now marks every one of those lines as changed. ### Line endings Windows tools often save lines ending in CRLF. macOS and Linux tools use LF. If one save switches the style, every line in the file changes. Use `git diff --ignore-cr-at-eol` to hide that noise while you read. To stop it, pick one style for the project, for example with `*.md text eol=lf` in `.gitattributes`. ### Trailing spaces In Markdown, two spaces at the end of a line make a hard line break. An editor that trims trailing spaces on save removes them. If the spaces were a hard break, the rendered page loses that break. If they were stray spaces, the page does not change. Either way, the raw diff shows a changed line nobody meant to edit. A rendered diff may not show it at all, which is one reason to check raw. ### Whole-paragraph lines When a paragraph is one long line, any edit marks the whole paragraph as changed. Word diffs help you read it. Writing one sentence per line helps more, because an edit then changes only that sentence's line. Markdown renders the paragraph the same either way. ## How to keep your Markdown diffs small 1. Turn off format-on-save for Markdown files you review or share. 2. Pick one line ending style for the project and set it in `.gitattributes`. 3. Start each sentence on its own line in files you edit often. 4. Fix one line, save, then run `git diff` or `diff -u` and check that only that line changed. 5. If your editor will not leave the rest of the file alone, make small fixes in a plain text editor. If an AI agent will read the file after you, a one-line diff tells it exactly what you changed. A reformatted file hides your edit in noise. ## Where Skimmark fits Skimmark is a small Markdown reader and editor for people whose AI agents write Markdown all day. It is in development and has not been released. Two planned v1 features cover the problems in this guide: - **Changes View** highlights what changed since you last marked the file as seen. It needs no git and no saved copy. - **Edit in place** on the rendered page, with a clean Round-Trip save. Lines you did not edit stay byte-for-byte the same, so your diff shows only your change. When a clean Round-Trip cannot be guaranteed, Document Lock turns editing off instead of risking the rest of the file. The app has no AI features. It is planned for the reading and checking side of the work. ## Next read - [How to review the Markdown your AI agents write](how-to-review-markdown-your-ai-agents-write.md) Skimmark is in development. You can see what it is and follow along at [skimmark.com](https://www.skimmark.com/).