Traduction du tutoriel Arch de Thomas Lord

Introduction aux changesets

Il est souvent utile de pouvoir comparer deux arborescences (généralement du même projet) et voir précisément quelles sont les différences entre elles. L'enregistrement de ces différences est appelé changeset ou delta.

Les changesets représentent un concept central de arch -- la plupart des outils de arch effectuent des opérations avec les changesets.

Si vous avez un changeset entre une « vieille arborescence » et une « nouvelle arborescence », vous pouvez « appliquer un changeset » sur la « vieille arborescence » et obtenir ainsi la « nouvelle arborescence » -- en d'autres termes, vous pouvez appliquer automatiquement les changements décrits dans le changeset. Si vous avez une troisième arborescence vous pouvez également appliquer ce patch et voir ce que donnerait ces changements sur lui.

arch inclut des outils sophistiqués pour créer et appliquer des changesets.

mkpatch
dopatch
Problème de patch -- Comment sont gérés les conflits

mkpatch

mkpatch génère un changeset décrivant les différences entre deux arborescences. La commande de base est :

% tla mkpatch ORIGINAL MODIFIED DESTINATION

qui compare l'arborescence ORIGINAL et MODIFIED

mkpatch crée un nouveau répertoire, DESTINATION, et enregistre le changeset dedans.

