Skip to content

v0.13.0 - Marked-up revisions, and diff as a CI gate

Latest
Latest

Choose a tag to compare

View all tags
@aloth aloth released this 11 Sep 08:57
v0.13.0
8093e8d

Added

olcli diff --latexdiff marks the revision up inside the document (#55)

olcli diff --latexdiff          # write .olcli-diff/main-diff.tex
olcli diff --latexdiff --pdf    # ...and compile it, download the PDF

A unified diff is the right artifact for a developer and the wrong one for a thesis advisor, who expects deletions struck through and additions underlined. It runs on the two sides diff has already fetched, so the markup describes exactly what the patch output does: struck through is what a push would overwrite, underlined is what it would upload. It costs no extra request.

  • Requires latexdiff on PATH, which ships with TeX Live and MacTeX. A missing binary is reported as a setup problem with the install command for your platform, not as a failure of diff
  • \input and \include are inlined before comparing, with --no-flatten to opt out. Without it a remote compile resolves those against the files in the project - the old content - and produces a PDF marking up the root document while showing every input file as unchanged
  • Output goes to .olcli-diff/, dotted because scanLocalFiles skips dotted entries before any ignore rule is consulted. A plain main-diff.tex next to the document would be uploaded by the next push
  • The root document is the .tex file declaring \documentclass. Several candidates are listed rather than resolved by preferring main.tex
  • --latexdiff-opt passes options straight through: --latexdiff-opt --math-markup=0

--pdf compiles the marked-up document on Overleaf, so a reviewable PDF needs no local TeX installation - the reason the flag was proposed in #45.

Overleaf's compile endpoint takes a path that must already be in the project; there is no way to compile a document that is not. So the markup is uploaded as olcli-latexdiff.tex next to the root document, compiled, downloaded, and removed. That is a real mutation of the project for the duration of one compile, and the command says so before it does it.

It refuses rather than overwrites if a file of that name already exists, deletes from a finally with nothing in between able to terminate the process first, and prints the exact olcli rm command if the delete fails or the run is interrupted.

olcli diff --exit-code makes the command a CI gate (#48)

olcli diff --exit-code             # 0 same, 1 differs, 2 failed
olcli diff --exit-code --name-only # the shape a pipeline usually wants
- name: Fail if the paper on Overleaf has drifted from the repo
  run: olcli diff --exit-code --name-only
  env:
    OVERLEAF_SESSION: ${{ secrets.OVERLEAF_SESSION }}

It reports diff(1)'s statuses. The 1 versus 2 split is the whole feature: a pipeline that cannot separate "the project differs" from "the run failed" reads an expired session cookie as a content change, and a job that goes red for the wrong reason sends whoever reads the log looking for a diff that was never computed. All ten failure paths move to 2 together.

Without the flag every failure stays 1, which is what every other command exits, so existing scripts are unaffected.

The status is set rather than exited on. process.exit discards whatever is still buffered on a non-TTY stdout, and olcli diff --exit-code > patch.txt is exactly a large patch going into a pipe.

Upgrading

npm i -g @aloth/olcli@0.13.0   # or: brew upgrade olcli

--latexdiff needs latexdiff on PATH. Everything else works without it, unchanged.

No configuration changes. No existing command changes behavior. Requires Node 20.18.1 or newer, unchanged from 0.12.0.

Contributors

Full changelog: https://github.com/aloth/olcli/blob/main/CHANGELOG.md

Assets 2
Loading