[Feature] olcli diff — preview content-level changes before push

[Waynting]

Feature proposal: olcli diff — preview content-level changes before push

Hi! First off, thanks for building olcli — the git remote helper alone has made my Overleaf workflow so much better.

I searched existing issues and didn't find a prior proposal for this.

So I'd like to propose a new command, and I'm happy to lead the implementation myself if you think it fits the project's direction.

Motivation

olcli push --dry-run shows which files would change, but not what changed inside them. Two scenarios where content-level diff matters:

1. Pre-push sanity check — before pushing, see exactly what edits will land on Overleaf (similar to reviewing git diff before committing).
2. Academic review workflow — a very common situation: a student revises a thesis locally and wants to show their advisor what changed. Overleaf's web history is limited (especially on free plans) and isn't reviewer-friendly. A marked-up diff PDF (via latexdiff) is the standard way journals and advisors expect to see revisions.

Proposed design

Core command (no external dependencies)

olcli diff [project] [dir]

• Compares local files against the current remote version
• Outputs a unified diff to stdout (colorized when TTY)
• Reuses the existing .olcli.json manifest to determine which files to compare, so it only fetches remote content for files that differ
• --name-only to list changed files, --file <path> to diff a single file

Optional latexdiff integration (opt-in flags)

olcli diff --latexdiff [--pdf]

• If latexdiff is available on PATH, generate a marked-up .tex (deletions struck through in red, additions underlined in blue)
• With --pdf, compile the marked-up file via Overleaf's remote compiler (reusing the existing compile machinery) — so users without a local TeX installation still get a reviewable PDF
• Gracefully degrades with a clear message if latexdiff isn't installed

Implementation sketch

• Text diffing via the diff npm package (or similar) — no new heavy deps
• Remote file contents fetched through the existing OverleafClient methods
• Binary files (images, PDFs) reported as "binary files differ" only
• Respects the existing ignore layers (.olignore etc.)

Out of scope (for now)

Keeping the first iteration small on purpose. Possible follow-ups if there's interest: diffing between two points in time via the git remote helper, tagging "review checkpoints", auto-creating a review project on Overleaf.

Questions for you

1. Does this fit how you see olcli evolving?
2. Any preference on the diff library, or constraints on new dependencies?
3. Would you prefer the latexdiff integration split into a separate PR?

If this sounds good, I'll start with a draft PR for the core olcli diff command. Thanks!

[aloth]

Thanks, this is a well-argued proposal and the second use case is the one that convinces me. Overleaf's own history is not built for handing a supervisor a reviewable set of changes, and latexdiff output is what advisors and journals actually expect. That is a real gap.

Answering your three questions directly:

1. Does it fit? Yes. It sits on the same line as the git remote helper: making Overleaf work inside review workflows people already have, rather than asking them to move into the web editor.

2. Diff library. The bar is low dependency count, not zero. diff is fine if the core command needs it. What I would rather avoid is anything pulling a transitive tree.

3. Split latexdiff out? Yes, please. The core command is text processing over data we already fetch. --latexdiff shells out to an external binary and --pdf sends files to the remote compiler. Different risk, different review. Land the core first.

One design question your sketch does not settle, and it matters more than the library choice: what is "remote"? The project can change between a pull and a later diff. If diff fetches fresh, it shows the truth but may disagree with what a subsequent push overwrites. If it compares against the last pulled state, it is fast and stable but can be stale. Either is defensible; the command needs to state which one it does, because a diff that does not describe what the push will overwrite is worse than no diff.

Two smaller notes for the core command:

• --name-only overlaps with what push --dry-run already reports. Worth checking whether they should share a code path or whether one should defer to the other.
• Please keep the binary handling you proposed. Reporting "binary files differ" is right; attempting anything smarter on PDFs and images is a rabbit hole.

Go ahead with the draft PR for the core command whenever you are ready.

[Waynting]

Draft PR is up: #48 — core command only, no latexdiff and no --pdf, as agreed.

On the design question you raised. diff fetches the remote fresh on every run, and the command states that in --help and in its own output footer. That turned out to be settled by the data model rather than by preference: .olcli.json records remote paths, never remote contents, so there is no stored snapshot to compare against — "diff against the last pull" would have meant designing a content cache rather than reusing one. Fetching fresh is also what makes the diff describe what a subsequent push will overwrite, which is the point of the command.

I should correct my own sketch above while I'm at it: I wrote that it would only fetch remote content for files that differ. That isn't possible — you can't know which files differ without fetching them — and it isn't necessary, because downloadProject already returns the whole project as a single archive. Fetching fresh costs one request, not one per file. The one thing it can't promise is a collaborator editing between diff and push, so every run prints the fetch time.

On --name-only overlapping push --dry-run. I kept the behaviour separate, because the two measure different things: push --dry-run selects by modification time (that's what push actually uploads), diff by content. A file touched but not edited appears in the first and not the second, so merging them would make one of them lie. What they genuinely do share is the local walk-and-filter loop — which already existed twice, in push and in sync, with the two copies drifted. That moves to src/scan.ts and all three now call it. For the discoverability side of the overlap, push --dry-run now says what it measures and points at olcli diff.

Binary files are reported as Binary files ... differ and nothing more, as you asked.

One thing I added that wasn't in the proposal: both sides pass through the same ignore layers, otherwise output.pdf and every stray .aux on Overleaf shows up as a local deletion on every run. A freshly pulled directory now diffs to "No differences", which is the check that the two sides agree.

The rest of the decisions are in the PR description. It's in draft — happy to change anything before I mark it ready.

[aloth]

Shipped in v0.10.0.

olcli diff                 # every changed file, as patches
olcli diff --name-only     # just the changed paths, with A/M/D prefixes
olcli diff --file main.tex # one file
olcli diff -U 8            # wider context

Also available as the diff_project MCP tool, so an assistant can preview a push without shelling out to the CLI.

Implemented by @Waynting in #48. Thanks for the proposal and for the implementation - the design question about what "remote" means was settled properly rather than papered over, and the --name-only overlap with push --dry-run was left as a real difference instead of merged away.

latexdiff support (--latexdiff, --pdf) was deliberately left out of that PR and is still open as follow-up work.