diffle: Een keyboard-first diff viewer met LSP-ondersteuning en GitHub-integratie

Installatie

Je kunt diffle op verschillende manieren installeren:

Via pakketbeheerders:

  • pixi (conda-forge): pixi global install diffle
  • npm: npm install -g @moritzwilksch/diffle

Via een standalone binary (geen Node.js vereist):

  • Linux (x64, arm64, glibc) en Apple silicon macOS:

curl -fsSL https://diffle.app/install.sh | sh (Installeert standaard in ~/.local/bin. Gebruik DIFFLEINSTALLDIR om dit te wijzigen of DIFFLE_VERSION=v0.1.9 om een specifieke release vast te leggen.)

  • Windows (x64, arm64) via PowerShell:

irm https://diffle.app/install.ps1 | iex

Uitproberen zonder installatie:

  • pixi exec diffle working
  • npx @moritzwilksch/diffle working
  • nix run github:moritzwilksch/diffle -- working

Let op: Het Nix-pakket bevat gh. De varianten #web, #rust en #python bevatten daarnaast language servers.

Kiezen wat je reviewt

Gebruik de volgende commando's om te bepalen welke wijzigingen je wilt bekijken:

  • diffle: Vergelijkt HEAD met de worktree (vergelijkbaar met een standaard git diff).
  • diffle working: Vergelijkt HEAD met de worktree, inclusief staged, unstaged en untracked bestanden.
  • diffle develop: Toont wat de huidige branch heeft toegevoegd sinds deze is afgesplitst van develop.
  • diffle pr 27: Opent GitHub PR 27 (of gebruik de URL). Zonder nummer wordt de PR van de huidige branch geopend.
  • diffle show a1b2c3d: Toont één specifieke commit (vergelijkbaar met git show).
  • diffle main..feat: Ondersteunt elke git-diff revspec: <rev> | a..b | a...b | a b.
  • diffle main..worktree: Hierbij staat "worktree" voor de niet-gecommitteerde boom aan weerszijden.
  • diffle range-diff main..v1 main..v2: Toont hoe een reeks commits is herwerkt (vergelijkbaar met git range-diff).
  • diffle --help: Toont alle beschikbare commando's en vlaggen.

Belangrijke opmerkingen:

  • Voor diffle pr is een GitHub-token vereist. PR's van andere repositories worden geopend in een tijdelijke clone.
  • Het sluiten van het laatste diffle-tabblad stopt de server en print de openstaande commentaren. Gebruik --keep-alive om de server actief te houden.

Reviewen

