Collaborer sur un fichier en utilisant Linux diff et patch

J’édite beaucoup de fichiers texte. Parfois, c’est du code. D’autres fois, c’est le mot écrit pour les jeux de rôle (RPG), les livres de programmation ou la correspondance générale. Parfois, c’est bien de faire un changement, mais pour mon collaborateur de comparer mon changement avec ce qu’ils avaient écrit à l’origine. De nombreuses personnes utilisent par défaut les suites bureautiques, comme LibreOffice, en utilisant des commentaires ou des fonctionnalités de suivi des modifications. Parfois, un outil plus simple a plus de sens, et pour cela, vous pouvez consulter l’historique de programmation pour des outils comme diff et patch, qui fournissent un formatage standardisé pour le suivi et l’application des modifications aux fichiers partagés.

Même avec un simple fichier, il y a de la complexité à synchroniser deux documents. Certains éléments sont modifiés, d’autres sont laissés seuls, du nouveau contenu est ajouté et certains restent les mêmes mais sont déplacés vers différents endroits dans le document. Il est difficile de reproduire les modifications sans accepter béatement que toutes les modifications sont également valables et sans remplacer l’ancien fichier par le nouveau. Il est également monolithiquement opaque. Il y a tellement de changements qu’il est difficile de déterminer exactement ce qui a changé.

Avec le diff commande, vous pouvez créer un enregistrement de la façon dont le fichier a changé, et avec patch vous pouvez “rejouer” ces modifications par rapport à l’ancienne version pour la mettre à jour avec la nouvelle version.

Installer

Supposons que vous et moi collaborions sur un dossier décrivant comment préparer une tasse de thé.

Jusqu’à présent, le fichier tea.md contient un copier-coller brut :

Boil water.
Warm the teapot.
Add tea and water to the teapot.
Place a tea cosy over the teapot.
Steep for 6 minutes.
Pour tea into cup.
Add milk.

Cela semble raisonnable, mais il y a toujours des optimisations que vous pouvez faire, vous m’envoyez donc le fichier pour amélioration. Dans un effort pour clarifier le processus de préparation du thé, je copie le fichier comme tea-revision.md et éditez-le, en terminant avec ceci:

Warm a teapot in the proving drawer of your oven.
Boil water.
Add tea leaves to a tea strainer.
Add strainer and water to teapot.
Steep for 6 minutes. Keep it warm with a tea cosy.
Pour tea into cup.
Optionally, add warm milk.

Comme prévu, certains éléments (Boil water et Pour tea into cup) sont inchangés, tandis que les autres lignes (Warm the teapot) ont eu des ajouts. Certaines lignes sont complètement nouvelles et d’autres sont identiques mais dans un ordre différent.

Créer une différence

Les diff L’outil affiche la différence entre deux fichiers. Il y a plusieurs manières d’afficher les résultats, mais je pense que la plus claire est la --unified (-u pour faire court), qui montre quelles lignes ont été ajoutées ou soustraites. Une ligne qui est modifiée de quelque manière que ce soit est traitée comme une ligne qui a été soustraite puis ajoutée. Par défaut, diff imprime sa sortie sur le terminal.

Apporter diff avec l’ancien fichier puis le nouveau fichier :

$ diff --unified tea.md tea-revised.md 
--- tea.md      2021-11-13 10:26:25.082110219 +1300
+++ tea-revised.md      2021-11-13 10:26:32.049110664 +1300
@@ -1,7 +1,7 @@
+Warm a teapot in the proving drawer of your oven.
 Boil water.
-Warm the teapot.
-Add tea and water to the teapot.
-Place a tea cosy over the teapot.
-Steep for 6 minutes.
+Add tea leaves to a tea strainer.
+Add strainer and water to teapot.
+Steep for 6 minutes. Keep it warm with a tea cosy.
 Pour tea into cup.
-Add milk.
+Optionally, add warm milk.

Un signe plus (+) au début d’une ligne indique quelque chose qui a été ajouté à l’ancien fichier. Un signe moins (-) au début d’une ligne indique une ligne qui a été supprimée ou modifiée.

Créer un patch avec diff

Un fichier de correctif n’est que la sortie du diff --unified commande placée dans un fichier. Vous pouvez le faire en utilisant la redirection Bash standard :

$ diff -u tea.md tea-revised.md > tea.patch

Le contenu du fichier est exactement le même que celui qui a été envoyé au terminal. J’aime voir les fichiers de correctifs dans Emacs, qui codent par couleur chaque ligne selon qu’elle est ajoutée ou soustraite.

Application des modifications avec patch

Une fois que j’ai un fichier de correctif, je pourrais vous l’envoyer pour que vous l’examiniez et, éventuellement, l’appliquez à votre ancien fichier. Vous appliquez un patch avec le patch commander:

$ patch tea.md tea.patch

Des lignes ont été ajoutées, des lignes ont été soustraites, et au final, vous vous retrouvez avec un fichier identique à ma version :

$ cat tea.md
Warm a teapot in the proving drawer of your oven.
Boil water.
Add tea leaves to a tea strainer.
Add strainer and water to teapot.
Steep for 6 minutes. Keep it warm with a tea cosy.
Pour tea into cup.
Optionally, add warm milk.

Il n’y a pas de limite au nombre de fois que vous pouvez patcher un fichier. Vous pouvez répéter mes modifications, générer un nouveau correctif et me l’envoyer pour examen. L’envoi de modifications plutôt que de résultats permet à chaque contributeur d’examiner ce qui a changé, de décider ce qu’il souhaite conserver ou éliminer et de documenter avec précision le processus.

Installer

Sous Linux et macOS, vous disposez déjà à la fois des diff et patch commandes. Sous Windows, vous pouvez obtenir diff et patch par Cygwin, ou utilisez Chocolatey pour rechercher diffutils et pièce.

Si vous avez déjà essayé de collaborer sur des fichiers par e-mail ou par chat et que vous vous êtes retrouvé à essayer de décris là où vous avez besoin d’un changement, alors vous allez adorer diff et patch. Un fichier soigneusement structuré, tel que du code ou un Markdown délimité par des lignes, est facile à différencier, corriger et maintenir.