Lier un document à un précédent, et voir ce qui a changé
Un push peut désormais indiquer qu’il s’agit d’une nouvelle version d’un document antérieur — ?replaces= dans l’API, --replaces depuis le CLI, une entrée replaces dans l’Action. C’est facultatif : rien ne lie les documents de son propre chef, et un push ordinaire reste le document sans rapport qu’il a toujours été. Les documents liés reçoivent une icône de chaîne dans l’historique et une comparaison ligne par ligne avec la version précédente.
Chaque push ici crée un document entièrement nouveau, et ce n’est pas un défaut à corriger : un lien collé dans un commentaire il y a trois semaines doit continuer à montrer ce que disait ce commit. Mais une note de version poussée chaque vendredi est vraiment le même document sept fois, et rien ne pouvait le dire. Désormais, quelque chose le peut.
Comment le dire
Un seul paramètre, sur le push qui crée le document le plus récent :
curl -H "Authorization: Bearer tp_live_…" --data-binary @v2.md \\
"https://transformpipe.com/api/v1/documents?name=notes.md&replaces=<id>"
Le CLI l’écrit --replaces <id>, et la GitHub Action prend une entrée replaces. L’id du document précédent est ce qu’affiche tp list, et ce que porte la sortie documents de l’Action. Il doit s’agir d’un document du même compte, sinon la requête renvoie 404 plutôt que de créer un lien vers quelque chose que vous ne pouvez pas voir.
Ce que vous obtenez
Dans l’historique, un document lié porte une icône de chaîne. L’ouvrir affiche toute la chaîne, du plus ancien au plus récent, et toute entrée qui a quelque chose avant elle peut lui être comparée : une comparaison ligne par ligne, calculée dans votre navigateur à partir des deux sources déjà récupérées, si bien que rien sur le serveur ne fait la comparaison.
Depuis un programme, GET /api/v1/documents/:id/versions — ou tp versions <id> — répond avec la chaîne à partir de n’importe lequel de ses membres — les ancêtres qu’il remplace, et tout ce qui a ensuite remplacé ceux-là — chacun avec son id, son name, son created_at et son propre replaces. Le connecteur pour assistants expose la même chose sous le nom tp_document_versions. Chaque document d’une liste porte aussi son replaces, si bien qu’un client qui a la liste en main peut reconstituer les chaînes sans une requête par ligne.
Pourquoi rien n’est déduit
Un convertisseur qui devinerait se tromperait d’une façon qui coûte. Deux fichiers au même nom ne sont souvent pas des versions l’un de l’autre — un README.md de deux dépôts différents, le même rapport pour deux mois différents — et un outil qui les enchaînerait présenterait silencieusement l’un comme le successeur de l’autre. Ici, ni le nom, la conversion ou le moment ne comptent : un document est la version d’un autre parce que quelqu’un l’a dit, un à la fois.
Ce que ce n’est pas
Ce n’est pas un historique automatique. Rien ici ne modifie un document sur place, aucune version n’apparaît donc sans un push, et il n’y a pas de retour en arrière : une version antérieure reste son propre document, à sa propre adresse, avec son propre lien de partage. Supprimer une version antérieure ne supprime pas la plus récente — le lien disparaît, et il reste le document sans rapport qu’il aurait été de toute façon.
Autres lectures : notes de version à partir de Markdown, et publier depuis GitHub Actions.