Sneltoetsen

  • j / k: Volgende of vorige regel (10j voor tien regels naar beneden).
  • J / K: Volgende of vorige bestand.
  • ] / [: Volgende of vorige hunk.
  • c: Commentaar toevoegen.
  • C: Commentaar toevoegen aan het hele bestand.
  • V: Een blok selecteren.
  • R: Markeren als opgelost (resolve).
  • v: Markeren als bekeken.
  • /: Zoeken in het huidige bestand.
  • g/: Zoeken in alle gewijzigde bestanden.
  • gf: Bestanden filteren.
  • F: Het volledige bestand openen.
  • Ctrl+o: Teruggaan.
  • yy: Alle commentaren kopiëren.
  • ?: Volledige lijst met sneltoetsen tonen.

Werking van commentaren

Bij een vergelijking worden de commits boven de threads weergegeven. Je kunt een specifieke commit kiezen, of navigeren met < en > om commits individueel te bekijken. "All changes" keert terug naar het volledige bereik. Commentaren op een gefocuste commit horen bij die specifieke commit.

Commentaren worden opgeslagen in <git-dir>/diffle/ en beïnvloeden de worktree niet. Ze volgen de tekst bij wijzigingen in de code en worden ongeldig zodra de code uit de diff verdwijnt.

Gegenereerde bestanden

Gegenereerde bestanden zijn standaard ingeklapt (zoals op GitHub). Bestanden gemarkeerd als linguist-generated in .gitattributes worden herkend; dit kan worden uitgeschakeld met linguist-generated=false. Andere bestanden kunnen via de instellingen of diffle config worden toegevoegd aan de lijst met automatisch ingeklapte bestanden.

Commentaren naar GitHub verzenden

Via het pull request-icoon kun je één thread, of alle openstaande threads, toevoegen aan een concept-review (pending review) op de PR. diffle verzendt de review nooit definitief; het bewerken, verwijderen en indienen van de commentaren gebeurt handmatig op GitHub. Als een thread opnieuw wordt toegevoegd, wordt het bestaande commentaar bijgewerkt in plaats van gedupliceerd.

Voorwaarden voor export:

  • De vergelijking moet exact overeenkomen met de gecommitteerde diff van de PR. Niet-gepushte commits of wijzigingen in de worktree blokkeren de export.
  • Verouderde (stale) threads worden overgeslagen.
  • diffle zoekt naar een token in de volgende volgorde: GITHUBTOKEN, GHTOKEN, of een ingelogde gh sessie. Zonder token blijven alle functies, behalve de GitHub-integratie, werken.
  • GITHUBAPIURL kan worden gebruikt om diffle naar een andere GitHub API te sturen (bijv. in Actions).

Navigeren naar definities (LSP)

diffle start een language server (LSP) voor elke taal in de diff, mits deze in de PATH wordt gevonden.

Navigatie:

  • gd of Ctrl/Cmd+click: Ga naar definitie.
  • gy: Ga naar type-definitie.
  • gA: Toon referenties.
  • gs / gS: Bestands- of repository-symbolen.
  • gh: Hover-informatie, inclusief schema-documentatie voor JSON, YAML en TOML.
  • w / b / 0 / $: Navigeren door symbolen in een regel. Het symbool onder de cursor wordt overal in het bestand gemarkeerd (onderscheid maakt tussen schrijven en lezen).

Resultaten buiten de diff (zoals de standaardbibliotheek) worden in read-only modus geopend. Grote repositories kunnen enige tijd nodig hebben voor indexering.

LSP Beheer: Gebruik diffle lsp om te zien welke server per taal wordt gebruikt.

  • Server overschrijven of uitschakelen:
  • Permanent: diffle config set-lsp rust "rust-analyzer"
  • Uitschakelen voor specifieke taal: diffle config set-lsp java ""
  • Terugzetten naar standaard (PATH): diffle config unset-lsp rust
  • Alleen voor deze run: diffle working --lsp python="pyrefly lsp"
  • Alles uitschakelen: diffle working --no-lsp

Language servers draaien via een shell binnen de repository en hebben toegang tot alles waar de huidige gebruiker toegang toe heeft.

Shell-aanvullingen (Completions)

Installeer completions voor jouw shell:

  • Bash: diffle completion --shell bash > ~/.local/share/bash-completion/completions/diffle
  • Zsh: diffle completion --shell zsh > ~/.local/share/zsh/site-functions/_diffle
  • Fish: diffle completion --shell fish > ~/.config/fish/completions/diffle.fish

Voer dit opnieuw uit na een upgrade om nieuwe commando's te synchroniseren. Revisions worden niet aangevuld.

Gebruik achter een reverse proxy

diffle ondersteunt path-prefixes (bijv. https://proxy.example/diffle/) zonder extra configuratie. De proxy moet het prefix verwijderen, inclusief voor WebSocket-upgrades op /diffle/ws, en de publieke origin vertrouwen:

diffle working -H 0.0.0.0 --no-open --allowed-origin https://proxy.example

Indien de proxy de Host en Origin herschrijft naar een upstream-adres (zoals een Kubernetes service naam), vertrouw dan dat specifieke adres. Een geweigerd verzoek resulteert in een 403-fout waarin het problematische header wordt genoemd.

Ontwikkeling

Basiscommando's:

  • npm install
  • npm run dev -- working
  • npm test && npm run typecheck && npm run build

Herstart npm run dev na wijzigingen aan de client; de server serveert vanuit dist/client.

Tests en Fixtures: npm run fixture -- <dir> bouwt de repository die de tests reviewen (inclusief renames, binaries, CRLF, etc.). Screenshot-tests draaien in Docker om overeenkomst met CI te garanderen:

  • npm run test:e2e:docker: De browser-suite.
  • npm run test:e2e:docker -- -g search: Specifieke scenario's.
  • npm run test:e2e:report: Open het laatste rapport.
  • npm run test:e2e:docker:update: Nieuwe screenshots accepteren.

Zie AGENTS.md voor meer details.

Erkenningen

  • diffle is geïnspireerd door difit.
  • Diffs worden gerenderd met @pierre/diffs.