À qui se destine ce manuel ?

On suppose que le lecteur est familier avec les commandes unix de base (telles que ls, mv et find).

Par ailleurs, le lecteur devrait être familier avec les programmes diff et patch et avec le concept de patchset.

Il est très utile -- mais pas strictement nécessaire -- d'avoir déjà utilisé d'autres systèmes de contrôle de version, tels que CVS.

Où est le manuel de référence ?

Arch est, dans sa plus grande partie, un programme auto-documenté. La commande :

% tla help

fournit une liste ordonnée des commandes disponibles et, pour une commande foo,

% tla foo -H

affiche la documentation de cette commande.

D'autres sources d'aide -- La liste de discussion et le Wiki

Un Wiki (site internet édité de manière collective) créé par la communauté des utilisateurs de arch est disponible à :

http://wiki.gnuarch.org/

Ce site comporte des comparaisons avec d'autres systèmes de contrôle de versions, des exemples de plusieurs utilisations possibles de arch, des recettes pour les tâches communes et des liens vers de nombreux outils, tels que des « shell wrappers » puissants et des explorateurs d'archive (web-based archive browsers). Les contributions et les questions de nouveaux utilisateurs sont bienvenues sur le Wiki -- à l'heure où ces lignes sont écrites, le Wiki ne requiert pas encore d'inscription pour y écrire ou y effectuer des modifications. (Cela dit, le revers de la médaille de cet accès ouvert est que l'information qui y est consignée ne doit pas être tenue pour parole d'évangile, dès lors qu'un petit malin pourrait y avoir délibérément semé le trouble ou -- plus vraisemblablement -- un débutant pourrait avoir publié des informations fausses.)

Arch est différent des anciens (et concurrents) systèmes au point que les nouveaux utilisateurs sont souvent un peu désorientés dans les premiers jours de son utilisation. On pourra trouver utile de chercher de l'aide sur la liste de discussion « gnu-arch-users », que l'on peut trouver sur :

http://www.gnu.org/software/gnu-arch

Si vous avez des besoins particuliers qu'arch ne semble pas être en mesure de satisfaire, certains membres de la liste de discussions « gnu-arch-users » sont disponibles pour des travaux de consultants. Cependant, parlez de vos propositions sur la liste de discussion en premier lieu -- il peut arriver que ce dont vous avez besoin soit déjà supporté, mais pas d'une manière évidente.

Qu'est-ce que le contrôle de révision ?

Un « système de contrôle de révision » est un outil de catalogage et de coordination pour des arborescences de fichiers et pour les modifications qu'on y apporte. Par exemple, un projet type de logiciel utilise le contrôle de révision pour suivre le développement du code source à travers le temps, pour garder une trace de chaque modification qui a été apportée à ce code (par exemple chaque correction de bogue ou ajout de fonctionnalité), pour partager ces modifications avec tous les programmeurs qui travaillent sur le projet et les aider à rester synchronisés, en combinant les modifications effectuées à des moments différents et/ou par des programmeurs différents en une seule et même arborescence.

Un « outil de gestion de code source » aide à gérer un grand nombre de fichiers bien plus grand que ce que vous pourriez faire « à la main ». Par exemple, un outil de gestion de code source est capable d'établir l'inventaire des fichiers dans une arborescence, de faire la distinction entre les fichiers sources et les fichiers temporaires (scratch files) et d'autres fichiers qui peuvent être archivés. On peut également être averti des fichiers sources ajoutés ou effacés.

La « gestion de configuration » rejoint les attentes de projets qui combinent des arborescences multiples et séparées en une seule arborescence. Un outil de gestion de configuration facilite la mise en place du projet « combiné » et de garder la trace de la façon dont le développement des parties qui le constituent est synchronisé.

Pourquoi utiliser arch ?

Arch présente de nombreux avantages, comparé aux autres systèmes de contrôle de révision. Notamment :

Il travaille sur l'ensemble de l'arborescence

Arch suit l'ensemble de l'arborescence -- et pas seulement des fichiers individuels. Par exemple, on peut changer de nombreux fichiers dans une arborescence, arch peut enregistrer tous ces changements comme un ensemble de changements, plutôt que fichier par fichier. Si on renomme les fichiers ou si on réorganise l'arborescence, arch est capable d'enregistrer ces modifications, de la même manière qu'il le fait lors des modifications de fichiers.

Il est orienté changeset

Arch ne crée pas uniquement des snapshots des arborescences de vos projets. Il associe plutôt chaque révision avec un changeset particulier : une description précise de ce qui a changé. Arch fournit ainsi des commandes orientées changeset qui facilitent la relecture de ces changements, la fusion (merge) d'arborescences en appliquant les modifications, l'analyse de l'historique d'une arborescence en demandant quels changements y ont été appliqués, et ainsi de suite.

Intégralement réparti

Arch ne repose pas sur une « distribution centralisée ». Par exemple, il n'est pas indispensable de donner un accès en écriture à tous les contributeurs importants d'un projet. Au lieu de cela, chaque contributeur peut avoir sa propre archive pour son travail. Arch opère en souplesse parmi les liens entre les archives.

Outils utilisés pour compiler arch

GNU Make : Il est nécessaire d'avoir GNU Make pour pouvoir compiler arch.

Outils Shell aux standards Posix : Le paquet nécessite que les outils shell au standards Posix soient présents sur votre système :

awk     find    mkdir   sh      wc
cat     fold    printf  tee     xargs
chmod   grep    pwd     test
date    head    rm      touch
echo    ls      sed     tsort

/usr/local/bin/bash ../configure --config-shell /usr/local/bin/bash

Périphérique "null" : Votre système doit pouvoir envoyer des données vers /dev/null. Ces données devraient tout simplement disparaître de l'univers. En tant que logiciel « écologique », nous avons fait en sorte que votre ordinateur puisse un jour convertir ces informations non traitées en chaleur, que vous pourrez utiliser en complément des systèmes de chauffage traditionnels.

Outils utilisés de manière interne par arch

Le reste des outils est utilisé de manière interne par arch lui-même. Ils ne doivent pas nécessairement être dans votre path -- lorsque vous compilez arch à partir des sources, lancez le script de configuration :

% ./configure --help

et

% ./configure --help-options

pour savoir comment indiquer les bonnes options à arch.

GNU Tar : GNU Tar doit être présent sur votre système. Arch appelle tar de manière interne pour empaqueter et dépaqueter les fichiers qu'il archive. Il est important que toutes les versions de Arch utilisent une version compatible de tar, raison pour laquelle GNU tar a été choisi.

GNU diff et GNU patch : Après de nombreuses délibérations, j'ai décidé d'utiliser les versions GNU de diff et patch. Plus précisément, nous avons besoin d'une version de diff capable de générer du « format unifié » (option -u) et une version de patch qui comprenne ce format et qui comprenne l'option --posix. (Ce serait facile d'utiliser des « diffs contextuels » ("context diffs") et, ainsi, les diff et patch standards. Cependant, les « diffs unifiés » sont plus lisibles et j'espère que choisir l'intégration spécifiques de ces sous-composants critiques aidera à donner à arch une stabilité à long terme.

Les commandes arch en général

Chaque commande de arch est appelée par le programme tla, via une syntaxe de sous-commande ordinaire :

% tla <sub-command> <options> <parameters>

On peut consulter une liste des sous-commandes disponibles :

% tla help

Un bref sommaire des options pour chaque commande est obtenu en saisissant :

% tla <sub-command> -h

Pour chacune, un message d'aide plus détaillé peut-être obtenu :

% tla <sub-command> -H

Par exemple, essayez :

% tla my-id -H
print or change your id
usage: tla my-id [options] [id]

  -h, --help     Display a help message and exit.
  -H             Display a verbose help message and exit.
  -V, --version  Display a release identifier string
                 and exit.
  -e, --errname  specify program name for errors
  -u, --uid      print only the UID portion of the ID

With no argument print your arch id.

With an argument, record ID-STRING as your id
in ~/.arch-params/=id

Your id is recorded in various archives and log messages
as you use arch.  It must consist entirely of printable
characters and fit on one line.  By convention, it should
have the form of an email address, as in this example:

        Jane Hacker <jane.hacker@gnu.org>

The portion of an id string between < and > is called your
uid.  arch sometimes uses your uid as a fragment when generating
unique file names.

The option -u (--uid) causes only the uid part of your id string
to be printed.

Un effort à été fait pour conserver une certaine régularité concernant le nom des options et la syntaxe des paramètres. Vous devriez retenir tout cela au long de votre apprentissage des différentes commandes.

my-id

Le premier pas dans l'utilisation de arch est de définir votre identité (id) avec la ligne de commande :

% tla my-id "Tom Lord <lord@emf.net>"

Votre id devrait être composée de votre nom, suivi de votre adresse courriel entre des chevrons.

Arch enregistre votre id dans plusieurs messages de log qu'il va créer.

On peut revoir son id en tapant :

% tla my-id
Tom Lord <lord@emf.net>

Comment ça marche ? -- Votre identité pour arch

Après la commande ci-dessus, vous aurez de nouveaux fichiers dans votre répertoire personnel :

% ls ~/.arch-params
=id

% cat ~/.arch-params/=id
Tom Lord <lord@emf.net>

Choisir un emplacement

Vous devez choisir où sera placée votre archive, dans quel répertoire elle sera rangée.

Dans les exemples qui suivent, nous allons créer une archive qui sera un sous-répertoire de ~/{archives}, ce dernier étant le répertoire où nous rangeons toutes nos archives.

Créons donc tout d'abord {archives} :

% mkdir ~/{archives}

Choisir un nom pour une archive

L'étape suivante consiste à faire le choix d'un nom pour votre archive. Un nom d'archive est constitué d'une adresse courriel, suivie par deux tirets (--), puis par un suffixe. Par convention, l'adresse courriel devrait être celle du propriétaire de l'archive.

Dans cet exemple, nous utiliserons le nom suivant :

lord@emf.net--2003-example

Créer l'archive

Pour créer une nouvelle archive, on utilise la commande make-archive, en lui indiquant le nom de l'archive et son emplacement:

# Créer la nouvelle archive
#
% tla make-archive lord@emf.net--2003-example ~/{archives}/2003-example

En faire votre archive par défaut

Afin de nous éviter de saisir le nom de l'archive à chaque commande, on déclare que cette nouvelle archive est notre archive par défaut :

% tla my-default-archive lord@emf.net--2003-example

On peut consulter le nom actuel de l'archive par défaut en tapant :

% tla my-default-archive
lord@emf.net--2003-example

On peut annuler ce réglage avec la commande :

% tla my-default-archive -d
user default archive removed

(Si vous jouez avec l'option -d, veillez à rétablir notre archive d'exemple par défaut, afin de pouvoir continuer de suivre le tutoriel.)

Comment ça marche ? -- De nouvelles archives

Examinons ce que font réellement ces commandes.

Tout d'abord, tla sait maintenant que la nouvelle archive existe :

Quelles sont les archives que tla connaît ?

% tla archives
lord@emf.net--2003-example
    /home/lord/{archives}/2003-example

% tla wheris-archive lord@emf.net--2003-example
/home/lord/{archives}/2003-example

Où est rangée l'information ?

 % ls ~/.arch-params
 =default-archive          =id          =locations

 % cat ~/.arch-params/=default-archive
lord@emf.net--2003-example

 % ls ~/.arch-params/=locations
 lord@emf.net--2003-example

 % cat ~/.arch-params/=locations/lord@emf.net--2003-example
 /home/lord/{archives}/2003-example

Le répertoire de l'archive a été créé et contient de nouveaux fichiers :

% ls ~/{archives}
2003-example

% ls -a ~/{archives}/2003-example
.                   .archive-version
..                  =meta-info

% cat ~/{archives}/2003-example/.archive-version
Hackerlab arch archive directory, format version 2.

% ls -a ~/{archives}/2003-example/=meta-info/
.        ..        name

% cat ~/{archives}/2003-example/=meta-info/name
lord@emf.net--2003-example

Nommer le nouveau projet

La première étape consiste à choisir une catégorie générale qui servira à nommer le projet. Dans les exemples qui vont suivre, nous utiliserons le nom :

hello-world

Choisir une branche pour ce projet

Arch vous encourage à diviser votre travail sur un projet en « branches » séparées.

Grosso modo, les branches permettent de séparer le travail sur un projet en deux chantiers (ou plus) largement indépendants. Supposons, par exemple, que le projet « hello world » ait deux besoins :

1. Le besoin de publier des versions régulières du bon vieux « hello world », en apportant des corrections de bogues simples ou des modifications liées à la portabilité du programme, ou, enfin, en ajoutant de petites fonctionnalités ;
2. le besoin de commencer à travailler sur l'interface graphique du projet « hello world », dont on suppose que la réalisation prendra une année.

Nous souhaitons que ces deux chantiers progressent en parallèle, mais qu'ils n'y ait pas d'interférence entre eux. Par exemple, nous ne souhaitons pas que le code de l'interface graphique soit publié avant qu'il ne soit relativement fonctionnel.

Dans cette situation, nous utilisons les « branches » : une pour les versions régulières (la branche mainline) et une autre pour l'interface graphique (la branche gui).

Il y a plusieurs autres utilisations possibles des « branches ». Nous en décrirons certaines dans le manuel. Pour le moment, nous n'avons besoin que d'une seule branche, pour les sources officielles de « hello world », que nous appelons :

hello-world--mainline
^^^^^^^^^^^  ^^^^^^^^
   |            |
category name  branch name

Notez que la catégorie et le nom de la branche sont séparés par deux tirets. En général, les noms de catégorie et de branche doivent être composés uniquement de lettres, de chiffres ou de tirets. Ils doivent commencer par une lettre mais ne doivent pas contenir deux tirets consécutifs ni se terminer par un tiret.

Choisir un numéro de version

Pour finir, on doit choisir un numéro de version pour la version de « hello world » sur laquelle on travaille. On créera cette version dans l'archive.

Avec arch, les numéros de versions ne portent pas les noms de version d'un « snapshot » particulier ou le nom de publication de votre projet -- bien qu'ils soient liés à ce concept. Les numéros de versions correspondent au nom d'une « ligne de développement  » : une séquence de changement que vous apportez alors que vous publiez une version.

Dans notre cas, on utilisera le nom :

hello-world--mainline--0.1
                       ^^^
                        | 
                 version number

Notez que les numéros de version sont toujours des entiers positifs, séparés par un point.

Préparer l'archive

Maintenant que nous avons choisi le nom d'archive de notre projet, il est temps de préparer l'archive à l'utilisation de ce nom :

% tla archive-setup hello-world--mainline--0.1

Après avoir passé cette commande, on peut interroger l'archive pour voir ce qu'on a fait :

% tla categories
hello-world

% tla branches hello-world
hello-world--mainline

% tla versions hello-world--mainline
hello-world--mainline--0.1

À quoi bon tout cela ?

Les personnes qui débutent avec arch sont parfois échaudés par la rigidité de l'espace de nommage¹. Les deux questions les plus communes à ce sujet sont :

« Pourquoi avoir des catégories, des branches et des versions ? Pourquoi ne pas simplement nommer les projets avec des chaînes de caractères arbitraires ? » La meilleure manière de répondre à ces questions est de rappeler qu'un système de contrôle de révision est un bibliothécaire. Une partie de son travail consiste à aider les utilisateurs à naviguer et à faire des recherches parmi une très grande collection de projets et de code sources. Dans le but de rendre ces recherches pratiques, arch définit un système de catalogage :

• catégories,
• branches,
• versions.

(voir l'introduction « Qu'est-ce que le contrôle de révision ? »)

D'une certaine manière, ce fonctionnement est analogue à celui des systèmes de catalogage utilisés dans les bibliothèques de livres, tels que la classification décimale Dewey. C'est une catégorisation hiérarchique de tout ce qui est dans la bibliothèque. C'est le moyen de décrire de manière uniforme l'endroit où un objet donné est stocké, et cela facilite sa recherche en suggérant des liens entre les différents articles. Par exemple, une branche est probablement liée aux autre branches dans un même projet. Une version avec un numéro de version plus grand contient probablement un travail plus récent qu'une autre dans la même branche avec un numéro de version plus bas.

Comment ça marche ? -- Créer les catégories, les branches et les versions

Que fait la commande archive-setup ? C'est assez simple : elle crée de nouveaux répertoires dans votre archive :

% tla whereis-archive lord@emf.net--2003-example
/home/lord/{archives}/2003-example

% cd `tla whereis-archive lord@emf.net--2003-example`

Les catégories sont des répertoires de haut niveau :

% ls
=meta-info      hello-world

Les branches sont au niveau suivant :

% ls hello-world
hello-world--mainline

Les versions viennent au troisième niveau...

% ls hello-world/hello-world--mainline
hello-world--mainline--0.1 

... et sont elles-mêmes des répertoires :

% ls hello-world/hello-world--mainline/hello-world--mainline--0.1/
+revision-lock      +version-lock

L'arborescence initiale

Afin de fournir des exemples concrets, supposons que nous ayons une version initiale de « hello-world » :

% cd ~/wd


% ls
hello-world

% cd hello-world

% ls
hw.c    main.c

% cat hw.c

#include <stdio.h>

void
hello_world (void)
{
  (void)printf ("hello warld");
}


% cat main.c

extern void hello_world (void);

int
main (int argc, char * argv[])
{
  hello_world ();
  return 0;
}

Initialiser une arborescence

La première étape pour préparer une arborescence de code source ordinaire est de la convertir en « arborescence de projet ».

% cd ~/wd/hello-world

% tla init-tree hello-world--mainline--0.1

% ls
hw.c    main.c  {arch}

Notez que nous avons indiqué à init-tree le nom de la version de l'archive dans laquelle nous travaillerons. init-tree a créé un sous-répertoire à la racine de l'arborescence ({arch}).

Le sous-répertoire {arch} indique qu'il est la racine d'une arborescence de projet :

% tla tree-root
/usr/lord/wd/hello-world

tla sait pour quelle version de l'archive est cette arborescence :

% tla tree-version
lord@emf.net--2003-example/hello-world--mainline--0.1

Enfin, arch a créé quelque chose appelé patch-log pour la version passée à init-tree :

% tla log-versions
lord@emf.net--2003-example/hello-world--mainline--0.1

Nous expliquerons ce que sont les « patch logs » dans les chapitres suivants.

Initialiser une arborescence ne change pas une archive

Jusqu'à présent, nous avons seulement déclaré l'arborescence du projet en tant que source : nous n'avons pour l'instant rien stocké de nouveau dans cette archive. Nous y viendrons. Mais avant de faire cela, il y a un sujet important qui doit être abordé : les inventaires de sources (source inventories). Nous verrons cela dans le chapitre suivant.

Comment gérer une erreur avec init-tree ?

Supposons que dans l'exemple ci-dessus, nous ayons fait une erreur de frappe :

% tla init-tree hello-world--mainlin--0.1

Une solution « brutale » consisterait à simplement effacer le sous-répertoire {arch} et recommencer. Cependant, à terme, cette solution n'est pas souhaitable : le sous-répertoire {arch} peut contenir des informations que vous ne souhaitez pas perdre. Nous profiterons donc de cette occasion pour introduire quelques commandes avancées.

L'erreur dans la commande init-tree pose deux problèmes. Le résultat des deux commandes suivantes ne donne pas ce à quoi nous nous attendons :

% tla tree-version
lord@emf.net--2003-example/hello-world--mainlin--0.1

% tla log-versions
lord@emf.net--2003-example/hello-world--mainlin--0.1

On peut changer la tree-version d'une arborescence à n'importe quel moment :

% tla set-tree-version hello-world--mainline--0.1

% tla tree-version
lord@emf.net--2003-example/hello-world--mainline--0.1

Gérer les « patch logs » est un peu plus compliqué. Nous devons ajouter les logs que nous voulons...

% tla add-log-version hello-world--mainline--0.1

% tla log-versions
lord@emf.net--2003-example/hello-world--mainlin--0.1
lord@emf.net--2003-example/hello-world--mainline--0.1

... et effacer ceux que ne souhaitons pas conserver :

% tla remove-log-version hello-world--mainlin--0.1

% tla log-versions
lord@emf.net--2003-example/hello-world--mainline--0.1

Comment ça marche ? -- Initialiser une nouvelle arborescence

init-tree a créé le sous-répertoire {arch} à la racine de l'arborescence. Qu'y a-t-il dedans ?

% ls {arch}
++default-version       =tagging-method         hello-world

% cat {arch}/++default-version
lord@emf.net--2003-example/hello-world--mainline--0.1

% cat {arch}/=tagging-method
[... long output ...]

{arch}/hello-world est la racine d'une arborescence assez profonde. Les « patch logs » sont stockés dans cette arborescence.

{arch}/=tagging-method est un fichier de configuration que vous pouvez utiliser pour personnaliser la procédure de nommage (naming conventions) qui s'applique à cette arborescence. Cela est expliqué dans un chapitre suivant (voir « Personnaliser les procédures de nommage de l'inventaire »).

Le concept d'inventaire par nom

(The Name-based inventory Concept)

Dans une arborescence de projet, certains fichiers et répertoires « font partie du code source » -- ils intéressent particulièrement arch. D'autres fichiers peuvent être des fichiers temporaires (scratch files), des sauvegardes générées par votre éditeur de texte et des fichiers temporaires (ou intermédiaires) générés par vos programmes. Ces fichiers devraient être ignorés ou traités spécifiquement par la plupart des commandes de arch.

Ce chapitre étudie comment arch reconnaît les fichiers auxquels il lui faut prêter attention et ceux qu'ils peut ignorer.

La commande d'inventaire

On utilise la commande tla inventory --names --source pour afficher une liste de fichiers sources telle que déterminée par la convention de nommage. Cette commande reconnaît de nombreuses options, notamment les options qui permettent d'afficher d'autres types de de fichiers (telles que les listes de tous les fichiers de sauvegarde générés par l'éditeur de texte, ou une liste de tous les fichiers qui ne sont pas liés au code source).

Supposons qu'après l'avoir édité, notre arborescence ait cet air là :

% ls
hw.c            hw.c.~1~        main.c          {arch}

Le fichier hw.c.~1~ est un fichier de sauvegarde de l'éditeur de texte. tla le sait et omet ce fichier dans l'inventaire des sources :

% tla inventory --names --source
./hw.c
./main.c

tla peut afficher d'autres listes :

% tla inventory --names --backups
./hw.c.~1~

Les conventions de nommage de arch

Cette section décrit les conventions de nommage par défaut utilisées par arch pour sélectionner les fichiers sources et les distinguer des autres types de fichiers. Dans un prochain chapitre nous décrirons comment personnaliser ces procédures pour une arborescence particulière (voir : « Personnaliser la convention de nommage de l'inventaire »).

La convention de nommage est basée sur plusieurs catégories de fichiers :

L'algorithme de classification des fichiers par nom a plusieurs règles. Pour chaque nom de fichier, chacune de ces règles est vérifiée dans l'ordre listé ci-dessus. La première règle rencontrée qui correspond au classement est alors utilisée.

Fichiers exclus (dot files)

Les fichiers spéciaux . et .. sont toujours exclus des inventaires.

Les noms « non compatibles » (non portable) ne sont pas reconnus

Les noms de fichiers qui contiennent des espaces, des caractères non imprimables ou un « globbing-character » sont toujours classés comme non reconnus. Les « globbing-characters » sont :

? [ ] * \

Test des fichiers exclus

Si l'option --all n'est pas passée à la commande inventory, les noms de fichiers qui correspondent au motif d'exclusion sont exclus de la liste. Si le nom d'un répertoire est exclu, son contenu est également exclu. Par défaut, le motif d'exclusion des fichiers correspond au fichiers de contrôle créés par arch lui-même :

^(.arch-ids|\{arch\})$

Test des fichiers poubelles

Tous les noms de fichiers qui atteignent cette étape et qui commencent avec deux virgules (,,) sont classés comme « à jeter » (junk). Les fichiers temporaires créés par arch lui-même commencent par deux virgules. Par défaut, ce motif correspond aux noms de fichiers qui commencent par (au moins) une virgule :

^,.*$

Test des fichiers de sauvegardes

Par défaut, tout fichier qui atteint cette étape et qui correspond au motif suivant est considéré comme un fichier de sauvegarde :

^.*(~|\.~[0-9]+~)$
^.*\.bak|\.orig|\.rej|\.original|\.modified|\.reject)$

Test des fichiers précieux

Par défaut, tout fichier qui atteint cette étape et qui correspond au motif suivant :

^\+.*$
^(\.gdbinit|\.#ckpts-lock)$
^(=build\.*|=install\.*)$
^(CVS|CVS\.adm|RCS|RCSLOG|SCCS|TAGS)$

Test des fichiers suspects (non reconnus)

Certains noms de fichiers qui atteignent cette étape sont explicitement traités comme « non reconnus » en présumant qu'ils ne devraient probablement pas être présents dans une arborescence. Par défaut, les noms qui se terminent par une des extensions suivantes sont « non reconnus » :

.o
.a
.so
.core

Par ailleurs, le nom de fichier « core » est (par défaut) traité comme « non reconnu ».

Test des fichiers sources

Les fichiers qui atteignent cette étape sont comparés au motif des fichiers sources. Le motif par défaut est montré ci-dessous. On devrait noter que ce motif chevauche celui qui correspond aux fichiers « exclus » donné plus haut. Si l'option --all est passée à la commande inventory, le motif « exclus » n'est pas activé et les fichiers qui y correspondent « retombent » à une étape ultérieure de cet algorithme.

^([_=a-zA-Z0-9].*|\.arch-ids|\{arch\}|\.arch-project-tree)$

En d'autres termes, par défaut, les fichiers et les répertoires de contrôle d'arch sont les sources (si ils ne sont pas exclus). Les fichiers qui commencent par des lettres, des nombres, des underscores ou un signe équivalent sont des fichiers sources.

Fichiers non reconnus

Tout fichier laissé à cet étape est traité comme « non reconnu ».

Exemples de conventions de nommage

En s'appuyant sur notre exemple nous pouvons illustrer quelques-unes des conventions de nommage de fichiers.

Souvenez-vous que notre arborescence de projet a l'aspect suivant :

% ls
hw.c                hw.c.~1~        main.c          {arch}

Donc la liste standard des sources donne :

% tla inventory --names --source
./hw.c
./main.c

Et la liste de tous les fichiers sources (sans en exclure aucun) donne :

% tla inventory --names --source --all
./hw.c
./main.c
./{arch}/.arch-project-tree
./{arch}/=tagging-method

On peut inclure les répertoires dans la liste :

% tla inventory --names --source --all --both
./hw.c
./main.c
./{arch}
./{arch}/.arch-project-tree
./{arch}/=tagging-method
./{arch}/hello-world
./{arch}/hello-world/hello-world--mainline
[... sortie interrompue ...]

On peut aussi regarder les listes de fichiers non sources :

% tla inventory --names --backups
./hw.c.~1~

La commande inventory a de nombreuses options qu'on pourra explorer.

Personnaliser la convention de nommage

On peut modifier les motifs utilisés par inventory pour classer les fichiers. Ceci est expliqué dans un chapitre ultérieur (« Adaptation de la convention de nommage dans l'inventaire »).

À quoi bon tout cela ? -- Conventions de nommage d'inventaire

De nombreux systèmes fournissent des conventions de nommage pour reconnaître les fichiers sources mais les utilisateurs qui débutent avec arch se demandent souvent pourquoi arch a besoin de tant de catégories de fichiers. Souvenons-nous que arch utilise les catégories :

excluded
source
precious
junk
backups
unrecognized

Chaque catégorie est explicitée ci-dessous.

excluded

Est simplement là pour faire en sorte que les listes d'inventaires restent brèves, entendu que, dans la plupart des cas, les fichiers de contrôle de arch ne sont pas particulièrement utiles. C'est un peu pareil que le traitement des répertoires . et .. (dot files) par ls; de même l'option --all de la commande inventory est similaire à l'option -a de la commande ls.

source

Permet à arch de distinguer ces fichiers de manière fiable. Par exemple, lorsqu'il compare deux arborescences, arch ne compare que les fichiers de la catégorie source.

precious

Ces fichiers sont ceux pour lesquels arch devrait faire un effort afin de les préserver. Par exemple, si vous demandez à arch de faire une copie d'une arborescence de projet, il copiera les fichiers « précieux » en même temps que les fichiers « sources ». Supposons, par exemple, que vous prenez des notes pendant que vous travaillez sur votre code source. On ne souhaitera pas que nos notes soient prises pour nos sources, mais on ne voudra pas pour autant les perdre. Une astuce consiste à donner à ce fichier un « nom précieux » (par exemple : +notes).

junk

Il est souvent utile, lorsqu'on travaille sur un projet, de créer des fichiers « à effacer ». On pourrait vouloir compiler un petit programme de test ou sauvegarder, pour un moment, la sortie d'une commande. Lorsqu'on a accumulé plusieurs de ces fichiers à effacer, il peut être pratique de pouvoir s'en débarrasser d'un seul coup, sans avoir à méticuleusement les identifier et déterminer lequel jeter, lequel conserver. Les fichiers « junk » sont parfaits pour ça. Quand on crée un de ces fichiers à effacer, on lui donne un nom du type ,foo. Plus tard, on pourra tranquillement passer des commandes du type :

% rm ,*

% find . -name ',*' | xargs rm

% tla inventory --junk | xargs rm

Du point de vue de arch, les fichiers « junk » ont deux caractéristiques importantes. Tout d'abord, lorsqu'on copie une arborescence, les fichiers à effacer ne sont pas copiés. Ensuite, on considère comme sécurisant pour arch de pouvoir écraser un fichier à effacer. En fait, arch écrasera un fichier à effacer si ce nom de fichier commence par : ,.

backups

Les fichiers de sauvegardes des éditeurs de texte, ainsi que les fichiers de sauvegarde créés par les programmes tels que patch sont souvent traités de manière particulière. Par exemple, si votre éditeur crée des sauvegardes numérotées (numbered backups), ceux-ci sont presque des fichiers à effacer. Mais plutôt que de tous les effacer, on pourrait vouloir n'en effacer que certains.

Pour arch ce qui est important c'est que lors d'une copie d'arborescence, les fichiers de sauvegarde ne devraient pas être copiés. Pour les utilisateurs, ce qui est probablement le plus efficace est d'utiliser l'astuce suivante, qui n'effacera pas les fichiers de sauvegarde :

% tla inventory --junk | xargs rm

unrecognized

L'apparence d'un fichier qui ne correspond à aucun motif d'une arborescence (ou qui a un nom suspect) indique la plupart du temps que quelque chose n'est pas correct. Plutôt que d'ignorer ces fichiers ou de les traiter comme des fichiers précieux ou à effacer, arch les marque explicitement afin de pouvoir en avertir les utilisateurs.

Adopter les conventions de nommage des fichiers est une discipline que de nombreux programmeurs peuvent trouver inhabituelle, mais nous la recommandons pourtant fortement. Il est simple de suivre ces conventions et les outils tels que inventory et tree-lint (qui seront présentés plus tard) vous aideront à maintenir vos sources en évitant que leur contrôle vous échappe.

L'air d'un source ou source réel

Dans les chapitres précédents, nous avons vu comment trouver les fichiers par rapport à la convention de nommage :

% tla inventory --names --source
hw.c
main.c

Dans ce chapitre, il y a une nouvelle distinction : les fichiers qui ont l'air d'un source par rapport à leur nom, par rapport aux fichiers réellement sources.

Lorsque vous archivez votre projet dans l'archive, arch va stocker les fichiers qui sont réellement des sources et ignorer le reste. Nous pouvons demander quels sont les fichiers sources réels en omettant l'option --names de inventory :

% tla inventory --source
[no output]

C'est un peu plus intéressant si on inclut les propres fichiers de arch « fichiers et répertoires systèmes » dans le listing :

% tla inventory --source --all --both
{arch}
{arch}/.arch-project-tree
{arch}/=tagging-method
{arch}/hello-world
[....]

Mais ce qu'il faut noter ici c'est que hw.c et main.c ne sont pas listés. Arch pense que ce sont des sources par le nom seulement. La prochaine section indique le moyen de corriger ça, et la section d'après explique ce qui se passe réellement.

La commande add

Nous pouvons indiquer à arch que nos fichiers sont réellement des sources, et qu'ils doivent donc être archivés avec le projet, en utilisant la commande tla add :

% tla add hw.c
% tla add main.c

Et maintenant nous pouvons obtenir une meilleure réponse à :

% tla inventory --source
hw.c
main.c

Une commande complémentaire est tla delete :

% tla delete hw.c

Cela n'efface pas le fichier hw.c lui-même :

% ls
hw.c            hw.c.~1~        main.c          {arch}

mais ça l'efface de la liste officielle des sources :

% tla inventory --source
main.c

Pour la poursuite de nos exemples, nous devons remettre hw.c dans la liste :

% tla add hw.c

% tla inventory --source
hw.c
main.c

Regardons plus en profondeur ce qui se passe lorsque nous ajoutons des fichiers avec tla add.

Deux noms pour chaque fichier

Dans le monde de arch, chaque fichier source (et répertoire) de notre arborescence a deux noms : un « chemin d'accès » (file path) et un « identifiant d'inventaire » (inventory id).

Le « chemin d'accès » du fichier est le chemin relatif du fichier par rapport à la racine de l'arborescence. Il décrit où le fichier est placé dans l'arborescence.

L'« identifiant d'inventaire » du fichier est (généralement) une chaîne arbitraire unique du fichier dans l'arborescence. L'identifiant d'inventaire reste constant même si le fichier est renommé. Ainsi, alors que le chemin d'accès indique où le fichier est placé, l'identifiant d'inventaire indique quel fichier est stocké à cet endroit.

Le but de tla add est d'assigner un identifiant d'inventaire à un fichier.

Dans notre exemple, nous pouvons examiner les identifiants :

   % tla inventory --source --ids
   hw.c    x_very_long_string
   main.c  x_another_very_long_string
   ^^^^    ^^^^^^^^^^^^^^^^^^^^^^^^^^
    |                |
    |           inventory ids
file paths

Généralement, quand un fichier est déplacé, son emplacement change, mais son identifiant d'inventaire reste le même. La commande tla move nous aide pour cela. Supposons que nous fassions :

% mv hw.c hello.c

nous devrions faire ensuite :

% tla move hw.c hello.c

après quoi :

% tla inventory --source --ids
hello.c   x_very_long_string
main.c    x_another_very_long_string

Notez que hello.c a le même identifiant que celui que hw.c avait.

Nous reviendrons sur ce sujet du changement de nom plus tard, pour l'instant, revenons où nous avions démarré :

% mv hello.c hw.c
% tla move hello.c hw.c

Section rapide -- ajout de répertoires

La commande tla add peut s'appliquer aux répertoires également. Si nous avions ajouté un nouveau répertoire à l'arborescence, nous devrions l'ajouter par tla add :

% mkdir docs

% tla inventory --names --source --both
docs
hw.c
hello.c

mais

% tla inventory --source --both
hw.c
hello.c

jusqu'à

% tla add docs

et ensuite

% tla inventory --source --both
docs
hw.c
hello.c

Mais, à nouveau, pour la poursuite de notre exemple, nous n'avons pas besoin de docs. Nous pouvons faire simplement :

% rm -rf docs

Il n'est pas nécessaire d'utiliser tla delete pour un répertoire physiquement effacé.

Comment ça marche ? -- tla add

Ce que fait tla add est assez simple. Notez que quand nous avons ajouté hw.c et main.c, un nouveau répertoire a été créé :

% ls -a
.               .arch-ids       hw.c.~1~        {arch}
..              hw.c            main.c

.arch-ids est un nouveau répertoire :

% ls .arch-ids
hw.c.id         main.c.id

% cat .arch-ids/hw.c.id
very long string

Les données déterminant l'identifiant des fichiers sont stockées dans les fichiers *.id. La commande tla delete efface ces fichiers. La commande tla move les renomme.

L'identifiant d'un répertoire est stocké un peu différemment. Par exemple, quand nous avions créé le sous-répertoire docs et que l'avions ajouté avec tla add, cela a créé un fichier docs/.arch-ids/=id.

Garder les choses ordonnées et rangées

La commande :

% tla tree-lint

est utile pour garder les choses ordonnées et rangées.

tree-lint vous indiquera les identifiants pour lesquels le fichier n'existe pas. Il vous indiquera quels sont les fichiers qui passent la convention de nommage, mais pour lesquels il n'y a pas d'identifiant.

Il va également vous alerter pour les fichiers qui ne suivent pas la convention de nommage.

Identifiants d'inventaire -- Plusieurs façons de procéder

« there is more than one way to do it »

Dans ce chapitre, vous avez appris les commandes de base add, move, et delete.

Ces outils pour gérer les identifiants d'inventaire ont été choisis pour leur ressemblance, du moins superficielle, avec les commandes des systèmes tels que CVS dont de nombreux utilisateurs sont familiers.

Il y a d'autres façons de gérer les identifiants d'inventaires. Parfois les autres méthodes sont plus adaptées. Un chapitre supplémentaire devrait parler de ces techniques...

Pourquoi est-ce comme cela ? -- Le but des identifiants d'inventaire

Comme vous le verrez dans les chapitres suivants, arch est pratique pour gérer les modifications effectuées sur les arborescences et les fichiers qu'elles contiennent, et pratique pour vous indiquer l'historique des arborescences et fichiers.

Comme exemple, supposons qu'Alice et Bob soient tous les deux en train de travailler sur le projet hello-world. Dans son arborescence, Alice effectue quelques modifications sur hw.c. Dans son arborescence, Bob renomme hw.c en hello.c.

À un moment donné il est nécessaire de « synchroniser » Alice et Bob. Bob doit récupérer les modifications qu'Alice a effectuées. Alice doit récupérer le fichier renommé par Bob.

Arch fournit plusieurs mécanismes pour synchroniser -- c'est une des choses les plus importantes qu'il peut faire -- mais pratiquement toutes aboutissent au calcul et à l'application d'un changeset.

Alice peut demander à arch de créer un changeset décrivant le travail qu'elle a effectué, et ce changeset décrira les modifications qu'elle a apportées à hw.c. Bob peut créer un changeset et ce changeset décrira le renommage qu'il a effectué.

Si Alice applique le changeset de Bob à son arborescence, sa copie de hw.c devrait être renommée en hello.c. Mais un cas plus subtile est celui-ci : que ce passe-t-il si Bob applique le changeset d'Alice à son arborescence ?

Alice a modifié un fichier nommé ./hw.c, mais dans l'arborescence de Bob, cette même modification devrait être appliquée à un fichier nommé ./hello.c. Heureusement, ces deux fichiers ont le même identifiant d'inventaire :

file path               inventory id
---------               -------------

         Alice's tree:
./hw.c                  x_very_long_string
                                          \ 
                                           - the same long string
         Bob's tree:                      /
./hello.c               x_very_long_string

Dans le changeset d'Alice, les modifications sont décrites comme ayant été effectuées sur le fichier dont l'identifiant est x_very_long_string.

Ensuite, lorsqu'il est appliqué sur l'arborescence de Bob, arch sait qu'il faut appliquer les modifications sur le fichier ayant le même identifiant ; il sait donc que les modifications s'appliquent sur ./hello.c.

Cet exemple illustre l'utilité des identifiants d'inventaire : ils permettent à arch de décrire les modifications effectuées sur une arborescence en terme d'identité logique des fichiers plutôt que de leur emplacement physique. Il y a bien d'autres exemples plus complexes de l'utilisation des identifiants d'inventaire, mais maintenant vous avez vu le principe de base.

Pourquoi est-ce comme cela ? -- Pourquoi tla move ne déplace pas les fichiers ?

Pourquoi tla delete n'efface pas le fichier de l'arborescence ou tla move ne le renomme pas ?

Ces commandes permettent d'ajuster les identifiants dans une arborescence même si d'autres outils qui ne connaissent pas arch ont réarrangé les fichiers. Par exemple, si vous utilisez un « gestionnaire de fichiers » pour renommer vos fichiers, tla move sera toujours capable de prendre en compte les changements que le gestionnaire a effectué.

Cependant, il y a maintenant deux commandes qui modifient en même temps les identifiants et les fichiers correspondants : tla mv et tla rm. Elles fonctionnent comme leurs équivalents UNIX, avec en plus la gestion de l'identifiant.

Créer le premier fichier de log

Vous êtes sur le point de créer une nouvelle « révision » de hello-world dans votre archive : un enregistrement de ce projet à un instant donné.

Lorsque vous créez une révision, la première étape consiste à créer un fichier de log pour cette révision :

% cd ~/wd/hello-world

% tla make-log
++log.hello-world--mainline--0.1--lord@emf.net--2003-example

La sortie de cette commande est le nom d'un fichier que nous devons éditer. Au départ il contient :

Summary: 
Keywords: 

Vous devriez remplir ce fichier comme vous le feriez pour un email. Ajouter une description succinte de la révision dans le champ « Summary: », et une description complète dans le corps du message. Exactement comme un email, le corps du texte doit être séparé de l'entête par une ligne vide. Lorsque c'est fait, le log doit avoir cet aspect :

Summary: initial import
Keywords: 

Ceci est l'importation initiale de « hello-world »,
l'application qui tue tout et qui propulsera votre nouvelle
boite .com au zénith du succès.

% vi ./++log.hello-world--mainline--0.1--lord@emf.net--2003-example

ou, tout simplement :

% vi `tla make-log`

Stocker la première révision dans l'archive

Finalement, nous pouvons demander à arch d'ajouter nos sources à l'archive :

% tla import
[....]

Nous pouvons observer l'effet de bord de cette commande de plusieurs manières.

Nous pouvons demander à arch quelles révisions existent dans l'archive pour notre projet :

% tla revisions hello-world--mainline--0.1
base-0

En fait, nous pouvons obtenir plus de détails :

% tla revisions --summary --creator --date \
                  hello-world--mainline--0.1 
base-0
    2003-01-28 00:45:50 GMT
    Tom (testing) Lord <lord@emf.net>
    initial import

Qu'est-ce qui a changé dans notre arborescence ? Souvenez-vous que nous avons quelque chose appelé « patch log » :

% tla log-versions
lord@emf.net--2003-example/hello-world--mainline--0.1

Maintenant il y a un message :

% tla logs hello-world--mainline--0.1
base-0

% tla logs --summary --creator --date \
               hello-world--mainline--0.1
base-0
    2003-01-28 00:45:50 GMT
    Tom (testing) Lord <lord@emf.net>
    initial import

% tla cat-log hello-world--mainline--0.1--base-0
Revision: hello-world--mainline--0.1--base-0
Archive: lord@emf.net--2003-example
Creator: Tom (testing) Lord <lord@emf.net>
Date: Mon Jan 27 16:45:50 PST 2003
Standard-date: 2003-01-28 00:45:50 GMT
Summary: initial import
Keywords: 
New-files: ./hw.c ./main.c
New-patches: \
  lord@emf.net--2003-example/hello-world--mainline--0.1--base-0

Ceci est l'importation initiale de « hello-world »,
l'application qui tue tout et qui propulsera votre nouvelle
boite .com au succès.

Le nom des révisions importées

import a créé une nouvelle révision dans l'archive. Notez que cette révision est appelée base-0 et que nous pouvons former un nom plus complet de cette révision en le préfixant par la catégorie, la branche, et la version :

hello-world--mainline--0.1--base-0
^^^^^^^^^^^  ^^^^^^^^  ^^^  ^^^^^^
     |          |       |     |
     |          |       |    patch level name
     |          |       |
     |          |     version number
     |          |
     |     branch name
     |
 category name

Si nous y ajoutons le nom de l'archive, on obtient quelque chose appelé « nom pleinement qualifié de la révision » (fully qualified revision name), qui est un identifiant globalement unique de la révision :

lord@emf.net--2003-example/hello-world--mainline--0.1--base-0
^^^^^^^^^^^^^^^^^^^^^^^^^^
            |
      archive name

Les noms pleinement qualifiés vont être de plus en plus importants au fur et à mesure que vous étudierez les « dépôts répartis » dans les chapitres suivants.

Comment ça marche ? -- Que fait import ?

Regardons ce que import a fait au niveau de l'archive :

Allons dans le répertoire de notre version de travail

% cd ~/{archives}
% cd 2003-example/
% cd hello-world/
% cd hello-world--mainline/
% cd hello-world--mainline--0.1/
% ls
base-0

Il a créé un nouveau répertoire base-0 pour la nouvelle révision.

% cd base-0
% ls
+revision-lock
hello-world--mainline--0.1--base-0.src.tar.gz
log

Comme toujours, le fichier +revision-lock est utilisé par arch en interne pour garder l'archive dans un état cohérent dans toutes les circonstances.

Le fichier log est une copie du message de log que vous avez écrit, avec quelques entêtes supplémentaires :

% cat log
Revision: hello-world--mainline--0.1--base-0
Archive: lord@emf.net--2003-example
Creator: Tom (testing) Lord <lord@emf.net>
Date: Mon Jan 27 16:45:50 PST 2003
Standard-date: 2003-01-28 00:45:50 GMT
Summary: initial import
Keywords: 
New-files: ./hw.c ./main.c
New-patches: \
  lord@emf.net--2003-example/hello-world--mainline--0.1--base-0

Ceci est l'importation initiale de « hello-world »,
l'application qui tue tout et qui propulsera votre nouvelle
boite .com au succès.

Finalement, le fichier compressé .tar.gz est une copie de l'arborescence de votre projet :

% tar ztf hello-world--mainline--0.1--base-0.src.tar.gz
hello-world--mainline--0.1--base-0/
hello-world--mainline--0.1--base-0/hw.c
hello-world--mainline--0.1--base-0/main.c
hello-world--mainline--0.1--base-0/{arch}/
hello-world--mainline--0.1--base-0/{arch}/.arch-project-tree
hello-world--mainline--0.1--base-0/{arch}/=tagging-method
hello-world--mainline--0.1--base-0/{arch}/hello-world/
[....]

Vous devriez noter que le fichier tar n'inclut pas tous les fichiers de votre arborescence. Il contient spécifiquement les fichiers listés par :

% cd ~/wd/hello-world

% tla inventory --source --both --all
[....]

Finalement, si vous parcourez le répertoire {arch} de votre arborescence, vous verrez deux nouvelles données :

% ls
++default-version       =tagging-method
++pristine-trees        hello-world

Le répertoire ++pristine-trees contient (à une certaine profondeur) une copie de l'arborescence que vous venez d'importer. C'est une copie mise en cache utilisée par certaines commandes de arch. (À noter : dans les prochaines versions de arch, le répertoire ++pristine-trees sera remplacé par un mécanisme différent).

Si vous creusez, dans le répertoire patch-log de hello-world, vous trouverez une copie du fichier de log de la révision que vous venez de créer (avec quelques entêtes supplémentaires).

warld != world\n

si vous regardez le source, vous noterez une faute d'orthographe et un bogue sur le retour à la ligne :

% cat hw.c

#include <stdio.h>

void
hello_world (void)
{
  (void)printf ("hello warld");
}

C'est clair, nous voulions dire « hello world », pas « hello warld », et nous voulions probablement un retour à la ligne à la fin du message. Réparons ces bogues maintenant.

Quelques conseils gratuits sur les messages de log

Les conseils gratuits méritent d'être payés

anonyme

Voilà le plan : nous modifierons le source pour réparer les bogues. Ensuite nous demanderons à arch d'archiver les modifications nécessaires pour réparer ces bogues. Cette seconde étape va créer une nouvelle révision dans l'archive.

Comme nous l'avons noté précédement, à chaque fois que vous créez une nouvelle révision, vous devez fournir un message de log pour cette révision (voir « Créer le premier fichier de log »).

Les bogues particuliers que nous sommes en train de réparer dans notre exemple ludique sont simplistes -- mais dans une situation réelle, ils seront sûrement plus complexes. Nous avons le choix : vous pouvez soit attendre que les modifications soient effectuées pour écrire le message de log décrivant vos changements, soit écrire le message de log au fur et à mesure.

Voici le conseil gratuit : écrivez le message de log au fur et à mesure. En d'autres termes, prenez des notes en cours de travail. Au niveau des commandes tla ça signifie que vous devez démarrer le processus de correction des bogues par :

% cd ~/wd/hello-world

tla make-log
++log.hello-world--mainline--0.1--lord@emf.net--2003-example

Ensuite éditez votre nouveau fichier de log pour y lire :

Summary: Réparation des bogues dans la chaine "hello world"
Keywords: 

Le « Summary » décrit ce que vous êtes censé effectuer comme nouvelles modifications. En cours de travail, vous pouvez remplir le corps du message de log.

Le cycle modification/mise à jour du log

Mettons que ces bogues soient plus complexes qu'ils ne le sont actuellement, voilà comment le travail pourrait se dérouler :

Change warld en world.

Mise à jour du message de log.

Ajoutez une note au fichier de log :

Summary: Réparation des bogues dans la chaine "hello world"
Keywords: 

Écriture correcte de "world" (et non "warld").

Ajout d'un retour à la ligne à la chaine.

Mise à jour du message de log à nouveau.

Summary: Réparation des bogues dans la chaine "hello world"
Keywords: 

Écriture correcte de "world" (et non "warld").

Ajout d'une nouvelle ligne à la chaine "hello world"

Oh mon dieu -- Qu'ai-je fait ?

Vous venez juste d'effectuer un long et difficile travail pour réparer ces bogues. Ne serait-ce pas une bonne idée que de revoir ce que vous avez fait avant de le publier ?

Pas de problème, arch est là pour ça :

% tla changes --diffs
[....]
*** patched regular files

**** ./hw.c
[....] 
     @@ -4,7 +4,7 @@
      void
      hello_world (void)
      {
     -  (void)printf ("hello warld");
     +  (void)printf ("hello world\n");
      }
[....]

Aha ! maintenant nous savons. C'est le moment d'archiver ces modifications.

Enregistrer les changements dans l'archive

Maintenant, enregistrons ces changements dans l'archive.

Si vous n'avez pas tenu compte de notre conseil gratuit (voir Quelques conseils gratuits sur les messages de log), c'est maintenant le moment de créer le message de log (astuce : tla make-log).

Pour sauvegarder vos changements dans l'archive, simplement :

% tla commit
[....]

Après ce commit, il y a une nouvelle révision dans l'archive.

% tla revisions hello-world--mainline--0.1
base-0
patch-1

ou, en plus détaillé :

% tla revisions --summary hello-world--mainline--0.1
base-0
    initial import
patch-1
    Réparation des bogues dans la chaine "hello world"

Notre arborescence de patch-log a également été mise à jour :

% tla logs hello-world--mainline--0.1
base-0
patch-1

% tla logs --summary hello-world--mainline--0.1
base-0
    initial import
patch-1
    Réparation des bogues dans la chaine "hello world"

Comment ça marche ? -- Archiver une nouvelle révision

Que fait commit au niveau de l'archive ?

Allons dans le répertoire de la version dans laquelle nous travaillons

% cd ~/{archives}
% cd 2003-example/
% cd hello-world/
% cd hello-world--mainline/
% cd hello-world--mainline--0.1/
% ls
+version-lock   =README         base-0          patch-1

Le sous-répertoire patch-1 est nouveau :

% cd patch-1

% ls
+revision-lock
hello-world--mainline--0.1--patch-1.patches.tar.gz
log

Comme d'habitude, le fichier de log est celui que vous avez écrit, avec quelques entêtes supplémentaires :

% cat log
Revision: hello-world--mainline--0.1--patch-1
Archive: lord@emf.net--2003-example
Creator: Tom (testing) Lord <lord@emf.net>
Date: Mon Jan 27 22:26:13 PST 2003
Standard-date: 2003-01-28 06:26:13 GMT
Summary: Réparation des bogues dans la chaine "hello world"
Keywords: 
New-files: \
  {arch}/hello-world/ [....] /patch-log/patch-1
Modified-files: hw.c
New-patches: \
  lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

Écriture correcte de "world" (et pas "warld").

Ajout d'un retour à la ligne à la fin de la chaine.

Le fichier .patches.tar.gz est appelé un changeset. Il décrit les changements que vous avez effectués par les différences entre la révision base-0 et la révision patch-1. Vous en apprendrez davantage sur la nature des changesets dans les chapitres suivants. Pour l'instant, vous pouvez considérer un changeset comme un équivalent de la sortie d'un diff -r qui serait utilisé pour comparer la révision base-0 d'avant vos changements, avec l'arborescence d'après vos changements (ou, comme dirait un utilisateur de arch : un « patch set on steroids »).

Dans l'arborescence du projet :

% cd ~/wd/hello-world

La commande commit a eu deux effets. Premièrement, elle a ajouté un fichier de log dans {arch}/hello-world. Deuxièmement, elle a modifié {arch}/++pristine-trees pour contenir une copie mise en cache de la révision patch-1 à la place de la révision base-0.

Récupérer la dernière révision

Vous devriez également avoir une arborescence en plus. Si c'est le cas, débarrassons-nous en :

% cd ~/wd

% ls
hello-world

% rm -rf hello-world

Supposons maintenant que vous vouliez récupérer les derniers sources du projet hello-world. Pour cela, vous utiliserez la commande get :

% tla get hello-world--mainline--0.1 hello-world
[...]


% ls 
hello-world

% ls hello-world
hw.c    main.c  {arch}

Récupérer une révision antérieure

Supposons que nous voulions récupérer une version antérieure du projet hello-world.

Notez que dans l'exemple précédent, nous avons simplement demandé une version particulière du projet :

% tla get hello-world--mainline--0.1 hello-world
          ^^^^^^^^^^^  ^^^^^^^^  ^^^ ^^^^^^^^^^^
               |           |      |       |
               |           |      |  target directory
               |           |      |
               |           |      |
               |           |   version number
               |           |
               |      branch name
               |
         category name

Nous pouvons récupérer une version antérieure en spécifiant son niveau de patch explicitement :

% tla get hello-world--mainline--0.1--base-0 hello-world-0
          ^^^^^^^^^^^  ^^^^^^^^  ^^^  ^^^^^^ ^^^^^^^^^^^^^
               |           |      |      |        |
               |           |      |      |  target directory
               |           |      |      |
               |           |      | patch level name
               |           |      |
               |           |   version number
               |           |
               |      branch name
               |
         category name


% ls
hello-world     hello-world