Utiliser Diff Anything en ligne de commande, avec Git et en CI

Rechercher l’exécutable installé

Le binaire du bureau utilise --cli pour les opérations en ligne de commande afin qu’un lancement ordinaire reste graphique. Une installation Microsoft Store déclare l’alias d’exécution diff-anything.exe ; Les utilisateurs de Windows peuvent l’exécuter lorsque cet alias est activé dans les alias d’exécution d’application.

La version du Mac App Store s’exécute dans l’App Sandbox d’Apple : son propre exécutable ne peut donc pas lire les fichiers indiqués sur une ligne de commande. Lancé depuis le Terminal, il indique d’installer l’outil en ligne de commande et quitte avec le code 2. Installez l’outil en ligne de commande gratuit de Diff Anything, un programme d’installation signé et notarié proposé sur ce site, et non sur le Mac App Store, pour les Mac Apple silicon et Intel sous macOS 13 ou version ultérieure. Il installe diff-anything dans /usr/local/bin : chaque commande, paramètre Git et manifeste de lot de ce guide fonctionne donc sans changement. L’outil n’a pas besoin de --cli mais l’accepte.

L’outil dispose de Pro lorsque Pro a été acheté ou restauré dans l’application Diff Anything sur le même Mac, sous le même utilisateur macOS ; ouvrez l’application une fois après l’achat ou la restauration. Sans Pro, il fonctionne comme la CLI gratuite, avec 10 comparaisons par jour comptées séparément. Il n’utilise jamais le réseau.

• Windows: diff-anything.exe --cli left.json right.json
• Mac, avec l’outil installé : diff-anything --cli left.json right.json
• Vérifiez la version installée : diff-anything --cli --version
• Mac : which -a diff-anything indique quel diff-anything s’exécute en premier, et diff-anything --pro-status indique si Pro a été trouvé

Télécharger l’outil en ligne de commande pour Mac →

Passer en mode explicite CLI

Fournissez deux chemins source et choisissez éventuellement --mode auto|text|json|yaml|toml|ini|plist|xml|csv|env|http|api|notebook|sqlite|folder|archive|document|binary, --format summary|terminal|json et --exit-code. Les profils de bureau enregistrés ne sont pas des options CLI.

Un terminal interactif utilise par défaut la vue avec coloration syntaxique ; une sortie redirigée utilise le résumé concis. Utilisez --color auto|always|never, --language pour choisir la langue de coloration et --context pour définir les lignes inchangées autour de chaque bloc de modifications.

Le mode document CLI compare le contenu extrait ; la page rendue PDF Visual diff est une fonctionnalité de bureau. Pour les vérifications de mise en page automatisées, restituez les pages PDF correspondantes en images de taille égale, comparez chaque paire avec le mode binaire Pro et lisez ses métriques d’image à partir de JSON.

Les comparaisons de texte prennent les options d’ignorance de l’application : --ignore-text et --ignore-lines avec une expression régulière, --ignore-preset pour les modèles d’horodatage et d’identification intégrés, --ignore-comments et --ignore-columns, tels que 1-6 ou 73-.

L’utilisation gratuite de CLI est limitée au texte, au JSON et aux notebooks, aux fichiers jusqu’à 5 Mo par côté et à 10 nouvelles sessions de comparaison par jour calendaire local. Les modes spécialisés, les rapports, l’application de correctifs et tous les manifestes de lots nécessitent Pro.

• Terminal: diff-anything --cli --format terminal --color auto left.ts right.ts
• JSON: diff-anything --cli --format json --mode json left.json right.json
• Image de page rendue : diff-anything --cli --mode binary --format json reference.png candidate.png
• Utilisez des chemins absolus ou stables en termes de flux de travail dans l’automatisation.

Interpréter les codes de sortie

Pour une comparaison unique, ajoutez --exit-code lorsque l’automatisation a besoin de différences pour affecter le résultat du processus. Sans cela, une comparaison unique valide renvoie zéro même lorsque des modifications sont détectées.

Pour une vérification de schéma API, utilisez plutôt --mode api --fail-on breaking : les schémas identiques ou équivalents réussissent, les modifications ininterrompues sont autorisées et le processus renvoie 1 uniquement pour les modifications interrompues ou les modifications que les règles n’ont pas pu classer.

Le mode batch renvoie zéro lorsque chaque cas réussit sa vérification failOn, un lorsqu’un cas échoue ou n’a pas pu être comparé, et deux lorsque le lot ne peut pas être invoqué ou que son manifeste ne peut pas être lu ou analysé.

• Unique avec --exit-code : 0 propre, 1 différence, 2 invocations non valides, entrée illisible ou échec de comparaison.
• Unique avec --mode api --fail-on breaking : 1 uniquement pour les cassures ou les modifications API non classifiées.
• Lot : 0 pour chaque cas réussi, 1 un cas échoue à sa vérification failOn ou n’a pas pu être comparé, 2 échec du manifeste ou de l’invocation.

Choisir le format de sortie adapté

Le format du terminal donne à une personne une différence avec une syntaxe mise en évidence, sécurisée par Unicode, avec des numéros de ligne et des morceaux compacts. Le résumé concis convient aux journaux ordinaires, tandis que JSON préserve les résultats structurés pour un autre outil.

Les workflows par lots acceptent les manifestes YAML ou JSON et peuvent émettre un résumé, JSON, JUnit ou SARIF. JUnit s’adapte aux surfaces de rapport de test ; SARIF s’adapte aux surfaces d’analyse de code et d’analyse statique qui comprennent la norme. Séparez les messages de diagnostic des sorties lisibles par machine afin que les analyseurs reçoivent des documents valides.