Quand mkpatch compare les deux arborescences, il utilise les identifiants (inventory ids). Par exemple, il considère deux répertoires ou deux fichiers comme étant « le même répertoire (ou fichier) » s'ils ont le même identifiant -- même s'ils sont placés à des endroits différents. (voir « Identifiants d'inventaire pour les sources ».)

Un changeset produit par mkpatch décrit quels fichiers et répertoires ont été ajoutés, déplacés, renommés ou modifiés (et comment ils ont été modifiés), ainsi que les fichiers dont les permissions auraient été changées (et comment). Lorsqu'il s'agit de fichiers textes classiques, mkpatch génère un « context diff » décrivant les différences. mkpatch peut comparer des fichiers binaires (en sauvegardant une copie complète de l'ancienne et de la nouvelle version si elles sont différentes) ainsi que les liens symboliques (en sauvegardant l'ancienne et la nouvelle cible, si elles sont différentes).

Une description détaillée du format d'un changeset est décrit dans l'appendice (voir « Le format arch d'un changeset »)

dopatch

dopatch est utilisé pour appliquer un changeset à une arborescence.

% tla dopatch PATCH-SET TREE

Si l'arborescence TREE est exactement la même que l'arborescence « originale » utilisée par mkpatch, alors TREE sera modifiée pour que l'arborescence devienne strictement identique à l'arborescence « modifiée » utilisée par mkpatch, avec une exception (détaillée plus loin).

« Exactement la même » signifie que la structure de l'arborescence est identique, que les liens symboliques sont identiques, que les fichiers textes sont identiques, et que les permissions des fichiers sont identiques. Les dates de modifications, les fichiers ayant plusieurs liens (en dur), et les propriétaires des fichiers ne sont pas forcément préservés.

L'exception à la règle « exactement la même » est qu'au cas où l'application du patch entraîne des suppressions de fichiers ou répertoires dans l'arborescence TREE, ces fichiers et répertoires seront sauvegardés dans un sous-répertoire de TREE avec un nom particulièrement visible à l'oeil grâce à sa syntaxe :

++removed-by-dopatch-PATCH--DATE

où PATCH est le nom complet du patch-set et DATE la date précise.

Problème de patch -- Comment sont gérés les conflits

Que se passe-t-il si l'arborescence à patcher de dopatch n'est pas exactement la même que l'originale utilisée par mkpatch ?

Ci-dessous, une description de ce à quoi on peut s'attendre. La documentation complète du fonctionnement de dopatch est incluse dans le code source.

dopatch fait un inventaire de l'arborescence à patcher. Il utilise les identifiants (inventory ids) pour décider quels fichiers et répertoires attendus sont présents ou manquants de l'arborescence et voir où chaque fichier et répertoire se trouve dans l'arborescence.

Patchs simples

Si le changeset contient un patch classique ou un metadata patch pour un lien, répertoire ou fichier, et que ce fichier est présent dans l'arborescence, dopatch applique le patch de manière habituelle. Si le patch s'applique proprement, le fichier modifié, le lien, ou le répertoire est laissé à sa place.

Si le patch ne peut pas s'appliquer proprement, dopatch va laisser le fichier orignal avec un suffixe .orig (le fichier original de l'arborescence devant être patché, sans aucune modification) et créer un fichier .rej (contenant la partie du patch qui n'a pas pu être appliquée)

Si le conflit concernait un fichier binaire, il n'y aurait pas eu de fichier partiellement patché. À la place nous aurions eu :

.orig -- le fichier original de l'arborescence à patcher,
         sans aucune modification

.rej  -- une copie complète du fichier de l'arborescence
         modifiée, avec les mêmes permissions que le fichier ``.orig``

.patch-orig -- une copie complète du fichier original
               utilisé par ``mkpatch``, avec ses permissions originales.

                -ou-

               le lien symbolique de l'arborescence utilisé
               par ``mkpatch`` avec ses permissions originales.

Si le conflit concernait un lien symbolique, il n'y aurait pas eu de fichier partiellement patché. À la place nous aurions eu :

.orig -- le fichier non modifié de l'arborescence originale

.rej -- un lien symbolique sur la cible attendue par le patch avec
        les mêmes permissions que le fichier ``.orig``

.patch-orig -- une copie complète du fichier original utilisé par
               ``mkpatch``, avec ses permissions originales.

                 -ou-

               le lien symbolique de l'arborescence utilisée
               par ``mkpatch`` avec ses permissions originales.

Patchs sur des fichiers manquants

Tous les patchs à appliquer sur des fichiers ou répertoires manquants sont enregistrés dans un sous-répertoire placé à la racine de l'arborescence à patcher.

==missing-file-patches-PATCH-DATE

où PATCH est le nom complet du changeset et DATE la date actuelle.

Réorganisation des répertoires et nouveaux répertoires

Les répertoires sont ajoutés, supprimés, et réorganisés de la manière attendue, même si vous ne savez pas que c'est ce que vous attendriez.

Supposons que lorsque la commande mkpatch a été appelée, l'arborescence ORIGINAL était :

Répertoire ou fichier:      Id:

a/x.c                       id_1
a/bar.c                     id_2

mais l'arborescence MODIFIED était :

a/x.c                       id_1
a/y.c                       id_2

avec une modification sur chaque fichiers. Le patch va renommer le fichier avec l'identifiant id_2` en ``y.c, et modifier le contenu des fichiers avec les identifiants id_1 et id_2.

Supposons, par exemple, que vous ayez cette arborescence :

a/foo.c                     id_1
a/zip.c                     id_2

et que vous appliquiez le patch à cette arborescence. Après le patch, vous aurez :

a/foo.c                     id_1
a/y.c (ancien zip.c)        id_2

avec les modifications sur chacun des fichiers.

Voici un exemple plus subtil et la manière de gérer ces conflits :

Supposons que l'arborescence originale utilisée par mkpatch était :

Répertoires et fichiers:    Id:

./a                         id_a
./a/b                       id_b
./a/b/c                     id_c

Finalement supposons que l'arborescence soit :

./x                         id_a
./x/b                       id_b
./x/c                       id_new_directory
./x/c/b                     id_different_file_named_b
./x/c/q                     id_c

Après l'application du patch nous aurons :

./x                         id_a
      Étant donné que le patch ne fait aucune modification sur le
      répertoire ayant id_a

./x/c.orig                  id_new_directory
./x/c.rej                   id_c
      Étant donné que le patch veut transformer le répertoire id_c
      en un sous-répertoire nommé ``c`` du répertoire ``id_a``, mais que cette
      arborescence a déjà un autre répertoire ici, avec l'identifiant
      ``id_new_directory``.

./x/c.rej/b                 id_b
      Étant donné que le patch veut renommer le répertoire avec
      l'identifiant ``id_b`` en un sous-répertoire nommé ``b`` du répertoire avec l'identifiant
      ``id_c``.

./x/c.orig/b                id_different_file_named_b
      Étant donné que le patch effectue des modifications sur ce fichier,
      il reste dans son répertoire parent.

Version du 18/09/2004 21h14 : wilk@flibuste.net--libre   docs-tla--fr--1.0     patch-102 ... base-0