1.1 --- a/it/00book.xml	Fri Jul 17 18:53:35 2009 +0200
     1.2 +++ b/it/00book.xml	Sat Jul 18 23:28:00 2009 +0200
     1.3 @@ -15,8 +15,8 @@
     1.4  <!ENTITY ch06     SYSTEM "ch06-collab.xml">
     1.5  <!ENTITY ch07     SYSTEM "ch07-filenames.xml">
     1.6  <!ENTITY ch08     SYSTEM "ch08-branch.xml">
     1.7 +<!ENTITY ch09     SYSTEM "ch09-undo.xml">
     1.8  <!--
     1.9 -<!ENTITY ch09     SYSTEM "ch09-undo.xml">
    1.10  <!ENTITY ch10     SYSTEM "ch10-hook.xml">
    1.11  <!ENTITY ch11     SYSTEM "ch11-template.xml">
    1.12  <!ENTITY ch12     SYSTEM "ch12-mq.xml">
    1.13 @@ -103,8 +103,8 @@
    1.14    &ch07;
    1.15    <!-- BEGIN ch08 -->
    1.16    &ch08;
    1.17 -  <!-- BEGIN ch09
    1.18 -  &ch09; -->
    1.19 +  <!-- BEGIN ch09 -->
    1.20 +  &ch09;
    1.21    <!-- BEGIN ch10
    1.22    &ch10; -->
    1.23    <!-- BEGIN ch11

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/it/ch09-undo.xml	Sat Jul 18 23:28:00 2009 +0200
     2.3 @@ -0,0 +1,566 @@
     2.4 +<chapter id="chap:undo">
     2.5 +  <?dbhtml filename="trovare-e-correggere-gli-errori.html"?>
     2.6 +  <title>Trovare e correggere gli errori</title>
     2.7 +
     2.8 +  <para id="x_d2">Sbagliare potrebbe essere umano, ma per gestire davvero bene le conseguenze degli errori ci vuole un sistema di controllo di revisione di prima qualità. In questo capitolo, discuteremo alcune tecniche che potete usare quando scoprite che un problema si è insinuato nel vostro progetto. Mercurial è dotato di alcune funzionalità ~highly capable~ che vi aiuteranno a isolare le cause dei problemi e a trattarle in maniera appropriata.</para>
     2.9 +
    2.10 +  <sect1>
    2.11 +    <title>Cancellare la cronologia locale</title>
    2.12 +
    2.13 +    <sect2>
    2.14 +      <title>L'inserimento accidentale</title>
    2.15 +
    2.16 +      <para id="x_d3">Ho l'occasionale ma persistente problema di digitare più velocemente di quanto riesca a pensare, cosa che talvolta ha come risultato io che inserisco un changeset che è incompleto o completamente sbagliato. Nel mio caso, il classico tipo di changeset incompleto è quello in cui ho creato un nuovo file sorgente ma ho dimenticato di usare <command role="hg-cmd">hg add</command> per aggiungerlo al repository. Un changeset <quote>completamente sbagliato</quote> non è così comune, ma non è meno fastidioso.</para>
    2.17 +
    2.18 +    </sect2>
    2.19 +    <sect2 id="sec:undo:rollback">
    2.20 +      <title>~Rolling back~ una transazione</title>
    2.21 +
    2.22 +      <para id="x_d4">Nella <xref linkend="sec:concepts:txn"/>, ho menzionato che Mercurial tratta ogni modifica del repository come una <emphasis>transazione</emphasis>. Ogni volta che inserite un changeset o estraete i cambiamenti da un altro repository, Mercurial ricorda cosa avete fatto. Potete annullare, o <emphasis>~roll back~</emphasis>, esattamente una di queste azioni usando il comando <command role="hg-cmd">hg rollback</command>. (Leggete la <xref linkend="sec:undo:rollback-after-push"/> per un importante avvertimento su come usare questo comando.)</para>
    2.23 +
    2.24 +      <para id="x_d5">Ecco un errore che mi ritrovo spesso a commettere: inserire un cambiamento in cui ho creato un nuovo file ma ho dimenticato di aggiungerlo tramite <command role="hg-cmd">hg add</command>.</para>
    2.25 +
    2.26 +      &interaction.rollback.commit;
    2.27 +
    2.28 +      <para id="x_d6">Controllare il risultato di <command role="hg-cmd">hg status</command> dopo l'inserimento conferma immediatamente l'errore.</para>
    2.29 +
    2.30 +      &interaction.rollback.status;
    2.31 +
    2.32 +      <para id="x_d7">Il commit ha catturato le modifiche al file <filename>a</filename>, ma non il nuovo file <filename>b</filename>. Se trasmettessi questo changeset a un repository che condivido con i miei colleghi, è molto probabile che qualcosa in <filename>a</filename> si riferisca a <filename>b</filename>, che non sarà presente nei loro repository quando estrarranno i miei cambiamenti. Di conseguenza, diventerei oggetto di una certa indignazione.</para>
    2.33 +
    2.34 +      <para id="x_d8">Tuttavia, la fortuna è dalla mia parte&emdash;mi sono accorto dell'errore prima di trasmettere il changeset. Ora uso il comando <command role="hg-cmd">hg rollback</command> e Mercurial farà sparire quell'ultimo changeset.</para>
    2.35 +
    2.36 +      &interaction.rollback.rollback;
    2.37 +
    2.38 +      <para id="x_d9">Notate che il changeset non è più presente nella cronologia del repository e che la directory di lavoro pensa ancora che il file <filename>a</filename> sia stato modificato. Il commit e il ~rollback~ hanno lasciato la directory di lavoro nello stato esatto in cui si trovava prima dell'inserimento; il changeset è stato completamente rimosso. Ora posso tranquillamente usare <command role="hg-cmd">hg add</command> per aggiungere il file <filename>b</filename> e rieseguire il commit.</para>
    2.39 +
    2.40 +      &interaction.rollback.add;
    2.41 +
    2.42 +    </sect2>
    2.43 +    <sect2>
    2.44 +      <title>L'estrazione sbagliata</title>
    2.45 +
    2.46 +      <para id="x_da">&Egrave; pratica comune con Mercurial mantenere i rami di sviluppo separati di un progetto in repository differenti. Il vostro gruppo di sviluppo potrebbe avere un repository condiviso per la release <quote>0.9</quote> del vostro progetto e un altro, contenente cambiamenti differenti, per la release <quote>1.0</quote>.</para>
    2.47 +
    2.48 +      <para id="x_db">In questa situazione, potete immaginare che pasticcio accadrebbe se aveste un repository <quote>0.9</quote> locale e vi propagaste accidentalmente i cambiamenti dal repository <quote>1.0</quote> condiviso. Nel caso peggiore, potreste non fare abbastanza attenzione e trasmettere quei cambiamenti nell'albero <quote>0.9</quote> condiviso, confondendo tutti gli altri sviluppatori (ma non preoccupatevi, ritorneremo a questo orribile scenario più avanti). Tuttavia, è più probabile che notiate immediatamente l'errore, perché Mercurial vi mostrerà l'URL da cui sta estraendo i cambiamenti, o perché vedrete Mercurial propagare un numero sospettosamente alto di cambiamenti nel repository.</para>
    2.49 +
    2.50 +      <para id="x_dc">Il comando <command role="hg-cmd">hg rollback</command> lavorerà scrupolosamente per cancellare tutti i changeset che avete appena estratto. Mercurial raggruppa tutti i cambiamenti provenienti da una invocazione di <command role="hg-cmd">hg pull</command> in una singola transazione, quindi un'unica invocazione di <command role="hg-cmd">hg rollback</command> è tutto quello che vi serve per annullare questo errore.</para>
    2.51 +
    2.52 +    </sect2>
    2.53 +    <sect2 id="sec:undo:rollback-after-push">
    2.54 +      <title>~Rolling back~ è inutile se avete già trasmesso le modifiche</title>
    2.55 +
    2.56 +      <para id="x_dd">Il valore di <command role="hg-cmd">hg rollback</command> scende a zero una volta che avete trasmesso le vostre modifiche a un altro repository. ~Rolling back~ un cambiamento lo fa scomparire interamente, ma <emphasis>solo</emphasis> nel repository in cui invocate <command role="hg-cmd">hg rollback</command>. Dato che un ~rollback~ elimina parte della cronologia, non è possibile che la scomparsa di un cambiamento si propaghi tra i repository.</para>
    2.57 +
    2.58 +      <para id="x_de">Se avete trasmesso un cambiamento a un altro repository&emdash;in particolare se è un repository condiviso&emdash;è essenzialmente <quote>scappato dal recinto</quote> e dovrete rimediare all'errore in un altro modo. Se trasmettete un changeset da qualche parte, poi ~roll it back~ e poi estraete i cambiamenti dal repository verso cui avete effettuato la trasmissione, il changeset di cui credevate di esservi sbarazzati riapparirà semplicemente nel vostro repository.</para>
    2.59 +
    2.60 +      <para id="x_df">(Se siete assolutamente sicuri che il cambiamento che volete ritirare è quello più recente contenuto nel repository a cui lo avete trasmesso <emphasis>e</emphasis> sapete che nessun altro può averlo estratto da quel repository, potete ritirare il changeset anche là, ma non dovreste aspettarvi che questo funzioni in maniera affidabile. Presto o tardi un cambiamento finirà in un repository su cui non avete un controllo diretto (o vi siete dimenticati di averlo) e tornerà indietro a mordervi.)</para>
    2.61 +
    2.62 +    </sect2>
    2.63 +    <sect2>
    2.64 +      <title>Potete ritirare una sola volta</title>
    2.65 +
    2.66 +      <para id="x_e0">Mercurial memorizza esattamente una transazione nel suo registro delle transazioni: quella più recente avvenuta nel repository. Questo significa che potete ritirare solo una transazione. Se vi aspettate di poter ritirare una transazione e poi il suo predecessore, questo non il comportamento che otterrete.</para>
    2.67 +
    2.68 +      &interaction.rollback.twice;
    2.69 +
    2.70 +      <para id="x_e1">Una volta che avete ritirato una transazione in un repository, non potete effettuare un altro ritiro in quel repository fino a quando non avete eseguito un altro inserimento o una nuova estrazione.</para>
    2.71 +
    2.72 +    </sect2>
    2.73 +  </sect1>
    2.74 +  <sect1>
    2.75 +    <title>Rimediare alle modifiche sbagliate</title>
    2.76 +
    2.77 +    <para id="x_e2">Se fate un cambiamento a un file e decidete che in realtà non volevate affatto modificare il file, e non avete ancora inserito i vostri cambiamenti nel repository, il comando che vi serve è <command role="hg-cmd">hg revert</command>. Guarda al changeset che è il genitore della directory di lavoro e ripristina il contenuto di quel file allo stato in cui era in quel changeset. (Questo è un modo verboso di dire che, nel caso normale, annulla le vostre modifiche.)</para>
    2.78 +
    2.79 +    <para id="x_e3">Vediamo come funziona il comando <command role="hg-cmd">hg revert</command> attraverso ancora un altro piccolo esempio. Cominceremo modificando un file che Mercurial ha già registrato.</para>
    2.80 +
    2.81 +    &interaction.daily.revert.modify;
    2.82 +
    2.83 +    <para id="x_e4">Se non vogliamo quella modifica, possiamo semplicemente usare <command role="hg-cmd">hg revert</command> sul file.</para>
    2.84 +
    2.85 +      &interaction.daily.revert.unmodify;
    2.86 +
    2.87 +    <para id="x_e5">Il comando <command role="hg-cmd">hg revert</command> ci fornisce un ulteriore grado di sicurezza salvando il nostro file modificato con una estensione <filename>.orig</filename>.</para>
    2.88 +
    2.89 +    &interaction.daily.revert.status;
    2.90 +
    2.91 +    <tip>
    2.92 +      <title>Fate attenzione ai file <filename>.orig</filename></title>
    2.93 +
    2.94 +      <para id="x_6b8">&Egrave; estremamente improbabile che stiate usando Mercurial per gestire file con estensione <filename>.orig</filename> o persino che siate interessati al contenuto di quei file. Nel caso, comunque, è utile ricordare che <command role="hg-cmd">hg revert</command> sovrascriverà incondizionatamente un file con estensione <filename>.orig</filename> esistente. Per esempio, se avete già un file <filename>foo.orig</filename> quando ritornate alla versione precedente del file <filename>foo</filename>, il contenuto di <filename>foo.orig</filename> verrà ~clobbered~.</para>
    2.95 +    </tip>
    2.96 +
    2.97 +    <para id="x_e6">Ecco un riepilogo dei casi che il comando <command role="hg-cmd">hg revert</command> è in grado di gestire. Li descriveremo in dettaglio nella prossima sezione.</para>
    2.98 +    <itemizedlist>
    2.99 +      <listitem><para id="x_e7">Se modificate un file, lo ripristinerà a suo stato non modificato.</para>
   2.100 +      </listitem>
   2.101 +      <listitem><para id="x_e8">Se usate <command role="hg-cmd">hg add</command> su un file, annullerà lo stato di <quote>aggiunto</quote> del file ma lascerà intatti i contenuti del file.</para>
   2.102 +      </listitem>
   2.103 +      <listitem><para id="x_e9">Se cancellate un file senza dirlo a Mercurial, ripristinerà il file con i suoi contenuti intatti.</para>
   2.104 +      </listitem>
   2.105 +      <listitem><para id="x_ea">Se usate il comando <command role="hg-cmd">hg remove</command> per cancellare un file, annullerà lo stato di <quote>rimosso</quote> del file e ne riprisinterà i contenuti intatti.</para>
   2.106 +      </listitem></itemizedlist>
   2.107 +
   2.108 +    <sect2 id="sec:undo:mgmt">
   2.109 +      <title>Errori nella gestione dei file</title>
   2.110 +
   2.111 +      <para id="x_eb">Il comando <command role="hg-cmd">hg revert</command> è utile non solo per i file modificati. Vi permette di invertire i risultati di tutti i comandi Mercurial di gestione dei file&emdash;<command role="hg-cmd">hg add</command>, <command role="hg-cmd">hg remove</command>, e così via.</para>
   2.112 +
   2.113 +      <para id="x_ec">Se usate <command role="hg-cmd">hg add</command> su un file, poi decidete che in effetti non volete che Mercurial ne tenga traccia, usate <command role="hg-cmd">hg revert</command> per annullare l'operazione di aggiunta. Non preoccupatevi, Mercurial non modificherà il file in alcun modo, ma si limiterà a eliminare il <quote>contrassegno</quote> per quel file.</para>
   2.114 +
   2.115 +      &interaction.daily.revert.add;
   2.116 +
   2.117 +      <para id="x_ed">Similmente, se chiedete a Mercurial di rimuovere un file tramite <command role="hg-cmd">hg remove</command>, potete usare <command role="hg-cmd">hg revert</command> per ripristinarne i contenuti allo stato in cui erano nel genitore della directory di lavoro.</para>
   2.118 +      
   2.119 +      &interaction.daily.revert.remove;
   2.120 +      
   2.121 +      <para id="x_ef">Questo funziona altrettanto bene per un file che avete cancellato a mano senza dirlo a Mercurial (ricordatevi che, nella terminologia di Mercurial, questo file viene detto <quote>mancante</quote>).</para>
   2.122 +
   2.123 +      &interaction.daily.revert.missing;
   2.124 +
   2.125 +      <para id="x_ee">Se invertite l'azione del comando <command role="hg-cmd">hg copy</command>, il file copiato rimane nella vostra directory di lavoro senza che Mercurial ne tenga traccia. Dato che l'operazione di copia non ha effetti sul file originale, Mercurial non agisce in alcun modo su quel file.</para>
   2.126 +
   2.127 +      &interaction.daily.revert.copy;
   2.128 +    </sect2>
   2.129 +  </sect1>
   2.130 +
   2.131 +  <sect1>
   2.132 +    <title>Gestire i cambiamenti inseriti</title>
   2.133 +
   2.134 +    <para id="x_f5">Considerate il caso in cui avete inserito un cambiamento <emphasis>a</emphasis> e subito dopo un altro cambiamento <emphasis>b</emphasis> basato sul precedente, poi realizzate che il cambiamento <emphasis>a</emphasis> era sbagliato. Mercurial vi consente di <quote>ritirare</quote> un intero changeset automaticamente e di costruire blocchi che vi permettono di invertire a mano parte di un changeset.</para>
   2.135 +
   2.136 +    <para id="x_f6">Prima di leggere questa sezione, c'è una cosa che dovete tenere a mente: il comando <command role="hg-cmd">hg backout</command> annulla gli effetti di un cambiamento effettuando una <emphasis>aggiunta</emphasis> alla cronologia del vostro repository, non modificandola o eliminandone una parte. &Egrave; lo strumento giusto da usare se state correggendo un bug, ma non se state cercando di annullare qualche cambiamento che ha conseguenze catastrofiche. Per trattare con questi, leggete la <xref linkend="sec:undo:aaaiiieee"/>.</para>
   2.137 +
   2.138 +    <sect2>
   2.139 +      <title>Ritirare un changeset</title>
   2.140 +
   2.141 +      <para id="x_f7">Il comando <command role="hg-cmd">hg backout</command> vi consente di <quote>annullare</quote> gli effetti di un intero changeset in modo automatico. Dato che la cronologia di Mercurial è immutabile, questo comando <emphasis>non</emphasis> si sbarazza del changeset che volete annullare, ma crea un nuovo changeset che <emphasis>inverte</emphasis> l'effetto del changeset da annullare.</para>
   2.142 +
   2.143 +      <para id="x_f8">Le operazioni del comando <command role="hg-cmd">hg backout</command> sono un po' intricate, quindi le illustreremo con alcuni esempi. Per prima cosa, creiamo un repository con alcuni semplici cambiamenti.</para>
   2.144 +
   2.145 +      &interaction.backout.init;
   2.146 +
   2.147 +      <para id="x_f9">Il comando <command role="hg-cmd">hg backout</command> prende un singolo identificatore di changeset come argomento; questo è il changeset da annullare. Normalmente, <command role="hg-cmd">hg backout</command> vi presenterà un editor di testo per farvi scrivere un messaggio di commit, in modo che possiate registrare il motivo per cui state ritirando il cambiamento. In questo esempio, forniremo un messaggio di commit sulla riga di comando usando l'opzione <option role="hg-opt-backout">-m</option> option.</para>
   2.148 +
   2.149 +    </sect2>
   2.150 +    <sect2>
   2.151 +      <title>Ritirare il changeset di punta </title>
   2.152 +
   2.153 +      <para id="x_fa">Cominceremo ritirando l'ultimo changeset che abbiamo inserito.</para>
   2.154 +
   2.155 +      &interaction.backout.simple;
   2.156 +
   2.157 +      <para id="x_fb">Potete vedere che la seconda riga di <filename>myfile</filename> non è più presente. Un'occhiata all'elenco generato da <command role="hg-cmd">hg log</command> ci dà un'idea di quello che il comando <command role="hg-cmd">hg backout</command> ha fatto.</para>
   2.158 +      
   2.159 +      &interaction.backout.simple.log;
   2.160 +      
   2.161 +      <para id="x_fc">Notate che il nuovo changeset creato da <command role="hg-cmd">hg backout</command> è un figlio del changeset che abbiamo ritirato. Questo è più facile da vedere nella <xref linkend="fig:undo:backout"/>, che mostra una rappresentazione grafica della cronologia dei cambiamenti. Come potete vedere, la cronologia è gradevolmente lineare.</para>
   2.162 +
   2.163 +      <figure id="fig:undo:backout">
   2.164 +	<title>Ritirare un cambiamento tramite il comando <command role="hg-cmd">hg backout</command></title>
   2.165 +	<mediaobject>
   2.166 +	  <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject>
   2.167 +	  <textobject><phrase>XXX add text</phrase></textobject>
   2.168 +	</mediaobject>
   2.169 +      </figure>
   2.170 +
   2.171 +    </sect2>
   2.172 +    <sect2>
   2.173 +      <title>Ritirare un changeset diverso dalla punta</title>
   2.174 +
   2.175 +      <para id="x_fd">Se volete ritirare un cambiamento diverso dall'ultimo che avete inserito, passate l'opzione <option role="hg-opt-backout">--merge</option> al comando <command role="hg-cmd">hg backout</command>.</para>
   2.176 +
   2.177 +      &interaction.backout.non-tip.clone;
   2.178 +
   2.179 +      <para id="x_fe">Questo rende il ritiro di qualsiasi changeset una <quote>singola</quote> operazione che di solito è semplice e veloce.</para>
   2.180 +
   2.181 +      &interaction.backout.non-tip.backout;
   2.182 +
   2.183 +      <para id="x_ff">Se date un'occhiata al contenuto di <filename>myfile</filename> dopo che l'operazione di ritiro si è conclusa, vedrete che il primo e il terzo cambiamento sono presenti, ma non il secondo.</para>
   2.184 +
   2.185 +      &interaction.backout.non-tip.cat;
   2.186 +
   2.187 +      <para id="x_100">Come illustrato nella rappresentazione grafica della cronologia nella <xref linkend="fig:undo:backout-non-tip"/>, Mercurial inserisce ancora un cambiamento in questo tipo di situazione (il nodo rettangolare è quello che Mercurial inserisce automaticamente) ma il grafo delle revisioni ora è diverso. Prima che Mercurial cominci il processo di ritiro, mantiene in memoria l'identità del genitore corrente della directory di lavoro. Poi ritira il changeset indicato e inserisce quello come un changeset. Infine, incorpora il genitore precedente della directory di lavoro, ma notate che <emphasis>non esegue il commit</emphasis> dei risultati dell'unione. Il repository ora contiene due teste, e la directory di lavoro è in uno ~stato di merge~.</para>
   2.188 +
   2.189 +      <figure id="fig:undo:backout-non-tip">
   2.190 +	<title>Ritiro automatico di un changeset diverso dalla punta tramite il comando <command role="hg-cmd">hg backout</command></title>
   2.191 +	<mediaobject>
   2.192 +	  <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject>
   2.193 +	  <textobject><phrase>XXX add text</phrase></textobject>
   2.194 +	</mediaobject>
   2.195 +      </figure>
   2.196 +
   2.197 +      <para id="x_103">Il risultato è che siete tornati <quote>indietro a dove eravate</quote>, solo con una parte aggiuntiva di cronologia che annulla gli effetti del changeset che volevate ritirare.</para>
   2.198 +
   2.199 +      <para id="x_6b9">Potreste chiedervi perché Mercurial non effettua il commit dei risultati dell'unione che ha eseguito. Il motivo è che Mercurial si comporta in maniera conservativa: di solito un'unione ha maggiori probabilità di contenere errori rispetto all'annullamento degli effetti del changeset di punta, quindi il vostro lavoro si troverà più al sicuro se prima ispezionate (e verificherete!) i risultati dell'unione e solo <emphasis>poi</emphasis> li inserite nel repository.</para>
   2.200 +
   2.201 +      <sect3>
   2.202 +	<title>Usate sempre l'opzione <option role="hg-opt-backout">--merge</option></title>
   2.203 +
   2.204 +	<para id="x_104">In effetti, dato che l'opzione <option role="hg-opt-backout">--merge</option> farà la <quote>cosa giusta</quote> a prescindere dal fatto che il changeset sia quello di punta o meno (i.e. non cercherà di eseguire un'unione se state ritirando la punta, dato che non ce n'è bisogno), dovreste usare <emphasis>sempre</emphasis> questa opzione quando eseguite il comando <command role="hg-cmd">hg backout</command>.</para>
   2.205 +
   2.206 +      </sect3>
   2.207 +    </sect2>
   2.208 +    <sect2>
   2.209 +      <title>Controllare meglio il processo di ritiro</title>
   2.210 +
   2.211 +      <para id="x_105">Sebbene vi abbia raccomandato di usare sempre l'opzione <option role="hg-opt-backout">--merge</option> quando ritirate un cambiamento, il comando <command role="hg-cmd">hg backout</command> vi permette di decidere come incorporare un changeset ritirato. Avrete raramente bisogno di controllare il processo di ritiro a mano, ma potrebbe essere utile capire quello che il comando <command role="hg-cmd">hg backout</command> fa per voi automaticamente. Per illustrare questo, cloniamo il nostro primo repository, ma omettiamo il cambiamento ritirato che contiene.</para>
   2.212 +
   2.213 +      &interaction.backout.manual.clone;
   2.214 +
   2.215 +      <para id="x_106">Come nel nostro esempio precedente, inseriremo un terzo changeset, poi ritireremo il suo genitore e vedremo cosa succede.</para>
   2.216 +
   2.217 +      &interaction.backout.manual.backout;
   2.218 +
   2.219 +      <para id="x_107">Il nostro nuovo changeset è ancora un discendente del changeset che abbiamo ritirato e quindi è una nuova testa, <emphasis>non</emphasis> un discendente di quello che era il changeset di punta. Il comando <command role="hg-cmd">hg backout</command> è stato piuttosto esplicito nel farcelo notare.</para>
   2.220 +
   2.221 +      &interaction.backout.manual.log;
   2.222 +
   2.223 +      <para id="x_108">Ancora, è facile vedere quello che è successo guardando al grafo della cronologia delle revisioni, nella <xref linkend="fig:undo:backout-manual"/>. Questo chiarifica che quando usiamo <command role="hg-cmd">hg backout</command> per ritirare un cambiamento diverso dalla punta, Mercurial aggiunge una nuova testa al repository (il cambiamento che ha inserito ha la forma di un rettangolo).</para>
   2.224 +
   2.225 +      <figure id="fig:undo:backout-manual">
   2.226 +	<title>Ritirare un cambiamento tramite il comando <command role="hg-cmd">hg backout</command></title>
   2.227 +	<mediaobject>
   2.228 +	  <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject>
   2.229 +	  <textobject><phrase>XXX add text</phrase></textobject>
   2.230 +	</mediaobject>
   2.231 +      </figure>
   2.232 +
   2.233 +      <para id="x_10a">Dopo che il comando <command role="hg-cmd">hg backout</command> ha terminato, lascia il nuovo changeset <quote>ritirato</quote> come il genitore della directory di lavoro.</para>
   2.234 +
   2.235 +      &interaction.backout.manual.parents;
   2.236 +
   2.237 +      <para id="x_10b">Ora abbiamo due insiemi isolati di cambiamenti.</para>
   2.238 +
   2.239 +      &interaction.backout.manual.heads;
   2.240 +
   2.241 +      <para id="x_10c">Pensiamo a quello che ora ci aspettiamo di vedere come contenuto di <filename>myfile</filename>. Il primo cambiamento dovrebbe essere presente, perché non lo abbiamo mai ritirato. Il secondo cambiamento non dovrebbe esserci, dato che quello è il cambiamento che abbiamo ritirato. Visto che il grafo della cronologia mostra il terzo cambiamento come una testa separata, <emphasis>non</emphasis> ci aspettiamo di vedere il terzo cambiamento nel contenuto di <filename>myfile</filename>.</para>
   2.242 +
   2.243 +      &interaction.backout.manual.cat;
   2.244 +
   2.245 +      <para id="x_10d">Per riottenere il terzo cambiamento nel file, eseguiamo semplicemente una normale unione tra le nostre due teste.</para>
   2.246 +
   2.247 +      &interaction.backout.manual.merge;
   2.248 +
   2.249 +      <para id="x_10e">Successivamente, la cronologia del nostro repository può essere rappresentata graficamente come nella <xref linkend="fig:undo:backout-manual-merge"/>.</para>
   2.250 +
   2.251 +      <figure id="fig:undo:backout-manual-merge">
   2.252 +	<title>Incorporare manualmente un cambiamento ritirato</title>
   2.253 +	<mediaobject>
   2.254 +	  <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject>
   2.255 +	  <textobject><phrase>XXX add text</phrase></textobject>
   2.256 +	</mediaobject>
   2.257 +      </figure>
   2.258 +
   2.259 +    </sect2>
   2.260 +    <sect2>
   2.261 +      <title>Perché <command role="hg-cmd">hg backout</command> funziona in questo modo</title>
   2.262 +
   2.263 +      <para id="x_110">Ecco una breve descrizione del funzionamento del comando <command role="hg-cmd">hg backout</command>.</para>
   2.264 +      <orderedlist>
   2.265 +	<listitem><para id="x_111">Si assicura che la directory di lavoro sia <quote>pulita</quote>, i.e. che l'elenco generato da <command role="hg-cmd">hg status</command> sia vuoto.</para>
   2.266 +	</listitem>
   2.267 +	<listitem><para id="x_112">Memorizza il genitore corrente della directory di lavoro. Chiamiamo <literal>orig</literal> questo changeset.</para>
   2.268 +	</listitem>
   2.269 +	<listitem><para id="x_113">Esegue l'equivalente di una invocazione di <command role="hg-cmd">hg update</command> per sincronizzare la directory di lavoro con il changeset che volete ritirare. Chiamiamo <literal>backout</literal> questo changeset.</para>
   2.270 +	</listitem>
   2.271 +	<listitem><para id="x_114">Trova il genitore di quel changeset. Chiamiamo <literal>parent</literal> questo changeset.</para>
   2.272 +	</listitem>
   2.273 +	<listitem><para id="x_115">Per ogni file su cui il changeset <literal>backout</literal> ha avuto effetto, esegue l'equivalente del comando <command role="hg-cmd">hg revert -r parent</command> su quel file per ripristinare il contenuto che aveva prima che quel changeset venisse inserito.</para>
   2.274 +	</listitem>
   2.275 +	<listitem><para id="x_116">Esegue il commit del risultato come un nuovo changeset che ha <literal>backout</literal> come genitore.</para>
   2.276 +	</listitem>
   2.277 +	<listitem><para id="x_117">Se specificate l'opzione <option role="hg-opt-backout">--merge</option> sulla riga di comando, esegue un'unione con <literal>orig</literal> e inserisce i risultati dell'unione nel repository.</para>
   2.278 +	</listitem></orderedlist>
   2.279 +
   2.280 +      <para id="x_118">In alternativa, sarebbe possibile implementare <command role="hg-cmd">hg backout</command> utilizzando <command role="hg-cmd">hg export</command> per esportare il changeset da ritirare sotto forma di diff e poi impiegando l'opzione <option role="cmd-opt-patch">--reverse</option> del comando <command>patch</command> per invertire l'effetto del cambiamento senza gingillarsi con la directory di lavoro. Questo sembra molto più semplice, ma non funzionerebbe affatto altrettanto bene.</para>
   2.281 +
   2.282 +      <para id="x_119">Il comando <command role="hg-cmd">hg backout</command> esegue un aggiornamento, un inserimento, un'unione e un altro inserimento per dare al meccanismo di unione la possibilità di fare il miglior lavoro possibile nel gestire tutte le modifiche avvenute <emphasis>tra</emphasis> il cambiamento che state ritirando e la revisione di punta corrente.</para>
   2.283 +
   2.284 +      <para id="x_11a">Se state ritirando un cambiamento che si trova 100 revisioni indietro nella cronologia del vostro progetto, le probabilità che il comando <command>patch</command> sia in grado di applicare un diff invertito in maniera pulita non sono molto alte, perché i cambiamenti intercorsi avranno probabilmente <quote>rotto il contesto</quote> utilizzato da <command>patch</command> per determinare se può applicare una patch (se questo vi sembra incomprensibile, leggete <!--<xref linkend="sec:mq:patch"/>-->FIXME per una discussione sul comando <command>patch</command>). In più, il meccanismo di unione di Mercurial riesce gestire i cambiamenti di nome e permessi per file e directory e le modifiche ai file binari, mentre <command>patch</command> non è in grado di farlo.</para>
   2.285 +
   2.286 +    </sect2>
   2.287 +  </sect1>
   2.288 +  <sect1 id="sec:undo:aaaiiieee">
   2.289 +    <title>Modifiche che non avrebbero mai dovuto essere fatte</title>
   2.290 +
   2.291 +    <para id="x_11b">Quasi sempre, il comando <command role="hg-cmd">hg backout</command> è esattamente quello che vi serve se volete annullare gli effetti di un cambiamento. Lascia una registrazione permanente di quello che avete fatto, sia quando avete inserito il changeset originale che quando avete successivamente rimesso in ordine.</para>
   2.292 +
   2.293 +    <para id="x_11c">In rare occasioni, comunque, potreste scoprire di aver inserito un cambiamento che non dovrebbe essere presente nel repository proprio per niente. Per esempio, sarebbe molto inusuale, e di solito considerato un errore, inserire in un repository i file oggetto di un progetto software insieme ai suoi file sorgente. I file oggetto non hanno praticamente alcun valore intrinserco e sono <emphasis>grandi</emphasis>, quindi aumentano la dimensione del repository e il tempo necessario a clonarlo o a estrarne i cambiamenti.</para>
   2.294 +
   2.295 +    <para id="x_11d">Prima di illustrare le opzioni che avete se eseguite il commit di un cambiamento <quote>da sacchetto di carta marrone</quote> (quel tipo di modifiche così cattive che vorreste nascondere la testa in un sacchetto di carta marrone), lasciatemi discutere alcuni approcci che probabilmente non funzioneranno.</para>
   2.296 +
   2.297 +    <para id="x_11e">Dato che Mercurial tratta la cronologia in maniera cumulativa&emdash;ogni cambiamento si basa su tutti i cambiamenti che lo precedono&emdash;in genere non potete far semplicemente sparire i cambiamenti disastrosi. L'unica eccezione è quando avete appena inserito una modifica e non è stata ancora propagata verso qualche altro repository. In questo caso, potete tranquillamente usare il comando <command role="hg-cmd">hg rollback</command>, come descritto nella <xref linkend="sec:undo:rollback"/>.</para>
   2.298 +
   2.299 +    <para id="x_11f">Dopo che avete trasmesso un cambiamento sbagliato a un altro repository, <emphasis>potreste</emphasis> anocra usare <command role="hg-cmd">hg rollback</command> per far scomparire la vostra copia locale del cambiamento, ma questa azione non avrà le conseguenze che volete. Il cambiamento sarà ancora presente nel repository remoto, quindi riapparirà nel vostro repository locale la prossima volta che ne estrarrete i cambiamenti.</para>
   2.300 +
   2.301 +    <para id="x_120">Se vi trovate in una situazione come questa e sapete verso quali repository si è propagato il vostro cambiamento sbagliato, potete <emphasis>provare</emphasis> a sbarazzarvi del cambiamento in <emphasis>ognuno</emphasis> di quei repository. Questa, naturalmente, non è una soluzione soddisfacente: se mancate anche un singolo repository quando state ripulendo, il cambiamento sarà ancora <quote>là fuori</quote> e potrebbe propagarsi ulteriormente.</para>
   2.302 +
   2.303 +    <para id="x_121">Se avete inserito uno o più cambiamenti <emphasis>dopo</emphasis> il cambiamento che vorreste veder sparire, le vostre opzioni si riducono ulteriormente. Mercurial non offre alcun modo per <quote>fare un buco</quote> nella cronologia lasciando gli altri changeset intatti.</para>
   2.304 +
   2.305 +    <sect2>
   2.306 +      <title>Ritirare un'unione</title>
   2.307 +
   2.308 +      <para id="x_6ba">Dato che le unioni sono spesso complicate, si sono sentiti casi di unioni gravemente rovinate, ma i cui risultati sono stati erroneamente inseriti in un repository. Mercurial fornisce un'importante protezione contro le unioni sbagliate rifiutandosi di eseguire il commit di file non risolti, ma l'ingenuità umana garantisce che è ancora possibile mettere sottosopra un'unione e inserirla.</para>
   2.309 +
   2.310 +      <para id="x_6bb">Data un'unione sbagliata che è stata inserita, di solito il miglior modo di affrontarla è semplicemente provare a riparare il danno a mano. Un completo disastro che non può essere corretto a mano dovrebbe essere molto raro, ma il comando <command role="hg-cmd">hg backout</command> può aiutare a rendere la pulizia più semplice. Offre un'opzione <option role="hg-opt-backout">--parent</option>, che vi consente di specificare a quale genitore tornare quando state ritirando un'unione.</para>
   2.311 +
   2.312 +      <figure id="fig:undo:bad-merge-1">
   2.313 +	<title>Un'unione sbagliata</title>
   2.314 +	<mediaobject>
   2.315 +	  <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject>
   2.316 +	  <textobject><phrase>XXX add text</phrase></textobject>
   2.317 +	</mediaobject>
   2.318 +      </figure>
   2.319 +
   2.320 +      <para id="x_6bc">Supponete di avere un grafo delle revisioni simile a quello della <xref linkend="fig:undo:bad-merge-1"/>. Quello che vorremmo fare è <emphasis>rifare</emphasis> l'unione tra le revisioni 2 e 3.</para>
   2.321 +
   2.322 +      <para id="x_6bd">Potremmo eseguire questa operazione nel modo seguente.</para>
   2.323 +
   2.324 +      <orderedlist>
   2.325 +	<listitem>
   2.326 +	  <para id="x_6be">Invocare <command role="hg-cmd">hg backout --rev=4 --parent=2</command>. Questo dice al comando <command role="hg-cmd">hg backout</command> di ritirare la revisione 4, che è l'unione sbagliata, e di scegliere il genitore 2, uno dei genitori dell'unione, nel momento di decidere quale revisione preferire. L'effetto del comando può essere visto nella <xref linkend="fig:undo:bad-merge-2"/>.</para>
   2.327 +	  <figure id="fig:undo:bad-merge-2">
   2.328 +	    <title>Ritirare l'unione favorendo un genitore</title>
   2.329 +	    <mediaobject>
   2.330 +	      <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject>
   2.331 +	      <textobject><phrase>XXX add text</phrase></textobject>
   2.332 +	    </mediaobject>
   2.333 +	  </figure>
   2.334 +	</listitem>
   2.335 +
   2.336 +	<listitem>
   2.337 +	  <para id="x_6bf">Invocare <command role="hg-cmd">hg backout --rev=4 --parent=3</command>. Questo dice al comando <command role="hg-cmd">hg backout</command> di ritirare ancora la revisione 4, ma questa volta scegliendo il genitore 3, l'altro genitore dell'unione. Il risultato è visibile nella <xref linkend="fig:undo:bad-merge-3"/>, in cui il repository ora contiene tre teste.</para>
   2.338 +	  <figure id="fig:undo:bad-merge-3">
   2.339 +	    <title>Ritirare l'unione favorendo l'altro genitore</title>
   2.340 +	    <mediaobject>
   2.341 +	      <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject>
   2.342 +	      <textobject><phrase>XXX add text</phrase></textobject>
   2.343 +	    </mediaobject>
   2.344 +	  </figure>
   2.345 +	</listitem>
   2.346 +
   2.347 +	<listitem>
   2.348 +	  <para id="x_6c0">Rifare l'unione sbagliata unendo le due teste generate dai ritiri, riducendo quindi a due il numero di teste nel repository, come si può vedere nella <xref linkend="fig:undo:bad-merge-4"/>.</para>
   2.349 +	  <figure id="fig:undo:bad-merge-4">
   2.350 +	    <title>Unire i risultati dei ritiri</title>
   2.351 +	    <mediaobject>
   2.352 +	      <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject>
   2.353 +	      <textobject><phrase>XXX add text</phrase></textobject>
   2.354 +	    </mediaobject>
   2.355 +	  </figure>
   2.356 +	</listitem>
   2.357 +
   2.358 +	<listitem>
   2.359 +	  <para id="x_6c1">Eseguire un'unione con il commit che è stato eseguito dopo l'unione sbagliata, come mostrato nella <xref linkend="fig:undo:bad-merge-5"/>.</para>
   2.360 +	  <figure id="fig:undo:bad-merge-5">
   2.361 +	    <title>Unire i risultati dei ritiri</title>
   2.362 +	    <mediaobject>
   2.363 +	      <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject>
   2.364 +	      <textobject><phrase>XXX add text</phrase></textobject>
   2.365 +	    </mediaobject>
   2.366 +	  </figure>
   2.367 +	</listitem>
   2.368 +      </orderedlist>
   2.369 +    </sect2>
   2.370 +
   2.371 +    <sect2>
   2.372 +      <title>Proteggervi dai cambiamenti che vi sono <quote>sfuggiti</quote></title>
   2.373 +
   2.374 +      <para id="x_123">Se avete inserito alcuni cambiamenti nel vostro repositor locale e li avete propagati da qualche altra parte, questo non costituisce necessariamente un disastro. Potete proteggervi prevenendo la comparsa di alcuni tipi di changeset sbagliati. Questo è particolarmente facile se il vostro gruppo di lavoro di solito estrae i cambiamenti da un repository centrale.</para>
   2.375 +
   2.376 +      <para id="x_124">Configurando alcuni hook su quel repository per validare i changeset in entrata (si veda il <xref linkend="chap:hook"/>), potete automaticamente evitare che alcuni tipi di changeset sbagliati compaiano nel repository centrale. Con una tale configurazione, alcuni tipi di changeset sbagliati tenderanno naturalmente a <quote>estinguersi</quote> perché non possono propagarsi verso il repository centrale. Ancora meglio, questo accade senza alcun bisogno di un intervento esplicito.</para>
   2.377 +
   2.378 +      <para id="x_125">Per esempio, un hook sui cambiamenti in entrata che verifica che un changeset si riesca effettivamente a compilare può prevenire involontari <quote>guasti</quote> al processo di assemblaggio.</para>
   2.379 +    </sect2>
   2.380 +
   2.381 +    <sect2>
   2.382 +      <title>Cosa fare con i cambiamenti sensibili che sfuggono</title>
   2.383 +
   2.384 +      <para id="x_6c2">Persino un progetto gestito con attenzione può subire uno sfortunato evento come il commit e l'incontrollata propagazione di un file che contiene password importanti.</para>
   2.385 +
   2.386 +      <para id="x_6c3">Se qualcosa del genere dovesse accadervi e le informazioni che vengono accidentalmente propagate sono davvero sensibili, il vostro primo passo dovrebbe essere quello di mitigare l'effetto della perdita senza cercare di controllare la perdita stessa. Se non siete sicuri al 100% di sapere esattamente chi può aver visto i cambiamenti, dovreste immediatamente cambiare le password, cancellare le carte di credito, o trovare qualche altro modo per assicurarvi che le informazioni fuoriuscite non siano più utili. In altre parole, assumete che il cambiamento si sia propagato in lungo e in largo e che non ci sia più niente che potete fare.</para>
   2.387 +
   2.388 +      <para id="x_6c4">Potreste sperare che ci sia qualche meccanismo che potete usare per scoprire chi ha visto un cambiamento o per cancellare il cambiamento permanentemente e ovunque, ma ci sono buone ragioni per cui queste operazioni non sono possibili.</para>
   2.389 +
   2.390 +      <para id="x_6c5">Mercurial non fornisce una ~audit trail~ di chi ha estratto i cambiamenti da un repository, perché di solito questa informazione è impossibile registrare o è facile da imbrogliare. In un ambiente multi-utente o di rete, dovreste quindi dubitare estremamente di voi stessi se pensate di aver identificato ogni luogo in cui un cambiamento sensibile si è propagato. Non dimenticate che le persone possono spedire pacchetti via email, salvare i propri dati su altri computer tramite il software di backup, trasportare i repository su chiavi USB e trovare altri modi completamente innocenti di confondere i vostri tentativi di ritrovare ogni copia di un cambiamento problematico.</para>
   2.391 +
   2.392 +      <para id="x_6c6">In più, Mercurial non vi fornisce un modo per far completamente sparire un changeset dalla cronologia perché non c'è alcun modo di imporre la sua sparizione, dato che qualcuno potrebbe facilmente modificare la propria copia di Mercurial per ignorare quelle direttive. E poi, se anche Mercurial fornisse questa funzionalità, qualcuno che semplicemente non abbia estratto il changeset che <quote>fa sparire questo file</quote> non ne godrebbe gli effetti, né lo farebbero i ~web crawler~ che visitano un repository al momento sbagliato, i backup del disco, o altri meccanismi. In effetti, nessun sistema distribuito di controllo di revisione può far sparire dati in maniera affidabile. Dare l'illusione di un controllo di questo tipo potrebbe facilmente fornirvi un falso senso di sicurezza, peggiorando le cose rispetto a non darvela affatto.</para>
   2.393 +    </sect2>
   2.394 +  </sect1>
   2.395 +
   2.396 +  <sect1 id="sec:undo:bisect">
   2.397 +    <title>Trovare la causa di un bug</title>
   2.398 +
   2.399 +    <para id="x_126">Mentre va benissimo essere in grado di ritirare un changeset che ha introdotto un bug, questo richiede che sappiate quale changeset va ritirato. Mercurial offre un inestimabile comando, chiamato <command role="hg-cmd">hg bisect</command>, che vi aiuta ad automatizzare questo processo e a completarlo in maniera molto efficiente.</para>
   2.400 +
   2.401 +    <para id="x_127">L'idea dietro al comando <command role="hg-cmd">hg bisect</command> è che un changeset ha introdotto una modifica di comportamento che potete identificare con un semplice test binario di successo o fallimento. Non sapete quale porzione di codice ha introdotto il cambiamento, ma sapete come verificare la presenza del bug. Il comando <command role="hg-cmd">hg bisect</command> usa il vostro test per dirigere la propria ricerca del changeset che ha introdotto il codice che ha causato il bug.</para>
   2.402 +
   2.403 +    <para id="x_128">Ecco alcuni scenari per aiutarvi a capire come potreste applicare questo comando.</para>
   2.404 +    <itemizedlist>
   2.405 +      <listitem><para id="x_129">La versione più recente del vostro software ha un bug che non ricordate fosse presente alcune settimane prima, ma non sapete quando il bug è stato introdotto. Qui, i vostri test binari controllano la presenza di quel bug.</para>
   2.406 +      </listitem>
   2.407 +      <listitem><para id="x_12a">Avete corretto un bug in tutta fretta e ora è il momento di chiudere la relativa voce nel database dei bug del vostro gruppo. Il database dei bug richiede un identificatore di changeset quando chiudete una voce, ma non ricordate in quale changeset avete corretto il bug. Ancora una volta, il vostro test binario controlla la presenza del bug.</para>
   2.408 +      </listitem>
   2.409 +      <listitem><para id="x_12b">Il vostro software funziona correttamente, ma più lento del 15% rispetto all'ultima volta che avete compiuto questa misurazione. Volete sapere quale changeset ha introdotto la perdita di prestazioni. In questo caso, il vostro test binario misura le prestazioni del vostro software per vedere se è <quote>veloce</quote> o <quote>lento</quote>.</para>
   2.410 +      </listitem>
   2.411 +      <listitem><para id="x_12c">La dimensione dei componenti del progetto che rilasciate è esplosa di recente e sospettate che qualcosa sia cambiato nel modo in cui assemblate il progetto.</para>
   2.412 +      </listitem></itemizedlist>
   2.413 +
   2.414 +    <para id="x_12d">Da questi esempi, dovrebbe essere chiaro che il comando <command role="hg-cmd">hg bisect</command> non è utile solo per trovare le cause dei bug. Potete usarlo per trovare qualsiasi <quote>proprietà emergente</quote> di un repository (qualsiasi cosa che non potete trovare con una semplice ricerca di testo sui file contenuti nell'albero) per la quale sia possibile scrivere un test binario.</para>
   2.415 +
   2.416 +    <para id="x_12e">Ora introdurremo un po' di terminologia, giusto per chiarire quali sono le parti del processo di ricerca di cui siete responsabili e quali sono quelle di cui è responsabile Mercurial. Un <emphasis>test</emphasis> è qualcosa che <emphasis>voi</emphasis> eseguite quando <command role="hg-cmd">hg bisect</command> sceglie un changeset. Una <emphasis>sonda</emphasis> è ciò che <command role="hg-cmd">hg bisect</command> esegue per dirvi se una revisione è buona. Infine, useremo la parola <quote>bisezione</quote> come nome e <quote>bisezionare</quote> come verbo per intendere la <quote>ricerca tramite il comando <command role="hg-cmd">hg bisect</command></quote>.</para>
   2.417 +
   2.418 +    <para id="x_12f">Un modo semplice per automatizzare il processo di ricerca sarebbe quello di collaudare semplicemente ogni changeset. Tuttavia, questo scala malamente. Se ci volessero dieci minuti per collaudare un singolo changeset e aveste 10.000 changeset nel vostro repository, l'approccio completo impiegherebbe una media di 35 <emphasis>giorni</emphasis> per trovare il changeset che ha introdotto un bug. Anche se sapeste che il bug è stato introdotto in uno degli ultimi 500 changeset e limitaste la ricerca a quelli, dovrebbero passare più di 40 ore di attesa per trovare il changeset che ha introdotto il vostro bug.</para>
   2.419 +
   2.420 +    <para id="x_130">Il comando <command role="hg-cmd">hg bisect</command> invece usa la propria conoscenza della <quote>forma</quote> della cronologia delle revisioni del vostro progetto per effettuare una ricerca in tempo proporzionale al <emphasis>logaritmo</emphasis> del numero dei changeset da controllare (il tipo di ricerca che esegue viene chiamata ricerca dicotomica). Con questo approccio, la ricerca attraverso 10.000 changeset impiegherà meno di 3 ore, anche a 10 minuti per ogni test (la ricerca richiederà circa 14 test). Limitate la vostra ricerca agli ultimi cento changeset e il tempo impiegato sarà solo circa un'ora (approssimativamente sette test).</para>
   2.421 +
   2.422 +    <para id="x_131">Il comando <command role="hg-cmd">hg bisect</command> è consapevole della natura <quote>ramificata</quote> della cronologia delle revisioni di un progetto Mercurial, quindi non ha problemi a trattare con rami, unioni, o molteplici teste in un repository. Opera in maniera così efficiente perché è in grado di potare interi rami di cronologia con una singola sonda.</para>
   2.423 +
   2.424 +    <sect2>
   2.425 +      <title>Usare il comando <command role="hg-cmd">hg bisect</command></title>
   2.426 +
   2.427 +      <para id="x_132">Ecco un esempio di <command role="hg-cmd">hg bisect</command> in azione.</para>
   2.428 +
   2.429 +      <note>
   2.430 +	<para id="x_133">Fino alla versione 0.9.5 di Mercurial compresa, <command role="hg-cmd">hg bisect</command> non era uno dei comandi principali, ma veniva distribuito con Mercurial sotto forma di estensione. Questa sezione descrive il comando predefinito, non la vecchia estensione.</para>
   2.431 +      </note>
   2.432 +
   2.433 +      <para id="x_134">Ora creiamo un nuovo repository in modo che possiate provare il comando <command role="hg-cmd">hg bisect</command> in isolamento.</para>
   2.434 +
   2.435 +      &interaction.bisect.init;
   2.436 +
   2.437 +      <para id="x_135">Simuleremo un progetto che ha un bug in modo molto semplice: creiamo cambiamenti elementari in un ciclo e nomineremo uno specifico cambiamento che conterrà il <quote>bug</quote>. Questo ciclo crea 35 changeset, ognuno dei quali aggiunge un singolo file al repository. Rappresenteremo il nostro <quote>bug</quote> con un file che contiene il testo <quote>i have a gub</quote>.</para>
   2.438 +
   2.439 +      &interaction.bisect.commits;
   2.440 +
   2.441 +      <para id="x_136">La prossima cosa che vorremmo fare è capire come usare il comando <command role="hg-cmd">hg bisect</command>. Possiamo usare il normale meccanismo di aiuto predefinito di Mercurial per fare questo.</para>
   2.442 +
   2.443 +      &interaction.bisect.help;
   2.444 +
   2.445 +      <para id="x_137">Il comando <command role="hg-cmd">hg bisect</command> lavora in più passi. Ogni passo procede nella maniera seguente.</para>
   2.446 +      <orderedlist>
   2.447 +	<listitem><para id="x_138">Eseguite il vostro test binario.</para>
   2.448 +	  <itemizedlist>
   2.449 +	    <listitem><para id="x_139">Se il test ha avuto successo, informate <command role="hg-cmd">hg bisect</command> invocando il comando <command role="hg-cmd">hg bisect --good</command>.</para>
   2.450 +	    </listitem>
   2.451 +	    <listitem><para id="x_13a">Se il test è fallito, invocate il comando <command role="hg-cmd">hg bisect --bad</command>.</para>
   2.452 +	</listitem>
   2.453 +	<listitem><para id="x_13b">Il comando usa le vostre informazioni per decidere quale changeset collaudare successivamente.</para>
   2.454 +	</listitem>
   2.455 +	<listitem><para id="x_13c">Il comando aggiorna la directory di lavoro a quel changeset e il processo ricomincia da capo.</para>
   2.456 +	</listitem></orderedlist>
   2.457 +      <para id="x_13d">Il processo termina quando <command role="hg-cmd">hg bisect</command> identifica un unico cambiamento che contrassegna il punto in cui il vostro test passa dallo stato di <quote>successo</quote> a quello di <quote>fallimento</quote>.</para>
   2.458 +
   2.459 +      <para id="x_13e">Per cominciare la ricerca, dobbiamo eseguire il comando <command role="hg-cmd">hg bisect --reset</command>.</para>
   2.460 +
   2.461 +      &interaction.bisect.search.init;
   2.462 +
   2.463 +      <para id="x_13f">Nel nostro caso, il test binario che usiamo è semplice: controlliamo per vedere se qualche file nel repository contiene la stringa <quote>i have a gub</quote>. Se è così, questo changeset contiene il cambiamento che ha <quote>causato il bug</quote>. Per convenzione, un changeset che ha la proprietà che stiamo cercando è <quote>guasto</quote>, mentre uno che non ce l'ha è <quote>corretto</quote>.</para>
   2.464 +
   2.465 +      <para id="x_140">Quasi sempre, la revisione su cui la directory di lavoro è sincronizzata (di solito, la punta) esibisce già il problema introdotto dal cambiamento malfunzionante, quindi la contrassegneremo come <quote>guasta</quote>.</para>
   2.466 +
   2.467 +      &interaction.bisect.search.bad-init;
   2.468 +
   2.469 +      <para id="x_141">Il nostro compito successivo consiste nel nominare un changeset che sappiamo <emphasis>non</emphasis> contenere il bug, in modo che il comando <command role="hg-cmd">hg bisect</command> possa <quote>circoscrivere</quote> la ricerca tra il primo changeset corretto e il primo changeset guasto. Nel nostro caso, sappiamo che la revisione 10 non conteneva il bug. (Spiegherò meglio come scegliere il primo changeset <quote>corretto</quote> più avanti.)</para>
   2.470 +
   2.471 +      &interaction.bisect.search.good-init;
   2.472 +
   2.473 +      <para id="x_142">Notate che questo comando ha stampato alcune informazioni.</para>
   2.474 +      <itemizedlist>
   2.475 +	<listitem><para id="x_143">Ci ha detto quanti changeset deve considerare prima di poter identificare quello che ha introdotto il bug e quanti test saranno richiesti dal processo.</para>
   2.476 +	</listitem>
   2.477 +	<listitem><para id="x_144">Ha aggiornato la directory di lavoro al prossimo changeset da collaudare e ci ha detto quale changeset sta collaudando.</para>
   2.478 +	</listitem></itemizedlist>
   2.479 +
   2.480 +      <para id="x_145">Ora eseguiamo il nostro test nella directory di lavoro, usando il comando <command>grep</command> per vedere se il nostro file <quote>guasto</quote> è presente. Se c'è, questa revisione è guasta, altrimenti è corretta.</para>
   2.481 +      
   2.482 +      &interaction.bisect.search.step1;
   2.483 +
   2.484 +      <para id="x_146">Questo test sembra un perfetto candidato per l'automazione, quindi trasformiamolo in una funzione di shell.</para>
   2.485 +      
   2.486 +      &interaction.bisect.search.mytest;
   2.487 +
   2.488 +      <para id="x_147">Ora possiamo eseguire un intero passo di collaudo con il singolo comando <literal>mytest</literal>.</para>
   2.489 +
   2.490 +      &interaction.bisect.search.step2;
   2.491 +
   2.492 +      <para id="x_148">Ancora qualche altra invocazione del comando che abbiamo preparato per il passo di collaudo e abbiamo finito.</para>
   2.493 +
   2.494 +      &interaction.bisect.search.rest;
   2.495 +
   2.496 +      <para id="x_149">Anche se avevamo 40 changeset attraverso cui cercare, il comando <command role="hg-cmd">hg bisect</command> ci ha permesso di trovare il changeset che ha introdotto il nostro <quote>bug</quote> usando solo cinque test. Dato che il numero di test effettuati dal comando <command role="hg-cmd">hg bisect</command> cresce con il logaritmo del numero dei changeset da analizzare, il vantaggio che ha rispetto a una ricerca che usa la strategia della <quote>forza bruta</quote> aumenta con ogni changeset che aggiungete.</para>
   2.497 +
   2.498 +    </sect2>
   2.499 +    <sect2>
   2.500 +      <title>Riordinare dopo la vostra ricerca</title>
   2.501 +
   2.502 +      <para id="x_14a">Quando avete finito di usare il comando <command role="hg-cmd">hg bisect</command> in un repository, potete invocare il comando <command role="hg-cmd">hg bisect --reset</command> per scartare le informazioni che venivano usate per guidare la vostra ricerca. Il comando non usa molto spazio, quindi non importa se vi dimenticate di effettuare questa esecuzione. Tuttavia, <command role="hg-cmd">hg bisect</command> non vi permetterà di cominciare una nuova ricerca in quel repository fino a quando non avrete eseguito <command role="hg-cmd">hg bisect --reset</command>.</para>
   2.503 +
   2.504 +      &interaction.bisect.search.reset;
   2.505 +
   2.506 +    </sect2>
   2.507 +  </sect1>
   2.508 +  <sect1>
   2.509 +    <title>Suggerimenti per trovare efficacemente i bug</title>
   2.510 +
   2.511 +    <sect2>
   2.512 +      <title>Fornire informazioni consistenti</title>
   2.513 +
   2.514 +      <para id="x_14b">Il comando <command role="hg-cmd">hg bisect</command> vi richiede di riportare correttamente il risultato di ogni test che eseguite. Se dite al comando che un test è fallito quando in realtà ha avuto successo, <emphasis>potrebbe</emphasis> essere in grado di scoprire l'inconsistenza. Se può identificare un'incosistenza nei vostri resoconti, vi dirà che un particolare changeset è sia corretto che guasto. Tuttavia, non è in grado di farlo perfettamente ed è ugualmente probabile che vi restituisca il changeset sbagliato come causa del bug.</para>
   2.515 +
   2.516 +    </sect2>
   2.517 +    <sect2>
   2.518 +      <title>Automatizzare il più possibile</title>
   2.519 +
   2.520 +      <para id="x_14c">Quando ho cominciato a usare il comando <command role="hg-cmd">hg bisect</command>, ho provato a eseguire alcune volte i miei test a mano sulla riga di comando. Questo è un approccio che almeno a me non si addice. Dopo alcune prove, ho visto che stavo facendo abbastanza errori da dover ricominciare le mie ricerche diverse volte prima di riuscire a ottenere i risultati corretti.</para>
   2.521 +
   2.522 +      <para id="x_14d">I miei problemi iniziali nel guidare a mano il comando <command role="hg-cmd">hg bisect</command> si sono verificati anche con ricerche semplici su repository di piccole dimensioni, ma se il problema che state cercando è più sottile, o se il numero di test che <command role="hg-cmd">hg bisect</command> deve eseguire aumenta, la probabilità che un errore umano rovini la ricerca è molto più alta. Una volta che ho cominciato ad automatizzare i miei test, ho ottenuto risultati molto migliori.</para>
   2.523 +
   2.524 +      <para id="x_14e">La chiave del collaudo automatizzato è duplice:</para>
   2.525 +      <itemizedlist>
   2.526 +	<listitem><para id="x_14f">verificate sempre lo stesso sintomo, e</para>
   2.527 +	</listitem>
   2.528 +	<listitem><para id="x_150">fornite sempre informazioni consistenti al comando <command role="hg-cmd">hg bisect</command>.</para>
   2.529 +	</listitem></itemizedlist>
   2.530 +      <para id="x_151">Nel mio esempio precedente, il comando <command>grep</command> verifica il sintomo e l'istruzione <literal>if</literal> prende il risultato di questo controllo e si assicura di fornire la stessa informazione al comando <command role="hg-cmd">hg bisect</command>. La funzione <literal>mytest</literal> ci permette di riprodurre insieme queste due operazioni, in modo che ogni test sia uniforme e consistente.</para>
   2.531 +
   2.532 +    </sect2>
   2.533 +    <sect2>
   2.534 +      <title>Controllare i vostri risultati</title>
   2.535 +
   2.536 +      <para id="x_152">Dato che il risultato di una ricerca con <command role="hg-cmd">hg bisect</command> è solo tanto buona quanto le informazioni che passate al comando, non prendete il changeset che vi indica come la verità assoluta. Un modo semplice di effettuare un riscontro sul risultato è quello di eseguire manualmente i vostro test su ognuno dei changeset seguenti.</para>
   2.537 +      <itemizedlist>
   2.538 +	<listitem><para id="x_153">Il changeset che il comando riporta come la prima revisione guasta. Il vostro test dovrebbe verificare che la revisione è effettivamente guasta.</para>
   2.539 +	</listitem>
   2.540 +	<listitem><para id="x_154">Il genitore di quel changeset (entrambi i genitori, se è un'unione). Il vostro test dovrebbe verificare che quel changeset è corretto.</para>
   2.541 +	</listitem>
   2.542 +	<listitem><para id="x_155">Un figlio di quel changeset. Il vostro test dovrebbe verificare che quel changeset è guasto.</para>
   2.543 +	</listitem></itemizedlist>
   2.544 +
   2.545 +    </sect2>
   2.546 +    <sect2>
   2.547 +      <title>Fate attenzione alle interferenze tra i bug</title>
   2.548 +
   2.549 +      <para id="x_156">&Egrave; possibile che la vostra ricerca di un bug venga rovinata dalla presenza di un altro bug. Per esempio, diciamo che il vostro software ~crashes~ alla revisione 100 e funziona correttamente alla revisione 50. Senza che voi lo sappiate, qualcun altro ha introdotto un ~crashing~ bug differente alla revisione 60 e lo ha corretto alla revisione 80. Questo potrebbe distorcere i vostri risultati in vari modi.</para>
   2.550 +
   2.551 +      <para id="x_157">&Egrave; possibile che questo altro bug <quote>mascheri</quote> completamente il vostro, cioè che sia comparso prima che il vostro bug abbia avuto la possibilità di manifestarsi. Se non potete evitare quell'altro bug (per esempio, impedisce al vostro progetto di venire assemblato) e quindi non potete dire se il vostro bug è presente in un particolare changeset, il comando <command role="hg-cmd">hg bisect</command> non è in grado di aiutarvi direttamente. Invece, invocando <command role="hg-cmd">hg bisect --skip</command> potete contrassegnare un changeset come non collaudato.</para>
   2.552 +
   2.553 +      <para id="x_158">Potrebbe esserci un problema differente se il vostro test per la presenza di un bug non è abbastanza specifico. Se controllate che <quote>il mio programma ~crashes~</quote>, allora sia il vostro ~crashing~ bug che un ~crashing~ bug non correlato che lo maschera sembreranno la stessa cosa e fuorvieranno <command role="hg-cmd">hg bisect</command>.</para>
   2.554 +
   2.555 +      <para id="x_159">Un'altra situazione utile in cui sfruttare <command role="hg-cmd">hg bisect --skip</command> è quella in cui non potete collaudare una revisione perché il vostro progetto era guasto e quindi in uno stato non collaudabile in quella revisione, magari perché qualcuno aveva introdotto un cambiamento che impediva al progetto di venire assemblato.</para>
   2.556 +
   2.557 +    </sect2>
   2.558 +    <sect2>
   2.559 +      <title>Circoscrivete la vostra ricerca in maniera ritardata</title>
   2.560 +
   2.561 +      <para id="x_15a">Scegliere il primo changeset <quote>corretto</quote> e il primo changeset <quote>guasto</quote> che contrassegneranno i punti estremi della vostra ricerca è spesso facile, ma merita comunque una breve discussione. Dal punto di vista di <command role="hg-cmd">hg bisect</command>, il changeset <quote>più recente</quote> è convenzionalmente <quote>guasto</quote> e il changeset <quote>più vecchio</quote> è <quote>corretto</quote>.</para>
   2.562 +
   2.563 +      <para id="x_15b">Se avete problemi a ricordare dove si trova un changeset <quote>corretto</quote> da fornire al comando <command role="hg-cmd">hg bisect</command>, non potreste fare meglio che collaudare changeset a caso. Ricordatevi di eliminare i contendenti che non possono esibire il bug (magari perché la funzionalità con il bug non era ancora presente) e quelli in cui un altro problema nasconde il bug (come ho discusso in precedenza).</para>
   2.564 +
   2.565 +      <para id="x_15c">Anche se i vostri tentativi si concludono <quote>in anticipo</quote> di migliaia di changeset o di mesi di cronologia, aggiungerete solo una manciata di test al numero totale che <command role="hg-cmd">hg bisect</command> deve eseguire, grazie al suo comportamento logaritmico.</para>
   2.566 +
   2.567 +    </sect2>
   2.568 +  </sect1>
   2.569 +</chapter>