romain@931: \chapter{Un rapide tour de Mercurial} bos@95: \label{chap:tour-basic} bos@84: romain@931: \section{Installer Mercurial sur votre système} bos@84: \label{sec:tour:install} bos@84: huguesfrachon@942: Des paquetages binaires de Mercurial sont disponibles pour la plupart huguesfrachon@942: des systèmes d'exploitation, ce qui rend facile l'utilisation immédiate huguesfrachon@942: de Mercurial sur votre ordinateur. bos@85: bos@84: \subsection{Linux} bos@84: romain@931: Parce que chaque distribution de Linux a ses propres outils de gestion huguesfrachon@942: de paquets, politiques et rythmes de développements, il est difficile de huguesfrachon@942: donner un ensemble d'instructions fixes pour installer les binaires de romain@931: Mercurial. La version de Mercurial avec laquelle vous vous retrouverez huguesfrachon@942: dépendra grandement de l'activité de la personne en charge du paquetage romain@931: pour la distribution. romain@931: huguesfrachon@942: Pour rester simple, je me concentrerai sur l'installation de Mercurial romain@931: en ligne de commande, sous les plus courantes des distributions. La romain@931: plupart des distributions fournissent des gestionnaires graphiques de romain@931: paquetage qui vous permettront d'installer Mercurial en quelques clicks. romain@931: Le paquetage devrait se nommer \textit{mercurial}. bos@84: bos@85: \begin{itemize} bos@85: \item[Debian] bos@85: \begin{codesample4} bos@85: apt-get install mercurial bos@85: \end{codesample4} bos@84: bos@85: \item[Fedora Core] bos@85: \begin{codesample4} bos@85: yum install mercurial bos@85: \end{codesample4} bos@84: bos@85: \item[Gentoo] bos@85: \begin{codesample4} bos@85: emerge mercurial bos@85: \end{codesample4} bos@84: bos@85: \item[OpenSUSE] bos@85: \begin{codesample4} bos@85: yum install mercurial bos@85: \end{codesample4} bos@84: belaran@943: \item[Ubuntu] Le paquetage de Mercurial d'Ubuntu est construit sur celui de Debian. belaran@943: Pour l'installer, exécute simplement les commandes suivantes: bos@262: \begin{codesample4} bos@262: apt-get install mercurial bos@262: \end{codesample4} romain@931: Les paquetages Ubuntu pour Mercurial ont tendance à être un peu en retard belaran@943: par rapport au paquetage Debian (au moment de l'écriture de ce livre, il belaran@943: faut compter un peu près un retard de 7 mois), ce qui signifie que parfois belaran@943: sur Ubuntu, vous risquez de rencontrer des problèmes qui ont été corrigés belaran@943: depuis longtemps dans les paquetages Debian. bos@85: \end{itemize} bos@84: arne@264: \subsection{Solaris} arne@264: romain@931: SunFreeWare, à \url{http://www.saufreeware.com}, est une bonne source huguesfrachon@942: pour trouver un vaste nombre de paquets précompilés pour 32 ou 64 bits romain@931: Intel et les architecture Sparc, dont les versions courantes de Mercurial. arne@264: bos@84: \subsection{Mac OS X} bos@84: romain@931: Lee Cantey publie un installeur de Mercurial pour Mac OS~X sur le site romain@931: \url{http://mercurial.berkwood.com}. Ce paquetage fonctionne sur les huguesfrachon@942: architectures Intel-~et PowerPCC. Avant de vous en servir, vous devez romain@931: installer une version Universel MacPython~\cite{web:macpython}. C'est romain@931: assez facile à faire : suivez simplement les instructions sur le site romain@931: de Lee. romain@931: romain@931: Il est aussi possible d'installer Mercurial en utilisant Fink ou MacPorts, huguesfrachon@942: deux outils de gestion de paquetage libres pour Mac OS X. Si vous avez romain@931: Fink, utiliser \command{sudo fink install mercurial-py25}. Si vous avez romain@931: acPorts, \command{sudo port install mercurial}. simon@313: bos@84: \subsection{Windows} bos@84: romain@931: Lee Cantey publie aussi un installeur de Mercurial pour Windows sur le site romain@931: \url{http://mercurial.berkwood.com}. Ce paquetage n'a aucune dépendance romain@931: externe, il fonctionne ``tout court''. bos@84: bos@84: \begin{note} romain@931: Le version de Windows de Mercurial ne convertie pas automatiquement romain@931: les retour chariot Windows et Unix. Si vous désirez partager votre romain@931: travail avec des utilisateurs Unix, vous devez faire un peu de configuration romain@931: supllémentaire. XXX En dire plus. bos@84: \end{note} bos@84: romain@931: \section{Commencer à utiliser Mercurial} romain@931: romain@931: Pour commencer, nous utiliserons la commande \hgcmd{version} pour vérifier romain@931: si Mercurial est installé proprement. Les informations affichées sur la romain@931: version ne sont pas réellement importante en soit, c'est surtout de savoir romain@931: si elles s'affichent qui nous intéresse. bos@87: \interaction{tour.version} bos@87: romain@931: \subsection{L'aide intégrée} romain@931: romain@931: Mercurial fournit un système d'aide intégré, ce qui est inestimable quand romain@931: vous vous retrouvez coincé à essayer de vous rappeler comment lancer telle romain@931: ou telle commande. romain@931: Si c'est le cas, exécuter simplement \hgcmd{help}; il vous aidera à imprimer huguesfrachon@942: une brève liste de commandes, avec une description de ce qu'elles font. Si vous romain@931: demandez de l'aide sur une commande spécifique (voir ci dessous), il affichera huguesfrachon@942: des informations plus détaillées. bos@87: \interaction{tour.help} huguesfrachon@942: Pour un niveau d'informations encore plus détaillées (ce dont vous aurez rarement huguesfrachon@942: besoin), exécuter \hgcmdargs{help}{\hggopt{-v}}. L'option \hggopt{-v} est romain@931: l'abréviation de \hggopt{--verbose}, et indique à Mercurial d'afficher plus huguesfrachon@942: d'informations que d'habitude. romain@931: romain@931: \section{Travailler avec un dépot} romain@931: romain@931: Avec Mercurial, tout se déroule au sein du \emph{dépot}\footnote{NdT: Dépôt est huguesfrachon@942: la traduction que j'ai retenue pour tout l'ouvrage du terme anglais \textit{repository}}. huguesfrachon@942: Le dépôt d'un projet contient tous les fichiers qui ``appartiennent'' au projet. belaran@938: belaran@938: Il n'y a rien de particulièrement magique au sujet de ce dépot, c'est belaran@938: simplement une arboresence sur votre système de fichiers que Mercurial huguesfrachon@950: traite de manière spéciale. Vous pouvez renommer ou effacer ce répertoire huguesfrachon@950: 'importe quel moment, en utilisant la ligne de commande ou votre belaran@938: explorateur de fichiers. belaran@938: belaran@938: \subsection{Faire une copie locale de votre dépot} belaran@938: huguesfrachon@950: \emph{Copier} un dépôt est juste un peu spécial. Bien que vous belaran@938: puissiez utiliser une commande habituelle de copie pour copier belaran@938: votre dépôt, il vaut mieux utiliser une commande fournie par belaran@938: Mercurial. Cette commande est appelée \hgcmd{clone}, car elle belaran@938: crée une copie identique d'un dépôt existant. bos@87: \interaction{tour.clone} belaran@938: Si votre opération de clonage réussit, vous devriez maintenant belaran@938: avoir un répertoire local appelé \dirname{hello}. Ce répertoire belaran@938: contiendra quelques fichiers. bos@87: \interaction{tour.ls} belaran@938: Ces fichiers ont le même contenu et historique dans votre dépôt belaran@938: qu'ils ont dans le dépôt que vous avez cloné. belaran@938: belaran@938: Chaque dépôt Mercurial est complet, autonome et indépendant. Il huguesfrachon@950: contient sa propre copie privée des fichiers du projet et de leurs belaran@938: historiques. Le clone d'un dépôt se souvient de la localisation du belaran@938: dépôt à partir duquel il a été clôné, mais il ne communique pas avec belaran@938: ce dernier, ou un autre, à moins que vous ne lui demandiez. belaran@938: huguesfrachon@950: Ce que tout ceci signifie pour le moment est que nous sommes libres huguesfrachon@950: d'expérimenter avec ce dépôt, confiants dans le fait qu'il s'agit d'un huguesfrachon@950: ``bac à sable'' qui n'affectera personne d'autre. belaran@938: belaran@938: \subsection{Quel est le contenu d'un dépôt ?} belaran@938: belaran@938: Prêtons plus attention un instant au contenu d'un dépôt. Nous voyons huguesfrachon@950: qu'il contient un répertoire nommé \dirname{.hg}. C'est ici que Mercurial belaran@938: conserve toutes ses métadonnées. bos@88: \interaction{tour.ls-a} bos@88: belaran@938: Le contenu du répertoire \dirname{.hg} et ses sous répertoires sont les huguesfrachon@950: seuls propres à Mercurial. Tous les autres fichiers et répertoires dans belaran@938: le répertoire sont à vous, et vous pouvez faire ce que vous en voulez. belaran@938: belaran@938: Pour introduire un peu de terminologie, le répertoire \dirname{.hg} est huguesfrachon@950: un ``vrai'' dépôt, et tous les fichiers et les répertoires qui coexistent huguesfrachon@950: avec lui, sont désignés sous le nom de \emph{espace de travail}\footnote{NdT: belaran@938: \textit{working directory}}. Une manière facile de se rappeler cette belaran@938: distinction est de retenir que le \emph{dépôt} contient l'\emph{historique} belaran@938: de votre projet, alors que l'\emph{espace de travail} contient une \emph{copie belaran@938: précise}\footnote{NdT: Ce terme est une traduction du terme anglais belaran@938: \textit{snapshot}. Il est traduit ici pour faciliter la lecture, mais ne sera belaran@938: plus traduit par la suite.} de votre projet à un certain point de son belaran@938: historique. belaran@938: belaran@938: \section{Une ballade dans l'historique} belaran@938: belaran@938: Une des premières choses que vous aurez envie de faire avec un nouveau belaran@938: dépôt, sera de comprendre son historique. La commande \hgcmd{log} vous belaran@938: donne une vue de l'historique. bos@88: \interaction{tour.log} belaran@938: Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque belaran@938: révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous belaran@938: appelons chacun de ces évènements enregistrés un \emph{changeset}, parce belaran@938: qu'il contient un ensemble de mofications sur plusieurs fichiers. belaran@938: belaran@938: La commande \hgcmd{log} affiche ainsi ces informations: bos@88: \begin{itemize} belaran@938: \item[\texttt{changeset}] Ce champ contient un nombre, séparé par une huguesfrachon@950: virgule, d'une chaine hexadécimale. Il s'agit en effet d'\emph{identifiants} belaran@938: pour un \textit{changeset}. Il y a deux identifiants car le numéro de belaran@938: la révision est plus court et plus à facile à saisir qu'une séquence belaran@938: hexadécimale. huguesfrachon@950: \item[\texttt{utilisateur}] L'identité de la personne qui a créé ce belaran@938: \textit{changeset}. C'est un champ libre de forme, mais la plupart du belaran@938: temps il contient le nom et l'email de la personne. belaran@938: \item[\texttt{date}] La date et l'heure à laquelle le \textit{changeset} huguesfrachon@950: a été créé, ainsi que le \textit{timezone} dans laquelle il a été créé. %%%TODO: Translate 'timezone' properly huguesfrachon@950: (La date et l'heure sont locales à cette \textit{timezone}, elles indiquent huguesfrachon@950: donc quelle date et quelle il était pour la personne qui a créé ce %%%TODO: je suppose (quelle "heure") belaran@938: \textit{changeset}.) belaran@938: \item[\texttt{résumé}] La première du message que le créateur a associée à belaran@938: son \textit{changeset} pour le décrire. bos@88: \end{itemize} belaran@938: belaran@938: Par défaut, la commande \hgcmd{log} n'affiche qu'un résumé, il manque belaran@938: beaucoup de détails. belaran@938: belaran@938: belaran@938: La figure~\ref{fig:tour-basic:history} fournit un représentation graphique belaran@938: de l'historique du dépôt \dirname{hello}, pour rendre plus facile de voir belaran@938: dans quelle direction l'historique se ``déroule''\footnote{NdT: \textit{flowing in}.}. belaran@938: Nous reviendrons régulièrement à cette représentation dans ce chapitre et belaran@938: ceux qui suivent. bos@97: bos@96: \begin{figure}[ht] bos@96: \centering bos@96: \grafix{tour-history} belaran@938: \caption{Représentation graphique du dépôt \dirname{hello} } bos@99: \label{fig:tour-basic:history} bos@96: \end{figure} bos@96: huguesfrachon@950: \subsection{Changesets, révisions, et discuter avec les autres}%%%TODO: je propose : "discussion" (3 noms communs) huguesfrachon@950: huguesfrachon@950: Comme l'anglais est réputé pour être un langage maladroit, et que l'informatique huguesfrachon@950: est la source de bien des erreurs terminologiques (pourquoi utiliser un belaran@939: seul terme quand quatre feront l'affaire ?), la gestion de version a une huguesfrachon@950: variété de mots et de phrases qui veulent dire la même chose. Si vous belaran@939: parlez à quelqu'un de l'historique de Mercurial à d'autres personnes, huguesfrachon@950: %%%TODO: ça ne veut rien dire: il faut supprimer une des personnes : soit "quelqu'un", huguesfrachon@950: % soit "à d'autres personnes" huguesfrachon@950: vous constaterez que souvent le mot ``\textit{changeset}'' est compressé simplement huguesfrachon@950: en ``change'' ou (à l'écrit) ``cset'', et même parfois un belaran@939: \textit{changeset} simplement ``révision'', abrégé en ``rev''. belaran@939: belaran@939: Bien que le \emph{mot} que vous utilisez pour désigner le concept de belaran@939: \textit{changeset} importe peu, l'\emph{identifiant} que vous utilisez belaran@939: pour désigner un \emph{spécifique} \textit{spécifique} a une grande belaran@939: importance. Rappelez vous que le \textit{changeset} affiché par la belaran@939: commande \hgcmd{log} identifie un \textit{changeset} à la fois avec belaran@939: un numéro de révision et une séquence hexadécimale. belaran@939: bos@97: \begin{itemize} belaran@939: \item Le numéro de révision est \emph{seulement valable dans ce dépôt}, belaran@939: \item alors que la séquence hexadécimale est un \emph{identifiant huguesfrachon@950: permanent, et invariant } qui pourra toujours être associé au huguesfrachon@950: \textit{changeset} exact de \emph{chaque} copie de votre dépôt. bos@97: \end{itemize} belaran@939: belaran@939: La distinction est importante. Si vous envoyez un email à quelqu'un en belaran@939: parlant de la ``révision 33'', il est très probable que sa révision~33 belaran@939: \emph{ne sera pas la même} que la votre. La raison de ceci est que le belaran@939: numéro de révision dépend de l'ordre dans lequel les modifications sont huguesfrachon@950: arrivées dans le dépôt, et il n'y a aucune garantie que les mêmes changements belaran@939: soient arrivés dans le même ordre dans différents dépôts. Trois modifications belaran@939: $a,b,c$ peuvent aisément apparaitre dans un dépôt comme $0,1,2$, et dans belaran@939: un autre comme $1,0,2$. belaran@939: belaran@939: Mercurial utilise les numéro de révision uniquement comme des raccourcis huguesfrachon@950: pratiques. Si vous devez disctuer d'un \textit{changeset} avec quelqu'un, huguesfrachon@950: our faire un enregistrement d'un \textit{changeset} pour une quelquonque %%%TODO: our : "pour" ou "ou" belaran@939: raison (par exemple, un rapport de \textit{bug}), utilisez la séquence belaran@939: hexadécimale. belaran@939: belaran@939: \subsection{Afficher une révision spécifique} belaran@939: belaran@939: Pour réduire la sortie de \hgcmd{log} à une seule révision, utilisez huguesfrachon@950: l'option \hgopt{log}{-r} (ou \hgopt{log}{--rev}). Vous pouvez utiliser huguesfrachon@950: le numéro de révision ou la séquence hexadécimale comme identifiant, et belaran@939: vous demandez autant de révisions que vous le souhaitez. belaran@939: \interaction{tour.log-r} belaran@939: belaran@939: Si vous voulez voir l'historique de plusieurs révisions sans avoir à belaran@939: les énumérer, vous pouvez utiliser la \emph{\textit{range notation}} belaran@939: \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le belaran@939: laisse en anglais} qui vous permet d'exprimer l'idée ``je veux toutes belaran@939: les révisions entre $a$ et $b$, inclus''. bos@88: \interaction{tour.log.range} huguesfrachon@950: Mercurial respecte aussi l'ordre dans lequel vous spécifiez les belaran@939: révisions, ainsi \hgcmdargs{log}{-r 2:4} affichera $2,3,4$ alors que belaran@939: \hgcmdargs{log}{-r 4:2} affichera $4,3,2$. belaran@939: belaran@939: \subsection{Informations détaillées} bos@91: belaran@948: huguesfrachon@950: Si le résumé affiché par \hgcmd{log} est utile si vous savez déjà ce %%%TODO: je pense que le premier "si" est de trop belaran@940: que vous cherchez. Vous aurez probablement besoin de voir un description belaran@940: complète du changement, ou une liste des fichiers modifiés. Si vous huguesfrachon@950: cherchez à déterminer si ce \textit{changeset} est bien celui que vous%%%TODO: les propositions sont mal construites : après un "si...." il faut une proposition sans "si... donc ici : "si ... recherchez", ben quoi ? belaran@940: recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou belaran@940: \hgopt{--verbose}) vous donne des informations supplémentaires. bos@91: \interaction{tour.log-v} bos@91: belaran@949: Si vous voulez voir à la fois la description et le contenu d'une belaran@949: modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}). belaran@949: Ceci affiche le contenu d'une modification comme un \emph{diff unifié} belaran@949: \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff huguesfrachon@950: unifié avant, consultez la section~\ref{sec:mq:patch} pour un rapide belaran@949: survol). belaran@948: bos@91: \interaction{tour.log-vp} bos@91: belaran@940: \section{Tout sur les options de commandes} belaran@940: belaran@946: belaran@940: Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial, huguesfrachon@950: étudions un moment comment elles fonctionnent de manière générale. Vous belaran@940: trouverez ça probablement utile pour la suite de notre parcours. belaran@940: huguesfrachon@950: Mercurial a une manière approche directe et cohérente pour interpréter %%%TODO: une manière d'approche ? belaran@940: les options que vous passez aux commandes. Il suit une convention commune belaran@940: à la plupart des systèmes Unix et Linux modernes. belaran@940: bos@91: \begin{itemize} belaran@947: \item Chaque option a un nom complet. Par exemple, comme nous l'avons déjà huguesfrachon@950: vu, la command e\hgcmd{log} accepte l'option \hgopt{log}{--rev}.%%%TODO: commande ou command e\hgcmd...? huguesfrachon@950: \item La plupart des options disposent de noms abrégés. Aussi, au lieu d'utiliser belaran@947: \hgopt{log}{--rev}, vous pouvez utiliser \hgopt{log}{-r}. (Les options qui huguesfrachon@950: n'ont pas de noms abrégés sont généralement rarement utilisées, c'est pour ça). huguesfrachon@950: \item Les noms complets commencent par deux tirets (i.e.~\hgopt{log}{--rev}), belaran@947: alors que les options courtes commencent avec un seul (i.e.~\hgopt{log}{-r}). huguesfrachon@950: \item Les noms des options sont cohérents entre les commandes. Par exemple, belaran@947: chaque commande qui accepte un \textit{changeset~ID} ou une numéro de révision belaran@947: accepte aussi \hgopt{log}{-r} et \hgopt{log}{--rev} comme arguments. belaran@947: %TODO: Small mistake here, shouldn't have log here... shouldn't it ? bos@91: \end{itemize} belaran@947: huguesfrachon@950: Dans les exemples de ce livre, j'utilise les noms abrégés plutôt que les noms huguesfrachon@950: complets. Ceci est une préférence personnelle, pas une recommandation. huguesfrachon@950: huguesfrachon@950: La plupart des commandes qui affichent une quelquonque sortie à l'écran, belaran@947: afficheront plus avec l'option \hggopt{-v} (ou \hggopt{--verbose}), et huguesfrachon@950: moins avec l'option \hggopt{-q} (ou \hggopt{--quiet}). belaran@947: belaran@947: \section{Faire et vérifier des modifications} belaran@947: huguesfrachon@950: Maintenant que nous avons une bonne idée des commandes pour consulter huguesfrachon@950: l'historique de Mercurial, regardons comment faire des modifications et huguesfrachon@950: les examiner. huguesfrachon@950: belaran@947: belaran@947: La première chose que nous allons faire c'est isoler notre expérience dans belaran@947: un dépôt à part. Nous allons utiliser la commande \hgcmd{clone}, mais nous belaran@947: n'avons pas besoin de faire une copie de dépôt distant. Comme nous avons belaran@947: déjà une copie locale, nous pouvons juste faire un clone de celle ci à la belaran@947: place. C'est beaucoup plus rapide que de faire une copie à travers le huguesfrachon@950: réseau, et un dépôt cloné localement prend moins d'espace disque aussi. belaran@947: bos@91: \interaction{tour.reclone} belaran@947: belaran@947: On notera au passage qu'il est souvent considéré comme une bonne pratique belaran@947: de conserver une copie ``immaculée'' du dépôt distant, à partir de laquelle belaran@947: vous pourrez faire des copies locales temporaires pour créer des ``bacs à belaran@947: sable'' pour chaque tâche sur laquelle vous souhaitez travailler. Ceci vous huguesfrachon@950: permet de travailler sur plusieurs choses en parallèle, chacune isolée les huguesfrachon@950: unes des autres en attendant que ces tâches soient finies et que vous soyez huguesfrachon@950: prêt à les réintégrer. Parce que les copies locales sont peu coûteuses, il belaran@947: est très rapide de créer ou détruire des dépôts dès que vous en avez besoin. belaran@947: belaran@947: %% Note: la dernière phrase n'est pas une traduction littérale, mais je belaran@947: %% pense qu'elle exprime plus clairement en français ce que veut dire son belaran@947: %% équivalent anglais. belaran@947: belaran@947: Dans notre dépôt \dirname{my-hello}, nous avons un fichier \filename{hello.c} belaran@947: qui contient le classique programme ``hello, world''. Nous allons utiliser belaran@947: l'ancienne et vénérable commande \command{sed} pour l'éditer pour qu'il belaran@947: affiche une seconde ligne à l'écran. (J'utilise \command{sed} seulement parce huguesfrachon@950: qu'il est facile d'écrire des exemples sous forme de script ainsi. Comme belaran@947: vous n'avez pas ces contraintes, vous n'utiliserez probablement pas \command{sed} belaran@947: mais plutôt votre éditeur de texte favori). belaran@947: bos@91: \interaction{tour.sed} bos@91: belaran@947: La commande \hgcmd{status} de Mercurial nous dira de quels fichiers Mercurial belaran@947: s'occupe au sein de ce dépôt. bos@91: \interaction{tour.status} belaran@947: La commande \hgcmd{status} n'affiche rien sur la sortie pour quelques fichiers belaran@947: mais une ligne commence par ``\texttt{M}'' for \filename{hello.c}. À moins que belaran@947: vous ne lui indiquiez de le faire, \hgcmd{status} n'affichera aucune sortie belaran@947: pour les fichiers qui n'ont pas été modifiés. belaran@947: belaran@947: Le caractère ``\texttt{M}'' indique que Mercurial a remarqué que nous avions belaran@947: modifié le fichier \filename{hello.c}. Nous n'avons pas besoin d'\emph{informer} belaran@947: Mercurial que nous allons modifier un fichier avant de le faire, ou que nous belaran@947: venons de le modifier, il est capable de s'en rendre compte tout seul. belaran@947: belaran@947: C'est pratique de savoir que nous avons modifié \filename{hello.c}, mais il belaran@947: serait encore plus pratique de savoir ce que nous avons modifié exactement. Pour belaran@947: cela, nous avons la commande \hgcmd{diff}. belaran@947: bos@91: \interaction{tour.diff} bos@91: belaran@947: \section{Enregister les modifications dans un nouveau \textit{changeset}} belaran@947: belaran@947: Nous pouvons modifier des fichiers, compiler et tester nos modifications, belaran@947: et utiliser les commandes \hgcmd{status} and \hgcmd{diff} pour voir les huguesfrachon@950: modifications effectuées, jusqu'au moment où nous serons assez satisfaits huguesfrachon@950: pour décider d'enregistrer notre travail dans un \textit{changeset}. belaran@947: belaran@947: La commande \hgcmd{commit} vous laisse créer un nouveau \textit{changeset}, belaran@947: nous désignerons généralement cette opération par ``faire un commit'' ou huguesfrachon@950: ``commiter''\footnote{NdT: De mon expérience, la plupart des francophones belaran@947: utilisent régulièrement, à l'oral, cette expression, mais bien évidement belaran@947: il ne s'agit pas d'un terme terminologiquement correct, ni même français.} belaran@947: belaran@947: \subsection{Définir le nom d'utilisateur} belaran@947: huguesfrachon@950: Quand vous exécutez la commande \hgcmd{commit} pour la première fois, elle huguesfrachon@950: n'est pas garantie de réussir. Mercurial enregistre votre nom et votre belaran@947: adresse avec chaque modification que vous effectuez, de manière à ce que belaran@947: vous soyez capable (ou d'autres le soient) de savoir qui a fait quelle belaran@947: modification. Mercurial essaye automatiquement de découvrir un nom huguesfrachon@950: d'utilisateur qui ait un minimum de sens pour effectuer l'opération belaran@947: de \textit{commit} avec. Il va essayer chacune des méthodes suivantes, belaran@947: dans l'ordre: bos@174: \begin{enumerate} belaran@947: \item Si vous spécifiez l'option \hgopt{commit}{-u} avec la commande belaran@947: \hgcmd{commit}, suivi d'un nom d'utilisateur, ceci aura toujours la belaran@947: priorité sur les autres méthodes ci dessous. belaran@947: \item Si vous avez défini une variable d'environement \envar{HGUSER}, belaran@947: c'est cette valeur qui est alors utilisée. huguesfrachon@950: \item Si vous créez un fichier nommé \sfilename{.hgrc} dans votre belaran@947: répertoire \textit{home}, avec une entrée \rcitem{ui}{username}, belaran@947: c'est la valeur associée qui sera utilisée. Pour voir à quoi belaran@947: ressemble le contenu de ce fichier regardez la belaran@947: section~\ref{sec:tour-basic:username} ci dessous. belaran@947: \item Si vous avez défini une variable d'environement \envar{EMAIL} belaran@947: celle ci sera utilisée ensuite. belaran@947: \item Enfin, Mercurial interrogera votre système pour trouver votre belaran@947: nom d'utilisateur local ainsi que le nom de la machine hôte, et il belaran@951: fabriquera un nom d'utilisateur à partir de ces données. Comme il arrive belaran@947: souvent que ce genre de noms soit totalement inutile, il vous belaran@947: préviendra en affichant un message d'avertissement. bos@174: \end{enumerate} belaran@947: huguesfrachon@950: Si tous ces mécanismes échouent, Mercurial n'exécutera pas la commande, belaran@947: affichant un message d'erreur. Dans ce cas, il ne vous laissera pas belaran@947: effectuer de \textit{commit} tant que vous n'aurez pas défini un nom belaran@947: d'utilisateur. belaran@947: belaran@947: Vous devriez penser à utiliser la variable d'environement \envar{HGUSER} belaran@947: et l'option \hgopt{commit}{-u} comme moyen pour \emph{changer le nom huguesfrachon@950: d'utilisateur} par défaut. Pour une utilisation normale, la plus simple belaran@947: et robuste manière d'opérer est de créer un fichier \sfilename{.hgrc}, belaran@947: voir ci dessous pour les détails à ce sujet. bos@102: huguesfrachon@950: \subsubsection{Créer un fichier de configuration pour Mercurial} bos@174: \label{sec:tour-basic:username} bos@102: huguesfrachon@950: Pour définir un nom d'utilisateur, utiliser votre éditeur de texte favori huguesfrachon@950: pour créer un fichier \sfilename{.hgrc} dans votre répertoire \textit{home}. huguesfrachon@950: Mercurial va utiliser ce fichier pour retrouver votre configuration personnelle. huguesfrachon@950: Le contenu initial devrait ressembler à ceci: bos@102: \begin{codesample2} bos@102: # This is a Mercurial configuration file. bos@102: [ui] bos@102: username = Firstname Lastname bos@102: \end{codesample2} huguesfrachon@950: La ligne avec \texttt{[ui]} commence une \emph{section} du fichier de huguesfrachon@950: configuration, ainsi la ligne ``\texttt{username = ...}'' signifie `` huguesfrachon@950: définir la valeur de l'élément \texttt{username} dans la section huguesfrachon@950: \texttt{ui}''. Une section continue jusqu'à ce qu'une nouvelle huguesfrachon@950: commence, ou que la fin du fichier soit atteinte. Mercurial ignore belaran@951: les lignes vide et traite tout texte situé à la suite d'un belaran@951: ``\texttt{\#}'' jusqu'à la fin de la ligne comme un commentaire. belaran@951: belaran@951: \subsubsection{Choisir un nom d'utilisateur} belaran@951: belaran@951: Vous pouvez utiliser n'importe quelle valeur pour votre \texttt{username}, belaran@951: car cette information est destinée à d'autres personnes et non à être belaran@951: interprétée par Mercurial. La convention que la plupart des personnes belaran@951: suivent est d'utiliser leurs noms suivies de leurs adresses emails, belaran@951: comme montrée ci dessus: bos@102: bos@102: \begin{note} belaran@951: Le mécanisme interne du serveur \textit{web} intégré à Mercurial, belaran@951: masque les adresses emails, pour rendre plus difficile leurs belaran@951: récupérations par les outils utilisés par les \textit{spammmers}. belaran@951: Ceci réduit la probabilité que vous receviez encore plus de belaran@951: \textit{spam} si vous vous publiez un dépôt sur internet. bos@102: \end{note} bos@102: belaran@951: \subsection{Rédiger un message de \textit{commit}} belaran@951: belaran@951: Lorsque l'on effectue une opération de \textit{commit}, Mercurial belaran@951: lance automatiquement un éditeur de texte pour permettre de saisir belaran@951: un message qui décrira les modifications effectuées dans ce belaran@951: \textit{changeset}. Ce message est nommée le \emph{message de belaran@951: \textit{commit}}. Ce sera un enregistrement pour tout lecteur belaran@951: expliquant le pourquoi et le comment de vos modifications, et il sera belaran@951: affiché par la commande \hgcmd{log}. bos@91: \interaction{tour.commit} bos@91: belaran@951: L'éditor que la commande \hgcmd{commit} déclenche ne contiendra belaran@951: qu'une ligne vide suivi d'un certain nombre de lignes commençant belaran@951: par ``\texttt{HG:}''. bos@91: \begin{codesample2} bos@91: \emph{empty line} bos@91: HG: changed hello.c bos@91: \end{codesample2} belaran@951: Mercurial ignore les lignes qui commence avec ``\texttt{HG:}'', il belaran@951: ne les utilise que pour nous indiquer quels fichiers modifiés il se belaran@951: prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a belaran@951: aucune conséquence sur l'opération de \textit{commit}. belaran@951: belaran@951: \subsection{Rédiger un message de \textit{approprié}} belaran@951: belaran@951: Comme \hgcmd{log} n'affiche que la première ligne du message de belaran@951: \textit{commit} par défaut, il est souvent considéré comme une bonne belaran@951: pratique de rédiger des messages de \textit{commit} qui rentre que belaran@951: sur une seule ligne. Voilà un exemple concret de message de belaran@951: \textit{commit} qui \emph{ne suit pas} cette directive, et qui a donc belaran@951: un résumé peu lisible. bos@91: \begin{codesample2} bos@91: changeset: 73:584af0e231be bos@91: user: Censored Person bos@91: date: Tue Sep 26 21:37:07 2006 -0700 bos@91: summary: include buildmeister/commondefs. Add an exports and install bos@91: \end{codesample2} bos@91: belaran@951: A ce sujet, il faut noter qu'il n'existe pas de règle absolu dans ce belaran@951: domaine. Mercurial lui-même n'interprète pas les contenus des messages belaran@951: de \textit{commit}, ainsi votre projet est libre de concevoir différentes belaran@951: politiques de formattage des messages. belaran@951: belaran@951: Ma préférence personnelle va au message court, mais informatif, qui offre belaran@951: des précisions supplémentaires à ce que pourrait m'apprendre une commande belaran@951: \hgcmdargs{log}{--patch}. belaran@951: belaran@951: \subsection{Annuler un \textit{commit}} belaran@951: belaran@951: Si, en rédigeant le message, vous décidez que finalement vous ne belaran@951: voulez pas effectuer ce \textit{commit}, il suffit de simplement quitter belaran@951: l'éditeur sans sauver. Ceci n'aura aucune conséquence sur le dépôt ou belaran@951: les fichiers de l'espace de travail. belaran@951: belaran@951: Si vous exécuter la commande \hgcmd{commit} sans aucun arguments, elle belaran@951: enregistre toutes les modifications que vous avez faites, comme le montre belaran@951: la commande \hgcmd{status} et \hgcmd{diff}. belaran@951: belaran@951: \subsection{Admirer votre travail} belaran@951: belaran@951: Une fois que votre \textit{commit} est terminé, vous pouvez utiliser belaran@951: la commande \hgcmd{tip} pour afficher le \textit{changeset} que nous belaran@951: venons de créer. Cette commande produit une sortie à l'écran qui est belaran@951: identique à celle du \hgcmd{log}, maios qui n'affiche que la dernière belaran@951: révision du dépôt. bos@91: \interaction{tour.tip} belaran@951: On fait courament référénce à la dernière révision du dépôt comme belaran@951: étant la révision \textit{tip}, ou plus simplement le \textit{tip}. belaran@951: belaran@951: \section{Partager ses modifications} belaran@951: belaran@951: Nous avons mentionné plus haut que les dépôts de Mercurial belaran@951: sont autosuffisants. Ce qui signifie que le \textit{changeset} belaran@951: que vous venez de créer existe seulement dans votre répertoire belaran@951: \dirname{my-hello}. Etudions comment propager cette modification belaran@951: dans d'autres dépôts. belaran@951: belaran@951: \subsection{Récupérer les modifications d'autres dépôts} bos@91: \label{sec:tour:pull} bos@91: belaran@951: Pour commencer, construisons un clône de notre dépôt \dirname{hello} belaran@951: qui ne contiendra pas le changement que nous venons d'effectuer. Nous belaran@951: l'appelerons notre dépôt temporaire \dirname{hello-pull}. bos@91: \interaction{tour.clone-pull} bos@91: belaran@951: Nous allons utiliser la commande \hgcmd{pull} pour apporter les belaran@951: modifications depuis \dirname{my-hello} dans \dirname{hello-pull}. belaran@951: Néanmoins, récupérer aveuglement des modifications depuis un dépôt belaran@951: a quelquechose d'un peu effrayant. Mercurial propose donc une belaran@951: commande \hgcmd{incoming} qui permet de savoir quelles modifications belaran@951: la commande \hgcmd{pull} \emph{pourrait} entraîner dans notre dépôt, belaran@951: et ceci sans effectuant réellement de modification dessus. bos@91: \interaction{tour.incoming} belaran@951: (Bien évidement, quelqu'un pourrait peut ajouter des modifications belaran@951: supplémentaires sur le dépôt que nous étudions avec \hgcmd{incoming}, belaran@951: avant que nous ayons effectué notre \hgcmd{pull}, avec comme belaran@951: triste conséquence que nous aurons récupéré des modifications que belaran@951: nous n'attendions pas.) belaran@951: belaran@951: Apporter les modifications rapatriées dans un dépôt sera résume donc belaran@951: à exécuter la commande \hgcmd{pull}, et préciser depuis quel dépôt belaran@951: effectuer le \hgcmd{pull}. bos@91: \interaction{tour.pull} belaran@951: belaran@951: Comme vous le voyez avec une sortie avant et après de la commande belaran@951: \hgcmd{tip}, nous avons réussi à récupérer aisément les modifications belaran@951: dans notre dépôt. Il reste néanmoins quelquechose à faire avant de belaran@951: placer ces modifications dans l'espace de travail. belaran@951: belaran@951: \subsection{Mise à jour de l'espace de travail} belaran@951: belaran@951: Nous avons jusqu'à maintenant que grossièrement définie la relation belaran@951: entre un dépôt et un espace de travail. La commande \hgcmd{pull} que belaran@951: nous avons exécuter dans la section~\ref{sec:tour:pull} a apportée belaran@951: des modifications, que nous avons vérifiées, dans notre dépôt, mais belaran@951: il n'ya aucune trace de ces modifications dans notre espace de travail. belaran@951: En effet, \hgcmd{pull} ne touche pas (par défaut) à l'espace de belaran@951: travail. C'est la commande \hgcmd{update} qui s'en charge. bos@91: \interaction{tour.update} bos@91: belaran@951: Il peut sembler un peu étrange que la commande \hgcmd{pull} ne met belaran@951: pas à jour l'espace de travail automatiquement. Il y a en fait une belaran@951: très bonne raison à cela: vous pouvez utilisez la commmande belaran@951: \hgcmd{update} pour mettre à jour votre espace de travail à l'état belaran@951: dans lequel il était à \emph{n'importe quelle révision} de l'historique belaran@951: du dépôt. Si vous aviez un espace de travail contenant une ancienne belaran@951: révision---pour chercher l'origine d'un \textit{bug}, par exemple---et belaran@951: que vous effectuiez un \hgcmd{pull} qui mettrait à jour automatiquement belaran@951: votre espace de travail, vous ne seriez probablement pas très satisfait. belaran@951: belaran@951: Néanmoins, commme les opérations de \textit{pull} sont très souvent belaran@951: suivies d'un \textit{update}, Mercurial vous permet de combiner les belaran@951: deux aisément passant l'option \hgopt{pull}{-u} à la commande belaran@951: \hgcmd{pull} bos@91: \begin{codesample2} bos@91: hg pull -u bos@91: \end{codesample2} belaran@951: belaran@951: Si vous étudiez de nouveau la sortie de la commande \hgcmd{pull} dans belaran@951: la section~\ref{sec:tour:pull} quand nous l'avons exécuter sans l'option belaran@951: \hgopt{pull}{-u}, vous pouvez constater qu'elle a afficher un rappel assez belaran@951: utile que vous devez encore effectuer une opération pour mettre à jour belaran@951: votre espace de travail: bos@92: \begin{codesample2} bos@92: (run 'hg update' to get a working copy) bos@92: \end{codesample2} bos@91: belaran@951: Pour découvrir quelle révision de l'espace de travail en est, utiliser belaran@951: la commande \hgcmd{parents}. bos@91: \interaction{tour.parents} belaran@951: Si vous regardez de nouveau le dessin~\ref{fig:tour-basic:history}, vous belaran@951: verrez que les flèches reliant entreux les \textit{changeset}. Le noeud belaran@951: dont la flèche mène \emph{de quelquepart} est dans chaque cas un parent, belaran@951: et le node dont la flèche mène \emph{à quelquepart} est un enfant. belaran@951: L'espace de travail a un parent de la même manière, c'est ce \textit{changeset} belaran@951: que l'espace de travail contient à ce moment. belaran@951: belaran@951: Pour mettre à jour l'espace de travail d'une révision particulière, belaran@951: indiquer un numéro de révision ou un \textit{changeset~ID} à la commande belaran@951: \hgcmd{update}. bos@91: \interaction{tour.older} belaran@951: Si vous ne précisez pas de manière explicite de numéro de révision belaran@951: belaran@951: la commande \hgcmd{update} mettra à jour votre espace de travail avec belaran@951: le contenu de la révsion \textit{tip}, comme montré dans l'exemple belaran@951: ci dessus lors du second appel à \hgcmd{update}. belaran@951: belaran@951: \subsection{Transférer les modifications à un autre dépôt} belaran@951: belaran@951: Mercurial vous laisse transférer les modifications à un autre belaran@951: dépôt, depuis votre dépôt actuel. Comme dans l'exemple du belaran@951: \hgcmd{pull} ci dessus, nous allons créer un dépôt temporaire belaran@951: vers lequel transférer\footnote{NdT: Les francophones disent souvent belaran@951: ``pousser'' tout simplement} nos modifications. bos@92: \interaction{tour.clone-push} belaran@951: La commande \hgcmd{outgoing} nous indique quels changements nous belaran@951: allons transférer vers l'autre serveyr. bos@92: \interaction{tour.outgoing} belaran@951: Et la commande \hgcmd{push} effectue réellement le transfert. bos@92: \interaction{tour.push} belaran@951: Comme avec \hgcmd{pull}, la commande \hgcmd{push} ne met pas à jour belaran@951: le répertoire de travail du dépôt dans lequel il transfère les belaran@951: modifications. (À l'inverse de \hgcmd{pull}, \hgcmd{push} ne fournit belaran@951: pas d'option \texttt{-u} pour forcer la mise à jour de l'espace belaran@951: de travail cible). belaran@951: belaran@951: Qu'est ce qui se passe lorsque vous essayez de récupérer ou de transférer belaran@951: vos modifications et que le dépôt cible a déjà reçu ces modifications ? belaran@951: Rien de bien excitant. bos@92: \interaction{tour.push.nothing} bos@92: belaran@951: \subsection{Partager ses modifications à travers le réseau} belaran@951: belaran@951: Les commandes que nous avons étudiés dans les sections précédentes belaran@951: ne sont pas limite aux dépôt locaux. Chacune fonction de la même belaran@951: manière à travers une connexion réseau, il suffit de lui passer une belaran@951: URL et non un chemin de fichier local. belaran@951: bos@93: \interaction{tour.outgoing.net} belaran@951: Dans cet exemple, nous allons voir quels changements nous pourrions belaran@951: transférer vers le dépôt distant, mais le dépôt est, de manière tout belaran@951: à fait compréhensible, pas configuré pour accepter des modifications belaran@951: d'utilisateurs anonymes. bos@93: \interaction{tour.push.net} bos@93: bos@84: %%% Local Variables: bos@84: %%% mode: latex bos@84: %%% TeX-master: "00book" bos@84: %%% End: