Bazaar

Bazaar

 




Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Page de référence : {en} IntroductionToBzr

Introduction

Si vous être déjà familier des contrôles de révisions décentralisés, vous êtes libre de passer directement à la section "Présentation de Bazaar-NG". Si, d'un autre côté, vous êtes familier des contrôles de révisions mais non décentralisés, vous pouvez commencer directement à la section "Comment les DRCS sont différents". Sinon, prenez un peu de café ou de thé, installez-vous confortablement et soyez prêt à suivre attentivement ce document.

Les objectifs du Contrôle des Révisions

Il est probable que vous travailliez sur différentes sortes de données textuelles -- les sources d'un programme, des sites web ou les fichiers de configuration qu'un administrateur système Unix doit gérer dans /etc. Il y a de fortes chances que vous aillez fait toute sorte d'erreurs que vous avez profondément regretté. Peut-être que vous avez supprimé le fichier de configuration de votre serveur d'e-mails ou bien que vous avez malmené le code source d'un projet que vous développiez. Quoi qu'il se fut passé, vous avez simplement supprimé une information importante que vous auriez désespérément aimé récupérer. Si ceci vous ait déjà arrivé, vous êtes donc probablement prêt pour Bazaar-NG.

Les systèmes de contrôle des révisions (que nous appellerons par la suite RCS -- NdT: Revision Control System) tels que Bazaar-NG vous donne la possibilité de suivre les changements d'un répertoire en le transformant en quelque chose d'un peu plus compliqué qu'un simple répertoire et que nous appellerons une branche. Une branche ne stocke pas uniquement l'état actuel du contenu d'un répertoire, mais aussi certains états dans le passé. Grâce à cela, lorsque vous faite quelque chose que vous souhaiteriez ne pas avoir fait, vous pouvez restaurer le répertoire, c'est-à-dire remettre son contenu dans un état passé.

Les systèmes de contrôle des révisions donnent aux utilisateurs la possibilité de sauvegarder les changements d'une branche en "committant une révision". La révision créée est essentiellement un résumé des changements qui ont été faits depuis la dernière fois que l'arborescence a été sauvegardé.

Ces révisions ont d'autres utilités très pratiques. Par exemple, on peut commenter les révisions pour expliquer ce que le récent ensemble de changements signifie en fournissant un message optionnel de log. Les messages de log permettent des choses du genre "Fixed the web template to close the table" et "Added sftp suppport. Fixes #595"

Ces logs sont conservées dont si plus tard il y a un problème avec sftp, on peut déceler quand le problème est probablement apparu.

Comment les DRCS sont différents

Beaucoup de systèmes de contrôle des révisions (RCS -- NdT: Revision Control Systems) sont stockés sur des serveurs. Si on veut travailler sur le code stocké dans un de ces RCS, on a besoin de se connecter au serveur et récupérer (checkout) le code. Ceci donne un répertoire dans lequel on peut fait des changements et committer. Le client RCS se connecte donc au serveur RCS et stocke les changements. Cette méthode est connue sous le nom de modèle centralisé.

Le modèle centralisé peut avoir quelques inconvénients. Un RCS centralisé requiert que l'on soit capable de se connecter au serveur lorsqu'on veut faire une opération de contrôle de versions. Ceci peut-être problématique si votre serveur est sur une quelconque autre machine sur internet mais pas vous. Ou, pire encore, vous êtes sur internet mais le serveur est en panne !

Les systèmes décentralisés de contrôle des révision (que nous appellerons par la suite DRCS -- NdT: Decentralized Revision Control Systems) résout ce problème en conservant les branches sur la même machine que le client. Dans le case de Bazaar-NG, la branche est conservée dans le même endroit que le code dont s'applique le contrôle de versions. Cela permet à l'utilisateur de sauvegarder ses changements (committer) lorsqu'il le souhaite -- même si il est hors-ligne. L'utilisateur n'a besoin d'un accès internet que quand il veut accéder aux modifications d'une branche de quelqu'un d'autre.

Beaucoup de gens ont fréquemment besoin de garder le suivi des changements pour un répertoire, tel que les changements de fichiers et sous-répertoires. Réaliser ce suivi à la main est une opération horrible qui avec le temps devient ingérable. Enfin, jusqu'à ce qu'on considère les outils de contrôle de versions tels que Bazaar-NG. Ces outils automatise l'opération de stockage de donnée en créant une révision de l'arborescence des répertoire lorsque l'utilisateur le demande.

Un logiciel de contrôle des révisions tel que Bazaar-NG peut fait plus que de simples stockage et restauration des changements. Par exemple, avec Bazaar-NG, un développeur peut prendre les modifications d'une branche du logiciel et les appliquer à une autre branche, parente ou dérivée -- même si ces changements existent dans une branche appartenant à quelqu'un d'autre. Ceci permet aux développeurs de coopérer sans donner d'accès en écriture au dépôt.

Bazaar-NG se souvient de l'ascendance d'une révision : les révisions précédentes sur lesquelles elle est basée. Une simple révision peut avoir plusieurs descendants directs, chacun avec des changements différents, représentant une divergence dans l'évolution de l'arborescence. Grâce aux systèmes de branches, Bazaar-NG permet à de multiples utilisateurs de coopérer sur l'évolution d'un projet, sans tous avoir besoin de travailler avec un système strict de verrouillage. Les branches peuvent être très utiles même pour un développeur solitaire.

Présentation de Bazaar-NG

Bazaar-NG installe une seule nouvelle commande, bzr. Tout le reste est une sous-commande de celle-ci. Vous pouvez obtenir de l'aide avec  bzr help . Nous verrons d'autres sous-commandes par la suite.

Une fonction d'un système de contrôle de versions est de conserver le suivi de qui a changé quoi. Dans un système décentralisé, cela implique un identifiant pour chaque auteur qui soit mondialement unique. La plupart des gens en ont déjà un : leur adresse e-mail. Bzr est assez intelligent pour générer automatiquement une adresse e-mail en récupérant vos nom d'utilisateur et de machine. Si vous ne voulez pas que Bazaar-NG procède comme cela, trois autres solutions existent :

  1. (Bazaar-NG 0.6 et plus). Définir votre adresse e-mail dans $HOME/.bazaar/bazaar.conf en ajoutant les lignes suivantes. Merci de noter que [DEFAULT] est insensible à la casse :

    •     [DEFAULT]
          email= Votre nom <email@isp.com>
  2. (Bazaar-NG 0.6 et plus). Redéfinir l'affectation précédente pour certaines branches données en créant une section de branche dans $HOME/.bazaar/branches.conf en ajoutant les lignes suivantes :

    •     [/le/repertoire/vers/la/branche]
          email=Votre nom <email@isp.com>
  3. Redéfinir les valeurs précédentes en affectant votre adresse e-mail complète à la variable d'environnement globale $BZREMAIL ou $EMAIL ($BZREMAIL sera prioritaire).

Créer une branche

L'historique est stockée par défaut dans le répertoire .bzr de la branche. Il y aura une possibilité de la stocker dans un dépôt séparé, qui peut être sur une machine distante. Nous créons une nouvelle branche en exécutant bzr init dans un répertoire existant :

    % mkdir tutorial
    % cd tutorial
    % ls -a
    ./  ../
    % pwd
    /home/mbp/work/bzr.test/tutorial
    %
    % bzr init
    % ls -aF
    ./  ../  .bzr/
    %

Comme pour CVS, il y a trois états de fichiers : inconnu (unknown), ignoré (ignored), et versionné (versioned). La commande add rend un fichier versionné : c'est-à-dire que ses changements seront enregistrés par le système :

    % echo 'hello world' > hello.txt
    % bzr status
    unknown:
      hello.txt
    % bzr unknowns
    hello.txt
    % bzr add hello.txt
    added hello.txt
    % bzr unknowns

Si vous ajoutez le mauvais fichier, vous pouvez utiliser bzr remove pour le rendre à nouveau non versionné. Dans ce cas-ci, la copie de travail ne sera pas supprimée, mais pourrait l'être dans d'autres cas (2).