Configurer l’outil de comparaison Git

Enregistrez Diff Anything en tant qu’outil de comparaison Git et transmettez les chemins LOCAL et DISTANT de Git en mode explicite CLI. N’ajoutez pas --exit-code à la commande difftool : Git s’attend à ce que l’outil traite avec succès une paire modifiée.

Git crée des fichiers temporaires pour certaines comparaisons, donc vérifiez ou modifiez via le flux de travail pris en charge par le mode sélectionné plutôt que de supposer qu’une source temporaire doit être conservée.

• git config --global diff.tool diff-anything
• git config --global difftool.diff-anything.cmd 'diff-anything.exe --cli "$LOCAL" "$REMOTE"'

Utilisez Diff Anything pour git diff

Pour que git diff lui-même utilise Diff Anything, définissez-le comme pilote de comparaison et attribuez-le aux types de fichiers dans le fichier .gitattributes du référentiel. Git exécute le pilote uniquement pour les fichiers qui lui sont attribués, les nomme par leurs chemins de référentiel, affiche les changements de mode et renomme comme le fait sa propre différence.

git diff utilise le pilote pour les fichiers attribués ; git log -p et git show l’utilisent avec --ext-diff. Laissez --exit-code en dehors d’un pilote diff, car Git s’arrête au premier fichier modifié lorsqu’un pilote se termine avec un statut différent de zéro. Sur le plan gratuit, un fichier que le plan ne couvre pas est répertorié comme non comparé et git diff continue avec le reste.

• git config --global diff.diff-anything.command 'diff-anything --cli --format terminal --color auto'
• .gitattributes: *.json diff=diff-anything
• .gitattributes: *.yaml diff=diff-anything
• diff-anything --cli --integration-help imprime cette configuration

Fusionner avec Git

Avec Pro, Diff Anything est à la fois un pilote de fusion et un outil de fusion. Le pilote de fusion fusionne les fichiers que vous lui attribuez dans .gitattributes chaque fois que Git fusionne : un fichier JSON, YAML, TOML ou INI est fusionné par ses données, les marqueurs de conflit entourent uniquement les valeurs modifiées différemment par les deux côtés et le pilote renvoie 1 tant que les conflits subsistent. --name %P lui donne le nom propre du fichier, qui décide de son format.

L’outil de fusion est l’application elle-même. git mergetool la lance pour chaque fichier en conflit et attend : la fenêtre affiche les versions de base, locale et distante ainsi que le résultat, les conflits laissés par Git apparaissant comme des conflits structurés. « Enregistrer et fermer » écrit le fichier fusionné et quitte avec le code 0 ; « Annuler » ou la fermeture de la fenêtre quitte avec le code 1 et laisse le fichier tel que Git l’a écrit. Sous Windows, la version du Microsoft Store est l’outil de fusion. Sur Mac, les mêmes paramètres lancent l’outil en ligne de commande, qui lit les fichiers, ouvre la fusion dans une fenêtre de l’application du Mac App Store, en lançant l’application si elle n’est pas ouverte, et écrit le fichier fusionné lorsque vous choisissez « Enregistrer et fermer » ; sans l’outil, ouvrez le fichier en conflit dans l’application et choisissez « Résoudre ».

• git config --global merge.diff-anything.driver 'diff-anything --cli --merge %O %A %B --output %A --name %P'
• git config --global merge.tool diff-anything
• git config --global mergetool.diff-anything.cmd 'diff-anything --merge-tool "$BASE" "$LOCAL" "$REMOTE" "$MERGED"'
• git config --global mergetool.diff-anything.trustExitCode true
• .gitattributes: *.toml merge=diff-anything

Exécuter des manifestes par lots

Un manifeste de lot Pro peut être un objet YAML ou JSON avec un tableau de comparaisons ou un tableau de comparaisons de niveau supérieur. Chaque élément prend en charge le nom, la gauche, la droite, un mode facultatif, failOn (n’importe lequel ou rupture) et warnsAsDifferences ; les règles de profil de bureau ne sont pas des champs de manifeste par lots et une clé mal orthographiée est signalée comme une erreur.

Utilisez --format junit ou --format sarif pour les surfaces de révision établies, ou --format json pour le résultat détaillé. Écrivez le rapport avec --output FILE, qui écrit UTF-8 ; dans Windows PowerShell 5.1, la redirection avec > écrit UTF-16, que de nombreux outils CI rejettent. Pour les cas API avec failOn :break, JUnit répertorie les modifications incompatibles avec leurs codes de règle et SARIF rapporte chaque résultat sous son code de règle.

• Élément du manifeste : { "name" : "Schéma API", "left" : "baseline/openapi.json", "right" : "build/openapi.json", "mode" : "api", "failOn" : "breaking" }
• Fichier JUnit : diff-anything --cli --batch comparatives.json --format junit --output report.xml
• Fichier SARIF : diff-anything --cli --batch comparatives.json --format sarif --output report.sarif

Diagnostiquer les échecs d’automatisation

Reproduisez localement les chemins exacts, le mode, le format et l’option de code de sortie. Vérifiez si le processus peut lire les deux sources et si le shell peut créer un fichier de sortie redirigé.

Les comparaisons CLI utilisent leurs options intégrées par défaut ; ils ne chargent pas les profils de bureau. Lorsque les résultats diffèrent selon la machine, inspectez les octets sources, les fins de ligne, les chemins et la version de l’application avant de modifier les attentes.