[2](2) bzr remove supprimera la copie de travail si cette dernière est présentement versionnée, mais n'a pas été modifiée depuis le dernier commit. Vous pouvez forcer la conservation du fichier en ajoutant l'option --keep à la commande bzr remove, ou forcer sa suppression avec l'option --force.

Localisation des branches

Tout l'historique est stockée dans une branche, qui est juste un répertoire du disque dur contenant les fichiers de contrôle. Il n'y a pas de dépôt ou de base de données tels qu'utilisés dans svn ou svk.

  • (Il y a des propositions d'ajouter du stockage partagé entre des branches parentes.)

Vous pouvez faire référence à vos branches sur le système de fichier de votre ordinateur en donnant simplement le nom du répertoire contenant la branche. bzr supporte également l'accès aux branches via http, par exemple :

% bzr log http://bazaar-ng.org/bzr/bzr.dev/

En installant des plugins bzr vous pouvez aussi accéder à des branches via les protocoles sftp ou rsync.

Affichage des changements

Une fois que vous avez terminé un certain travail, vous voudriez le committer à l'historique des versions. Il est bon de committer assez souvent : lorsque vous faites marcher une nouvelle fonctionnalité, fixez un bug, ou améliorez du code ou de la documentation. C'est aussi de bon usage de vérifier que le code compile bien et passe son jeu de tests avant de committer, pour être sur que chaque révision n'entraîne pas une régression de la qualité du programme. Vous pouvez aussi retrouver vos changements, pour être sûr que que vous être en train de committer ce que vous aviez l'intention de committer, et comme une possibilité de repenser votre travail avant de l'enregistrer de manière permanente.

Deux commandes bzr sont particulièrement utiles ici : status et diff.

bzr status

La commande status vous indique quels changements ont été faits au répertoire de travail depuis la dernière révision.

% bzr status
modified:
  foo

Par défaut bzr status cache les fichiers "ennuyant" (boring), qui sont soit inchangés soit ignorés. Pour les voir aussi, utilisez l'option --all. La commande status peut optionnellement avoir en argument le nom de certains fichiers ou répertoire à vérifier.

bzr diff

La commande diff montre le texte complet des changements de tout les fichiers dans le format standard diff unifié. Il peut être redirigé à travers un tube vers beaucoup de programmes tels que patch, diffstat, filterdiff et colordiff :

    % bzr diff
    *** added file 'hello.txt'
    --- /dev/null 
    +++ hello.txt 
    @@ -1,0 +1,1 @@
    +hello world

Avec l'option -r, l'arborescence est comparée à une version antérieure, ou bien les différences sont montrées entre deux versions :

% bzr diff -r 1000..          # tout depuis r1000
% bzr diff -r 1000..1100      # changement depuis 1000 jusqu'à 1100

L'option --diff-options demande à bzr d'exécuter le programme externe diff avec des arguments définis. Par exemple :

% bzr diff --diff-options --side-by-side foo

Committer les changements

Quand l'état de l'arborescence de travail est satisfaisant, il peut être committé à la branche, créant ainsi une nouvelle révision qui conserve un cliché de l'état en cours.

bzr commit

La commande commit requiert un message décrivant les changements dans la révision à committer. Il enregistre aussi votre identifiant userid, la date, l'heure et le fuseau horaire actuels, ainsi que l'inventaire et le contenu de l'arborescence. Le message de commit est spécifié par l'option -m ou --message. Vous pouvez entrer un message de commit multi-lignes ; dans la plupart des shells vous pouvez le saisir en laissant les guillemets ouverts à la fin de la ligne.

    % bzr commit -m "added my first file"

Vous pouvez aussi utiliser l'option -F pour récupérer le message depuis un fichier. Certaines personnes aiment écrire des notes pour un message de commit pendant qu'ils travaillent, puis affichent le diff pour vérifier qu'ils ont bien fait ce qui ont dit qu'ils faisaient. (Ce fichier peut aussi est utile quand vous reprenez votre travail après une pause.)

Message depuis un éditeur de texte

Si vous n'utilisez ni l'option -m, ni -F alors bzr ouvrira un éditeur de texte pour que vous saisissiez un message. L'éditeur à exécuter est contrôlé par votre variable d'environnement $EDITOR ou (après Bazaar-NG 0.6) la composition d'un e-mail. Si vous quittez l'éditeur sans faire de modification, le commit sera annulé.

Commit sélectif

Si vous passez en argument des noms de fichiers ou de répertoires à la ligne de commande commit seuls les changements de ses fichiers seront committés. Par exemple :

 % bzr commit -m "documentation fix" commit.py

Par défaut bzr committe toujours tous les changements de l'arborescence, même si il est exécuté depuis un sous-répertoire. Pour committer seulement depuis le répertoire courant, utilisez :

 % bzr commit .

Supprimer les changements non committés

Si vous avez fait des changements et que vous ne voulez pas les garder, utilisez la commande revert pour revenir à la version immédiatement précédente. Utiliser bzr diff avant serait une bonne idée pour vois ce qui sera supprimé. Par défaut la commande revert restaure l'arborescence entière ; si des noms de fichiers ou de répertoires sont passés en arguments alors seulement ceux-là seront affectés. revert vide aussi la liste des révisions de fusion en attente.

Ignorer des fichiers

Beaucoup d'arborescence de sources contiennent des fichiers qui ne nécessitent pas d'être versionnés, tels que les fichiers de backup des éditeurs, mes fichiers objets ou bytecode et les programmes compilés. Vous pouvez simplement ne pas les ajouter, mais ils seraient toujours perçus comme des fichiers inconnus (unknown). Vous pouvez aussi dire à bzr de les ignorer en les ajoutant dans un fichier appelé .bzrignore à la racine de l'arborescence.

Ce fichier contient une liste de masques de fichiers (wildcards ou globs), une par ligne. Son contenu habituel ressemble à ceci :

    *.o
    *~
    *.tmp
    *.py[co]

Si un masque contient un slash, il est interprété comme un chemin d'accès relatif à la racine de l'arborescence ; autrement il est seulement interprété comme un nom de fichier. Donc, l'exemple précédent ignore *.o dans tous les sous-répertoires, alors que l'exemple ci-dessous ignore seulement config.h à la racine du projet et tous les fichiers HTML se trouvant dans le répertoire doc/ :

    ./config.h
    doc/*.html

Pour obtenir une liste des fichiers ignorés et quel masque ils vérifient, utilisez bzr ignored :

    % bzr ignored
    config.h                 ./config.h
    configure.in~            *~

Il peut arriver soit d'avoir un fichier versionné qui vérifie un des masques, soit de vouloir ajouter un fichier qui a déjà l'état d'ignoré. Retenez simplement que ces masques n'ont pas d'effet sur les fichiers versionnés ; ils déterminent seulement si un fichier non versionné est considéré comme inconnu ou ignoré.

Le fichier .bzrignore devrait normalement être versionné, ainsi les nouvelles copies de la branche considéreront les mêmes masques :

    % bzr add .bzrignore
    % bzr commit -m "Add ignore patterns"

Examiner l'historique

bzr log

La commande bzr log montre une liste des révisions précédentes. La commande bzr log --forward fait la même chose mais dans l'ordre chronologique inverse (les révisions les plus récentes sont affichées à la fin).

Comme avec bzr diff, bzr log supporte l'argument -r :

% bzr log -r 1000..          # Révision 1000 et toutes celles ultérieures
% bzr log -r ..1000          # Toutes les révisions jusqu'à la 1000 incluse
% bzr log -r 1000..1100      # Les changements depuis la 1000 jusqu'à la 1100
% bzr log -r 1000            # Uniquement les changements de la révision 1000

Statistiques d'une branche

La commande bzr info résume quelques informations à propos de l'arborescence de travail et de l'historique de la branche.

Les répertoires de gestion de versions ("versioning")

bzr gère les versions des fichiers et des répertoires de manière à ce qu'il puisse garder un suivi des renommages et les fusionnent intelligemment :

    % mkdir src
    % echo 'int main() {}' > src/simple.c
    % bzr add src
    % bzr status
    A       src/
    ?       src/simple.c
    % bzr add src/simple.c
    % bzr status
    A       src/
    A       src/simple.c

Supprimer et enlever des fichiers

Vous pouvez supprimer des fichiers ou répertoires en les supprimant juste du répertoire de travail. Ceci est un peu différent de CVS qui requiert que vous fassiez aussi un cvs remove.

bzr remove rend le fichier non versionné, et peut dans certains cas supprimer la copie de travail (2). Ceci est utile lorsque vous ajoutez le mauvais fichier, ou décidez qu'un fichier de devrait finalement pas être versionné.

    % rm -r src
    % bzr remove -v hello.txt
    ?       hello.txt
    % bzr status
    removed:
      hello.txt
      src/
      src/simple.c
    unknown:
      hello.txt

Si vous enlevez le mauvais fichier par accident, vous pouvez utiliser bzr revert pour le restaurer.

Gestion des branches ("branching")

Bien souvent, plutôt que de commencer votre propre projet, vous voudrez soumettre une modification à une projet existant. Vous pouvez récupérer une branche existante en copiant son répertoire, en décompressant un tarball ou en réalisant une copie à distance comme avec rsync. Vous pouvez aussi utiliser bzr pour récupérer une copie. Parce que cette nouvelle copie est potentiellement une nouvelle branche, la commande est appelée branch :

    % bzr branch http://bazaar-ng.org/bzr/bzr.dev 
    % cd bzr.dev

Ceci télécharge l'historique complet de cette branche, donc nous pouvons faire toutes les opérations dessus localement : log, annotation, création et fusion de branches. Il y aura une option pour récupérer uniquement une partie de l'historique si vous le souhaitez.

Suivre les changement en amont

Vous pouvez rester à jour avec la branche parente en extrayant (pull) ses changements :

    % bzr pull

Cette commande fonctionne uniquement si votre branche locale (de destination) inclue uniquement les changements de la branche parente et aucun commit local. Autrement, on dit que les branches ont divergé, et elle doivent à la place être fusionnées.

Fusionner des branches parentes

Si deux branches ont divergé (les deux ont des changements unique) alors bzr merge est la commande appropriée à utiliser. La fusion calculera automatiquement les changements qui existent dans la branche de référence et qui ne sont pas dans la vôtre, puis essaiera de les appliquer à votre branche.

  % bzr merge URL

Si il y a un conflit durant la fusion, 3 fichiers avec le même nom de base sont créés. Le nom du fichier contenant la version de base commune aux deux branches (sans aucune modification) a pour suffixe .BASE, le nom du fichier contenant vos modifications locales a pour suffixe .THIS et le nom du fichier contenant les modifications provenant de l'autre arborescence a pour suffixe .OTHER. En utilisant un programme tel que kdiff3, vous pouvez maintenant confortablement les fusionner en un seul fichier. Pour committer vous devez en renommer un avec le nom de fichier original (sans suffixe) et détruire les deux autres fichier. Tant qu'il existe des fichiers possédants le suffixe .BASE, .THIS ou .OTHER la commande commit se plaindra.

TODO: marqueurs de conflit à l'intérieur des fichiers ;

Publier votre branche

Vous n'avez pas besoin d'un serveur spécial pour publier une branche bzr, juste d'un serveur web normal. Il n'y a qu'à mettre en place un miroir des fichiers vers votre serveur, en incluant le répertoire .bzr. On peut publier une branche (ou les changements d'une branche) grâce à l'une des trois méthodes suivantes :

  • Rsync: rsync -avrz BRANCHE_LOCALE nom-serveur.com/ce/repertoire/la
  • (Après la 0.6): bzr push sftp://nom-serveur.com/ce/repertoire/la (sftp://nom-serveur.com/ce/repertoire/ doit déjà exister)
  • Le plugin push fourni avec {en} BzrTools