hgbook
view it/ch10-hook.xml @ 801:fcddc33b6e4d
Wording.
| author | Giulio@puck |
|---|---|
| date | Fri Aug 14 16:10:54 2009 +0200 (2009-08-14) |
| parents | 8888db7085e8 |
| children | 0727262f69d1 |
line source
1 <chapter id="chap:hook">
2 <?dbhtml filename="usare-gli-hook-per-gestire-gli-eventi-nei-repository.html"?>
3 <title>Usare gli hook per gestire gli eventi nei repository</title>
5 <para id="x_1e6">Mercurial vi offre un potente meccanismo per effettuare azioni automatiche in risposta agli eventi che accadono in un repository. In alcuni casi, potete persino controllare la risposta di Mercurial a questi eventi.</para>
7 <para id="x_1e7">Il nome che Mercurial usa per indicare una di queste azioni è <emphasis>hook</emphasis> (letteralmente, gancio). Gli hook vengono chiamati <quote>trigger</quote> (letteralmente, grilletto) in alcuni sistemi di controllo di revisione, ma i due nomi si riferiscono alla stessa idea.</para>
9 <sect1>
10 <title>Un'introduzione agli hook di Mercurial</title>
12 <para id="x_1e8">Qui di seguito troverete una breve lista degli hook supportati da Mercurial. Rivisiteremo ognuno di questi hook in maggior dettaglio più avanti, nella <xref linkend="sec:hook:ref"/>.</para>
14 <para id="x_1f6">Ognuno degli hook che viene indicato come <quote>hook di controllo</quote> nella propria descrizione ha l'abilità di determinare se un'attività può procedere. Se l'hook ha successo, l'attività può procedere; se fallisce, l'attività non viene permessa oppure viene annullata, a seconda dell'hook.</para>
16 <itemizedlist>
17 <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: viene eseguito dopo che un gruppo di changeset proveniente da qualche altra parte è stato propagato nel repository.</para>
18 </listitem>
19 <listitem><para id="x_1ea"><literal role="hook">commit</literal>: viene eseguito dopo la creazione di un nuovo changeset nel repository locale.</para>
20 </listitem>
21 <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: viene eseguito una volta per ogni nuovo changeset proveniente da qualche altra parte che è stato propagato nel repository. Notate la differenza con <literal role="hook">changegroup</literal>, che viene eseguito una volta per ogni <emphasis>gruppo</emphasis> di changeset propagato nel repository.</para>
22 </listitem>
23 <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: viene eseguito dopo che un gruppo di changeset è stato trasmesso da questo repository.</para>
24 </listitem>
25 <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: viene eseguito prima di cominciare a propagare un gruppo di changeset nel repository.</para>
26 </listitem>
27 <listitem><para id="x_1ee"><literal role="hook">precommit</literal>:
28 hook di controllo. Viene eseguito prima di cominciare un inserimento.</para>
29 </listitem>
30 <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: hook di controllo. Viene eseguito prima di cominciare a trasmettere un gruppo di changeset da questo repository.</para>
31 </listitem>
32 <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: hook di controllo. Viene eseguito prima di creare un'etichetta.</para>
33 </listitem>
34 <listitem><para id="x_1f1"><literal role="hook">pretxnchangegroup</literal>: hook di controllo. Viene eseguito dopo che un gruppo di changeset proveniente da un altro repository è stato propagato nel repository locale, ma prima di completare la transazione che renderebbe permanenti i cambiamenti nel repository.</para>
35 </listitem>
36 <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: hook di controllo. Viene eseguito dopo la creazione di un nuovo changeset nel repository locale, ma prima di completare la transazione che lo renderebbe permanente.</para>
37 </listitem>
38 <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: hook di controllo. Viene eseguito prima di cominciare un aggiornamento o un'unione della directory di lavoro.</para>
39 </listitem>
40 <listitem><para id="x_1f4"><literal role="hook">tag</literal>: viene eseguito dopo la creazione di un'etichetta.</para>
41 </listitem>
42 <listitem><para id="x_1f5"><literal role="hook">update</literal>: viene eseguito dopo che un'operazione di aggiornamento o di unione della directory di lavoro è stata completata.</para>
43 </listitem></itemizedlist>
45 </sect1>
46 <sect1>
47 <title>Hook e sicurezza</title>
49 <sect2>
50 <title>Gli hook vengono eseguiti con i vostri privilegi</title>
52 <para id="x_1f7">Quando invocate un comando Mercurial in un repository e quel comando causa l'esecuzione di un hook, quell'hook viene eseguito sul <emphasis>vostro</emphasis> sistema, con il <emphasis>vostro</emphasis> account utente, al <emphasis>vostro</emphasis> livello di privilegio. Dato che gli hook sono frammenti di codice eseguibile, dovreste trattarli in maniera adeguatamente sospettosa. Non installate un hook a meno che non confidiate di sapere chi lo ha creato e che cosa fa.</para>
54 <para id="x_1f8">In alcuni casi, potreste essere esposti a hook che non avete installato voi. Se lavorate con Mercurial su un sistema che non vi è familiare, sappiate che Mercurial eseguirà gli hook definiti nel file <filename role="special">~/.hgrc</filename> globale per quel sistema.</para>
56 <para id="x_1f9">Se state lavorando con un repository posseduto da un altro utente, Mercurial può eseguire gli hook definiti nel repository di quell'utente, ma li eseguirà ancora sotto la <quote>vostra identità</quote>. Per esempio, se estraete i cambiamenti da quel repository tramite <command role="hg-cmd">hg pull</command>, e il suo file <filename role="special">.hg/hgrc</filename> definisce un hook <literal role="hook">outgoing</literal> locale, quell'hook verrà eseguito con il vostro account utente anche se non siete il proprietario di quel repository.</para>
58 <note>
59 <para id="x_1fa">Questo avviene solo se estraete cambiamenti da un repository operando su un file system locale o di rete. Se state effettuando l'estrazione via HTTP o ssh, qualsiasi hook <literal role="hook">outgoing</literal> verrà eseguito sul server con l'account utente che è stato usato per eseguire il processo server.</para>
60 </note>
62 <para id="x_1fb">Per vedere quali hook sono definiti in un repository, usate il comando <command role="hg-cmd">hg showconfig hooks</command>. Se state lavorando in un repository, ma state comunicando con un repository di cui non siete i proprietari (e.g. usando <command role="hg-cmd">hg pull</command> o <command role="hg-cmd">hg incoming</command>), ricordate che sono gli hook dell'altro repository che dovreste controllare, non i vostri.</para>
63 </sect2>
65 <sect2>
66 <title>Gli hook non si propagano</title>
68 <para id="x_1fc">In Mercurial, gli hook non sono soggetti a controllo di revisione e non si propagano quando clonate un repository o ne estraete i cambiamenti. La ragione è semplice: un hook è un frammento di codice eseguibile completamente arbitrario. Viene eseguito sotto l'identità del vostro utente, al vostro livello di privilegio, sulla vostra macchina.</para>
70 <para id="x_1fd">Sarebbe estremamente avventato per qualsiasi sistema distribuito di controllo di revisione implementare hook soggetti al controllo di revisione, dato che questo offrirebbe un modo facilmente sfruttabile per alterare gli account degli utenti del sistema di controllo di revisione.</para>
72 <para id="x_1fe">Dato che Mercurial non propaga gli hook, se state collaborando con altre persone su un progetto comune, non dovreste presumere che gli altri stiano usando gli stessi hook Mercurial che state usando voi, o che i loro siano correttamente configurati. Dovreste documentare quali sono gli hook che vi aspettate siano usati dalle altre persone.</para>
74 <para id="x_1ff">In una intranet aziendale, questo aspetto è in qualche modo più facile da controllare, dato che per esempio potete fornire un'installazione <quote>standard</quote> di Mercurial su un file system NFS e usare un file <filename role="special">~/.hgrc</filename> globale per definire hook che verranno visti da tutti gli utenti. Tuttavia, come constateremo nella prossima sezione, anche questo approccio ha dei limiti.</para>
75 </sect2>
77 <sect2>
78 <title>Gli hook possono essere sostituiti</title>
80 <para id="x_200">Mercurial vi consente di sostituire una definizione di hook attraverso la sua ridefinizione. Potete disabilitare un hook impostando il suo valore alla stringa vuota, o cambiare il suo comportamento come desiderate.</para>
82 <para id="x_201">Se fate ricorso a un file <filename role="special">~/.hgrc</filename> di sistema o globale che definisce alcuni hook, dovreste quindi tenere presente che i vostri utenti sono in grado di disabilitare o sostituire quegli hook.</para>
83 </sect2>
85 <sect2>
86 <title>Assicurarsi che gli hook critici vengano eseguiti</title>
88 <para id="x_202">Talvolta potreste voler imporre il rispetto di una politica in modo che gli altri non siano in grado di aggirarla. Per esempio, potreste richiedere a ogni changeset di passare una rigorosa serie di test. La definizione di questo requisito attraverso un hook in un file <filename role="special">~/.hgrc</filename> globale non avrà effetto sui computer portatili degli utenti remoti, e naturalmente gli utenti locali potranno alterarla a piacimento sostituendo quell'hook.</para>
90 <para id="x_203">Invece, potete istituire le vostre politiche sull'uso di Mercurial in modo che le persone siano tenute a propagare i cambiamenti attraverso un server <quote>ufficiale</quote> ben noto che avete messo in sicurezza e configurato adeguatamente.</para>
92 <para id="x_204">Questo risultato si può ottenere attraverso una combinazione di ingegneria sociale e tecnologia. Se impostate un account con accesso ristretto, gli utenti potranno trasmettere i cambiamenti attraverso la rete ai repository gestiti da questo account, ma non potranno usare l'account per entrare sul server ed eseguire i normali comandi di shell. In questo scenario, un utente può effettuare il commit di un changeset che contiene tutte le porcherie che desidera.</para>
94 <para id="x_205">Quando qualcuno trasmette un changeset al server da cui tutti estraggono i cambiamenti, il server verificherà il changeset prima di accettarlo come permanente e lo rifiuterà se non riesce a passare i test. Se le persone si limitano a estrarre i cambiamenti da questo server di filtraggio, questo servirà ad assicurare che tutti i cambiamenti estratti dalle persone siano stati automaticamente controllati.</para>
96 </sect2>
97 </sect1>
99 <sect1 id="sec:hook:simple">
100 <title>Una breve guida all'uso degli hook</title>
102 <para id="x_212">Scrivere un hook Mercurial è facile. Cominciamo con un hook che viene invocato al termine dell'esecuzione di <command role="hg-cmd">hg commit</command> e che stampa semplicemente l'hash del changeset appena creato. L'hook è chiamato <literal role="hook">commit</literal>.
103 </para>
105 <para id="x_213">Tutti gli hook seguono lo schema presentato in questo esempio.</para>
107 &interaction.hook.simple.init;
109 <para id="x_214">Aggiungete una voce alla sezione <literal role="rc-hooks">hooks</literal> del vostro file <filename role="special">~/.hgrc</filename>. Sulla sinistra si trova il nome dell'evento in risposta al quale attivarsi, sulla destra si trova l'azione da intraprendere. Come vedete, è possibile eseguire comandi di shell arbitrari in un hook. Mercurial passa informazioni aggiuntive all'hook usando le variabili d'ambiente (cercate <envar>HG_NODE</envar> nell'esempio).</para>
111 <sect2>
112 <title>Effettuare molteplici azioni per evento</title>
114 <para id="x_215">Vi capiterà piuttosto spesso di voler definire più di un hook per un particolare tipo di evento, come mostrato qui sotto.</para>
116 &interaction.hook.simple.ext;
118 <para id="x_216">Mercurial vi permette di fare questo aggiungendo un'<emphasis>estensione</emphasis> alla fine del nome di un hook. Il nome di un hook si estende scrivendo il nome dell'hook, seguito da un punto (il carattere <quote><literal>.</literal></quote>), seguito da altro testo di vostra scelta. Per esempio, Mercurial eseguirà sia <literal>commit.foo</literal> che <literal>commit.bar</literal> all'occorrenza dell'evento <literal>commit</literal>.</para>
120 <para id="x_217">Per stabilire un ordine di esecuzione ben definito quando più hook corrispondono allo stesso evento, Mercurial ordina gli hook secondo l'estensione ed esegue i comandi di hook in questo ordine. Nell'esempio precedente, eseguirà <literal>commit.bar</literal> prima di <literal>commit.foo</literal>, e <literal>commit</literal> prima di entrambi.</para>
122 <para id="x_218">Per aiutarvi a ricordare lo scopo di un hook, è buona norma usare un'estensione abbastanza descrittiva quando ne definite uno nuovo. Se l'hook fallisce, otterrete un messaggio di errore che contiene il nome dell'hook e l'estensione, quindi l'impiego di un'estensione descrittiva potrebbe darvi un suggerimento immediato sul motivo per cui l'hook è fallito (si veda la <xref linkend="sec:hook:perm"/> per un esempio).</para>
124 </sect2>
125 <sect2 id="sec:hook:perm">
126 <title>Controllare se un'attività può procedere</title>
128 <para id="x_219">Nei nostri primi esempi, abbiamo usato l'hook <literal role="hook">commit</literal>, che viene invocato al termine di un commit ed è uno dei vari hook Mercurial che vengono eseguiti dopo la conclusione di un'attività. Questi hook non hanno alcun modo di influenzare l'attività stessa.</para>
130 <para id="x_21a">Mercurial definisce un certo numero di eventi che accadono prima che un'attività cominci, o dopo che è cominciata ma prima che termini. Gli hook attivati da questi eventi hanno l'ulteriore capacità di determinare se l'attività può continuare o se verrà abortita.</para>
132 <para id="x_21b">L'hook <literal role="hook">pretxncommit</literal> viene invocato dopo che un commit è stato completamente eseguito ma non si è ancora concluso. In altre parole, i metadati che rappresentano il changeset sono stati scritti su disco, ma la transazione non ha ancora avuto il permesso di completarsi. L'hook <literal role="hook">pretxncommit</literal> ha la capacità di decidere se la transazione può completarsi oppure se deve essere abortita.</para>
134 <para id="x_21c">Se l'hook <literal role="hook">pretxncommit</literal> termina con un codice di stato uguale a zero, la transazione può completare, il commit si conclude e l'hook <literal role="hook">commit</literal> viene eseguito. Se l'hook <literal role="hook">pretxncommit</literal> termina con un codice di stato diverso da zero, la transazione viene abortita, i metadati che rappresentano il changeset vengono cancellati e l'hook <literal role="hook">commit</literal> non viene eseguito.</para>
136 &interaction.hook.simple.pretxncommit;
138 <para id="x_21d">In questo esempio, l'hook controlla che il messaggio di commit contenga un identificatore di bug. Se lo contiene, il commit può completare, altrimenti il commit viene abortito.</para>
140 </sect2>
141 </sect1>
142 <sect1>
143 <title>Implementare i vostri hook</title>
145 <para id="x_21e">Quando state scrivendo un hook, potreste trovare utile eseguire Mercurial con l'opzione <option role="hg-opt-global">-v</option> oppure con l'elemento di configurazione <envar role="rc-item-ui">verbose</envar> impostato a <quote>vero</quote>, in modo che Mercurial stampi un messaggio prima di invocare qualsiasi hook.</para>
147 <sect2 id="sec:hook:lang">
148 <title>Scegliere la modalità di esecuzione del vostro hook</title>
150 <para id="x_21f">Potete implementare un hook come un normale programma&emdash;tipicamente uno script di shell&emdash;o come una funzione Python che viene eseguita nell'ambito del processo Mercurial.</para>
152 <para id="x_220">Implementare un hook come programma esterno ha il vantaggio di non richiedere alcuna conoscenza del funzionamento interno di Mercurial. Potete invocare i normali comandi Mercurial per ottenere tutte le informazioni aggiuntive di cui avete bisogno. Lo svantaggio è che gli hook esterni sono più lenti rispetto agli hook interni.</para>
154 <para id="x_221">Un hook Python interno ha accesso completo alla API di Mercurial e non deve <quote>pagare</quote> la creazione di un altro processo, quindi è intrinsecamente più veloce rispetto a un hook esterno. Per ottenere la maggior parte delle informazioni richieste da un hook è anche più facile usare la API di Mercurial che eseguire i comandi Mercurial.</para>
156 <para id="x_222">Se siete a vostro agio con Python, o avete bisogno di prestazioni elevate, implementare i vostri hook in Python potrebbe essere una buona scelta. Tuttavia, quando il vostro hook è semplice da scrivere e le prestazioni non vi interessano (cose che probabilmente capitano per la maggior parte degli hook), uno script di shell è perfettamente adeguato.</para>
158 </sect2>
159 <sect2 id="sec:hook:param">
160 <title>I parametri di hook</title>
162 <para id="x_223">Mercurial invoca ogni hook con un insieme di parametri ben definito. In Python, un parametro viene passato come un argomento con nome alla vostra funzione di hook. Per un programma esterno, un parametro viene passato come una variabile d'ambiente.</para>
164 <para id="x_224">I nomi e i valori dei parametri specifici di un hook saranno gli stessi sia per gli hook implementati in Python sia per quelli realizzati come script di shell. Un parametro booleano sarà rappresentato come un valore booleano in Python, ma come una variabile d'ambiente con valore numerico 1 (per <quote>vero</quote>) o 0 (per <quote>falso</quote>) per un hook esterno. Se il nome di un parametro di hook è <literal>foo</literal>, anche l'argomento con nome per un hook Python sarà chiamato <literal>foo</literal>, mentre la variabile d'ambiente per un hook esterno sarà chiamata <literal>HG_FOO</literal>.</para>
165 </sect2>
167 <sect2>
168 <title>I valori di ritorno degli hook e il controllo delle attività</title>
170 <para id="x_225">Un hook che viene eseguito con successo deve terminare con uno stato uguale a zero se è esterno, o restituire il valore booleano <quote>falso</quote> se è interno. Il fallimento viene indicato con uno stato di terminazione diverso da zero per un hook esterno, o dal valore booleano <quote>vero</quote> per un hook interno. Se un hook interno solleva un'eccezione, l'hook si considera fallito.</para>
172 <para id="x_226">Per un hook che controlla se un'attività può procedere, zero o falso significano <quote>concesso</quote>, mentre un numero diverso da zero, vero, o un'eccezione significano <quote>negato</quote>.</para>
173 </sect2>
175 <sect2>
176 <title>Scrivere un hook esterno</title>
178 <para id="x_227">Quando definite un hook esterno nel vostro file <filename role="special">~/.hgrc</filename> e l'hook viene invocato, il suo valore viene passato alla vostra shell, che lo interpreta. Questo significa che potete usare i normali costrutti di shell nel corpo dell'hook.</para>
180 <para id="x_228">Un hook eseguibile viene sempre eseguito con la sua directory corrente impostata alla directory radice del repository.</para>
182 <para id="x_229">Ogni parametro di hook viene passato come una variabile d'ambiente con il nome in maiuscolo preceduto dalla stringa <quote><literal>HG_</literal></quote>.</para>
184 <para id="x_22a">Con l'eccezione dei parametri di hook, Mercurial non imposta o modifica alcuna variabile d'ambiente quando esegue un hook. Questo è utile da ricordare se state scrivendo un hook globale che potrebbe venire invocato da un certo numero di utenti differenti con differenti variabili d'ambiente impostate. In ambienti multi-utente, non dovreste fare affidamento sul fatto che le variabili d'ambiente abbiano i valori che avete impostato nel vostro ambiente di lavoro durante il collaudo dell'hook.</para>
185 </sect2>
187 <sect2>
188 <title>Dire a Mercurial di usare un hook interno</title>
190 <para id="x_22b">La sintassi del file <filename role="special">~/.hgrc</filename> per definire un hook interno è leggermente differente da quella per un hook eseguibile. Il valore dell'hook deve cominciare con il testo <quote><literal>python:</literal></quote> e proseguire con il nome completamente qualificato dell'oggetto invocabile da usare come valore dell'hook.</para>
192 <para id="x_22c">Il modulo in cui si trova l'hook viene automaticamente importato quando l'hook viene invocato. Purché il nome del modulo e il valore di <envar>PYTHONPATH</envar> siano corretti, l'importazione dovrebbe <quote>funzionare e basta</quote>.</para>
194 <para id="x_22d">Il seguente frammento di un file <filename role="special">~/.hgrc</filename> di esempio illustra la sintassi e il significato delle nozioni appena descritte.</para>
195 <programlisting>[hooks]
196 commit.esempio = python:miomodulo.sottomodulo.miohook</programlisting>
197 <para id="x_22e">Quando Mercurial esegue l'hook <literal>commit.esempio</literal>, importa <literal>miomodulo.sottomodulo</literal>, cerca l'oggetto invocabile chiamato <literal>miohook</literal> e lo invoca.</para>
198 </sect2>
200 <sect2>
201 <title>Implementare un hook interno</title>
203 <para id="x_22f">Il più semplice hook interno non fa nulla, ma illustra la forma base della API degli hook:</para>
204 <programlisting>def miohook(ui, repo, **kwargs):
205 pass</programlisting>
206 <para id="x_230">Il primo argomento di un hook Python è sempre un oggetto <literal role="py-mod-mercurial.ui">mercurial.ui.ui</literal>. Il secondo è un oggetto repository, al momento sempre un'istanza di <literal role="py-mod-mercurial.localrepo">mercurial.localrepo.localrepository</literal>. Gli altri argomenti con nome seguono questi due argomenti. Quali argomenti con nome vengono passati dipende dall'hook che viene invocato, ma un hook può ignorare gli argomenti di cui non ha bisogno depositandoli in un dizionario di argomenti con nome, come succede con <literal>**kwargs</literal> qui sopra.</para>
208 </sect2>
209 </sect1>
210 <sect1>
211 <title>Alcuni hook di esempio</title>
213 <sect2>
214 <title>Scrivere messaggi di commit significativi</title>
216 <para id="x_231">È difficile immaginare un messaggio di commit utile che sia anche molto breve. Il semplice hook <literal role="hook">pretxncommit</literal> dell'esempio seguente vi impedirà di esguire il commit di un changeset con un messaggio più piccolo di quindici byte.</para>
218 &interaction.hook.msglen.go;
219 </sect2>
221 <sect2>
222 <title>Controllare lo spazio bianco in coda</title>
224 <para id="x_232">Un uso interessante per un hook relativo ai commit è quello di aiutarvi a scrivere codice più pulito. Un semplice esempio di <quote>codice più pulito</quote> è la regola per cui un cambiamento non dovrebbe aggiungere nessuna nuova riga di testo contenente <quote>spazio bianco in coda</quote>. Lo spazio bianco in coda è composto da una serie di spazi e caratteri di tabulazione alla fine di una riga di testo. Nella maggior parte dei casi, lo spazio bianco in coda non è altro che rumore invisibile e superfluo, ma si rivela occasionalmente problematico e in genere le persone preferiscono sbarazzarsene.</para>
226 <para id="x_233">Potete usare l'hook <literal role="hook">precommit</literal> o l'hook <literal role="hook">pretxncommit</literal> per scoprire se avete un problema di spazio bianco in coda. Se usate <literal role="hook">precommit</literal>, l'hook non saprà quali file state inserendo, quindi dovrà controllare ogni file modificato nel repository alla ricerca di spazio bianco in coda. Se volete inserire un cambiamento al solo file <filename>foo</filename>, ma il flie <filename>bar</filename> contiene spazio bianco in coda, effettuare un controllo tramite l'hook <literal role="hook">precommit</literal> vi impedirà di eseguire il commit di <filename>foo</filename> a causa dei problemi con <filename>bar</filename>. Questo comportamento non sembra corretto.</para>
228 <para id="x_234">Se doveste scegliere l'hook <literal role="hook">pretxncommit</literal>, il controllo non avverrà fino al momento appena precedente il completamento della transazione di commit. Questo vi consentirà di controllare il problema solo sui file che verranno registrati. Tuttavia, se avete inserito il messaggio di commit interattivamente e l'hook fallisce, la transazione verrà abortita e dovrete riscrivere il messaggio di commit dopo aver corretto lo spazio bianco in coda e invocato ancora <command role="hg-cmd">hg commit</command>.</para>
230 &interaction.ch09-hook.ws.simple;
232 <para id="x_235">In questo esempio, abbiamo introdotto un semplice hook <literal role="hook">pretxncommit</literal> che controlla lo spazio bianco in coda. Questo hook è breve, ma non molto utile: termina con uno stato di errore se un changeset aggiunge una riga con spazio bianco in coda a un file qualsiasi, ma non stampa alcuna informazione che potrebbe aiutarci a individuare il file o la riga che contiene il problema. L'hook ha anche la piacevole proprietà di non prestare attenzione alle righe non modificate, in quanto solo le righe che introducono nuovo spazio bianco in coda causano problemi.</para>
234 &ch09-check_whitespace.py.lst;
236 <para id="x_236">Questa versione è molto più complessa, ma anche molto più utile. Analizza un diff unificato per vedere se una qualsiasi riga aggiunge spazio bianco in coda e stampa il nome del file e il numero della riga di ogni occorrenza di questo tipo. Anche meglio, se il cambiamento aggiunge spazio bianco in coda, questo hook salva il messaggio di commit e stampa il nome del file salvato prima di uscire e dire a Mercurial di abortire la transazione, in modo che possiate usare l'opzione <option role="hg-opt-commit">-l nomefile</option> del comando <command role="hg-cmd">hg commit</command> per riutilizzare il messaggio di commit salvato una volta che avete corretto il problema.</para>
238 &interaction.ch09-hook.ws.better;
240 <para id="x_237">Come ultima nota a margine, osservate in questo esempio l'uso della funzione di modifica sul posto di <command>sed</command> per eliminare lo spazio bianco in coda da un file. Questo impiego è sufficientemente conciso e utile che lo riprodurrò qui di seguito (usando <command>perl</command> per sicurezza).</para>
241 <programlisting>perl -pi -e 's,\s+$,,' nomefile</programlisting>
243 </sect2>
244 </sect1>
245 <sect1>
246 <title>Hook inclusi</title>
248 <para id="x_238">Mercurial viene distribuito con diversi hook inclusi che potete trovare nella directory <filename class="directory">hgext</filename> dell'albero dei sorgenti di Mercurial. Se state usando un pacchetto precompilato di Mercurial, gli hook si trovano nella directory <filename class="directory">hgext</filename> posizionata ovunque il vostro pacchetto abbia installato Mercurial.</para>
250 <sect2>
251 <title><literal role="hg-ext">acl</literal>&emdash;controllo di accesso per parti di un repository</title>
253 <para id="x_239">L'estensione <literal role="hg-ext">acl</literal> vi permette di controllare quali utenti remoti hanno il permesso di trasmettere changeset verso un server attraverso la rete. Potete proteggere qualsiasi porzione di un repository (compreso l'intero repository) in modo che uno specifico utente remoto possa trasmettere solo cambiamenti che non influenzano le parti protette.</para>
255 <para id="x_23a">Questa estensione implementa il controllo di accesso sulla base dell'identità dell'utente che effettua la trasmissione, <emphasis>non</emphasis> di chi ha eseguito il commit dei changeset che vengono trasferiti. Ha senso usare questo hook solo se avete un ambiente server protetto che autentica gli utenti remoti e volete essere sicuri che solo specifici utenti possano trasmettere cambiamenti a quel server.</para>
257 <sect3>
258 <title>Configurare l'hook <literal role="hook">acl</literal></title>
260 <para id="x_23b">Per gestire i cambiamenti in entrata, l'hook <literal role="hg-ext">acl</literal> deve essere usato come un hook <literal role="hook">pretxnchangegroup</literal>. Questo vi permette di vedere quali file vengono modificati da ogni changeset in entrata e di abortire un gruppo di changeset se modifica qualche file <quote>proibito</quote>. Ecco un esempio di come attivare l'hook:</para>
261 <programlisting>[hooks]
262 pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
264 <para id="x_23c">L'estensione <literal role="hg-ext">acl</literal> si configura usando tre sezioni.</para>
266 <para id="x_23d">La sezione <literal role="rc-acl">acl</literal> contiene solo la voce <envar role="rc-item-acl">sources</envar>, che elenca le modalità di provenienza dei cambiamenti in entrata a cui l'hook deve fare attenzione. Di solito, non avrete bisogno di configurare questa sezione.</para>
267 <itemizedlist>
268 <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: controlla i changeset in entrata che arrivano da un repository remoto via HTTP o ssh. Questo è il valore predefinito di <envar role="rc-item-acl">sources</envar> e di solito è l'unica impostazione di cui avrete bisogno per questo elemento di configurazione.</para>
269 </listitem>
270 <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: controlla i changeset in entrata che arrivano attraverso un'estrazione da un repository locale.</para>
271 </listitem>
272 <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: controlla i cambiamenti in entrata che arrivano attraverso una trasmissione da un repository locale.</para>
273 </listitem>
274 <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: controlla i changeset in entrata che arrivano da un altro repository attraverso un bundle.<footnote><para id="x_fff">FIXME Cos'è un bundle?</para></footnote></para>
275 </listitem></itemizedlist>
277 <para id="x_242">La sezione <literal role="rc-acl.allow">acl.allow</literal> controlla gli utenti a cui è permesso aggiungere changeset al repository. Se questa sezione non è presente, il permesso viene concesso a tutti gli utenti a cui non viene esplicitamente negato. Se questa sezione è presente, il permesso viene negato a tutti gli utenti a cui non viene esplicitamente concesso (quindi una sezione vuota significa che il permesso viene negato a tutti gli utenti).</para>
279 <para id="x_243">La sezione <literal role="rc-acl.deny">acl.deny</literal> determina quali sono gli utenti a cui viene impedito di aggiungere changeset al repository. Se questa sezione non è presente o è vuota, tutti gli utenti hanno il permesso di aggiungere modifiche.</para>
281 <para id="x_244">La sintassi per le sezioni <literal role="rc-acl.allow">acl.allow</literal> e <literal role="rc-acl.deny">acl.deny</literal> è la stessa. Sulla sinistra di ogni voce si trova un pattern di tipo glob che corrisponde a file e directory relativi alla radice del repository, sulla destra si trova un nome utente.</para>
283 <para id="x_245">Nell'esempio seguente, l'utente <literal>manualista</literal> può trasmettere cambiamenti solo al sottoalbero <filename class="directory">doc</filename> del repository, mentre l'utente <literal>stagista</literal> può trasmettere cambiamenti a qualsiasi file o directory tranne <filename class="directory">sorgenti/sensibili</filename>.
284 </para>
285 <programlisting>[acl.allow]
286 doc/** = manualista
287 [acl.deny]
288 sorgenti/sensibili/** = stagista</programlisting>
290 </sect3>
291 <sect3>
292 <title>Collaudo e risoluzione dei problemi</title>
294 <para id="x_246">Se volete collaudare l'hook <literal role="hg-ext">acl</literal>, eseguitelo abilitando le informazioni di debug di Mercurial. Dato che probabilmente lo eseguirete su un server dove non è conveniente (e talvolta nemmeno possibile) passare l'opzione <option role="hg-opt-global">--debug</option>, non dimenticatevi che potete abilitare le informazioni di debug nel vostro file <filename role="special">~/.hgrc</filename>:
295 </para>
296 <programlisting>[ui]
297 debug = true</programlisting>
298 <para id="x_247">Con questa opzione abilitata, l'hook <literal role="hg-ext">acl</literal> stamperà abbastanza informazioni da permettervi di capire perché sta consentendo o vietando le trasmissioni da specifici utenti.</para>
300 </sect3>
301 </sect2>
303 <sect2>
304 <title><literal
305 role="hg-ext">bugzilla</literal>&emdash;integrazione con Bugzilla</title>
307 <para id="x_248">L'estensione <literal role="hg-ext">bugzilla</literal> aggiunge un commento a un bug su Bugzilla ogni volta che trova un riferimento all'identificatore di quel bug in un messaggio di commit. Potete installare questo hook su un server condiviso, in modo che l'hook venga eseguito ogni volta che un utente remoto trasmette i cambiamenti a quel server.</para>
309 <para id="x_249">L'hook aggiunge al bug un commento che somiglia a questo (potete configurare i contenuti del commento, come vedrete fra un attimo):</para>
310 <programlisting>Changeset aad8b264143a, creato da Mario Rossi
311 <mario.rossi@example.com> nel repository vattelapesca,
312 fa riferimento a questo bug.
313 Per i dettagli completi, si veda
314 http://hg.example.com/vattelapesca?cmd=changeset;node=aad8b264143a
315 Descrizione del changeset: risolto bug 10483 proteggendo il codice da alcuni
316 puntatori NULL.</programlisting>
317 <para id="x_24a">Il valore di questo hook è che automatizza il processo di aggiornamento di un bug ogni volta che un changeset vi fa riferimento. Se lo configurate in maniera adeguata, l'hook faciliterà la navigazione diretta da un bug su Bugzilla a un changeset che si riferisce a quel bug.</para>
319 <para id="x_24b">Potete usare il codice di questo hook come un punto di partenza per ricette più esotiche di integrazione con Bugzilla. Ecco alcune possibilità.</para>
320 <itemizedlist>
321 <listitem><para id="x_24c">Richiedere che ogni changeset trasmesso al server abbia un identificatore di bug valido nel proprio messaggio di commit. In questo caso, vorrete configurare l'hook come un hook <literal role="hook">pretxncommit</literal> per consentirgli di rifiutare i cambiamenti che non contengono identificatori di bug.</para>
322 </listitem>
323 <listitem><para id="x_24d">Permettere ai changeset in entrata di modificare automaticamente lo <emphasis>stato</emphasis> di un bug, come pure di aggiungere semplicemente un commento. Per esempio, l'hook potrebbe riconoscere la stringa <quote>risolto bug 31337</quote> come il segnale che indica la necessità di aggiornare lo stato del bug 31337 a <quote>richiede un collaudo</quote>.</para>
324 </listitem></itemizedlist>
326 <sect3 id="sec:hook:bugzilla:config">
327 <title>Configurare l'hook <literal role="hook">bugzilla</literal></title>
329 <para id="x_24e">Dovreste configurare questo hook nel file <filename role="special">~/.hgrc</filename> del vostro server come un hook <literal role="hook">incoming</literal>, per esempio nel modo seguente:</para>
330 <programlisting>[hooks]
331 incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
333 <para id="x_24f">A causa della natura specializzata dell'hook e dato che Bugzilla non è stato implementato con questo tipo di integrazioni in mente, configurare questo hook è un processo piuttosto complicato.</para>
335 <para id="x_250">Prima di cominciare, dovete installare la libreria di interfaccia Python per MySQL sulla macchina (o le macchine) dove intendete eseguire l'hook. Se non è disponibile sotto forma di pacchetto precompilato per il vostro sistema, potete scaricarla da <citation>web:mysql-python</citation>.
336 </para>
338 <para id="x_251">Le informazioni di configurazione per questo hook si trovano nella sezione <literal role="rc-bugzilla">bugzilla</literal> del vostro file <filename role="special">~/.hgrc</filename>.
339 </para>
340 <itemizedlist>
341 <listitem><para id="x_252"><envar role="rc-item-bugzilla">version</envar>: la versione di Bugzilla installata sul server. Lo schema di database usato da Bugzilla cambia occasionalmente, quindi questo hook deve sapere esattamente quale schema usare.</para>
342 </listitem>
343 <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: il nome della macchina del server MySQL che memorizza i vostri dati per Bugzilla. Il database deve essere configurato per consentire le connessioni da qualunque macchina stia eseguendo l'hook <literal role="hook">bugzilla</literal>.
344 </para>
345 </listitem>
346 <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: il nome utente con il quale connettersi al server MySQL. Il database deve essere configurato per consentire a questo utente di connettersi da qualunque macchina stia eseguendo l'hook <literal role="hook">bugzilla</literal>. Questo utente deve essere in grado di modificare le tabelle di Bugzilla. Il valore predefinito di questo elemento è <literal>bugs</literal>, che è il nome standard dell'utente Bugzilla in un database MySQL.</para>
347 </listitem>
348 <listitem><para id="x_255"><envar role="rc-item-bugzilla">password</envar>: la password MySQL per l'utente che avete configurato alla voce precedente. Il testo della password viene memorizzato in chiaro, quindi dovreste assicurarvi che utenti non autorizzati non possano leggere il file <filename role="special">~/.hgrc</filename> dove avete inserito questa informazione.</para>
349 </listitem>
350 <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: il nome del database Bugzilla sul server MySQL. Il valore predefinito di questo elemento è <literal>bugs</literal>, che è il nome standard del database MySQL dove Bugzilla memorizza i propri dati.</para>
351 </listitem>
352 <listitem><para id="x_257"><envar role="rc-item-bugzilla">notify</envar>: se volete che Bugzilla spedisca un'email di notifica agli interessati dopo che questo hook ha aggiunto un commento a un bug, avrete bisogno che questo hook esegua un comando ogni volta che aggiorna il database. Il comando da eseguire dipende da dove avete installato Bugzilla, ma tipicamente somiglierà al seguente, se avete installato Bugzilla in <filename class="directory">/var/www/html/bugzilla</filename>:</para>
353 <programlisting>cd /var/www/html/bugzilla &&
354 ./processmail %s nessuno@example.com</programlisting>
355 <para id="x_258">Il programma <literal>processmail</literal> di Bugzilla si aspetta che gli vengano passati un identificatore di bug (l'hook sostituisce <quote><literal>%s</literal></quote> con l'identificatore di bug) e un indirizzo email. Si aspetta anche di essere in grado di scrivere su alcuni file nella directory in cui viene eseguito. Se Bugzilla e questo hook non sono installati sulla stessa macchina, dovrete trovare un modo per eseguire <literal>processmail</literal> sul server dove Bugzilla è installato.</para>
356 </listitem></itemizedlist>
358 </sect3>
359 <sect3>
360 <title>Correlare i nomi utente Mercurial ai nomi utente Bugzilla</title>
362 <para id="x_259">Di default, l'hook <literal role="hg-ext">bugzilla</literal> prova a utilizzare l'indirizzo email di chi ha eseguito il commit del changeset come il nome utente Bugzilla con cui aggiornare un bug. Se questa impostazione non vi soddisfa, potete correlare gli indirizzi email degli utenti Mercurial ai nomi utente Bugzilla tramite una sezione <literal role="rc-usermap">usermap</literal>.</para>
364 <para id="x_25a">Ogni elemento nella sezione <literal role="rc-usermap">usermap</literal> contiene un indirizzo email sulla sinistra e un nome utente Bugzilla sulla destra.</para>
365 <programlisting>[usermap]
366 maria.bianchi@example.com = maria</programlisting>
367 <para id="x_25b">Potete tenere i dati della sezione <literal role="rc-usermap">usermap</literal> in un normale file <filename role="special">~/.hgrc</filename>, oppure dire all'hook <literal role="hg-ext">bugzilla</literal> di leggere le informazioni da un file <filename>usermap</filename> esterno. In quest'ultimo caso, potete memorizzare i dati del file <filename>usermap</filename> separatamente in un repository modificabile dall'utente, per esempio. Questo vi permette di dare ai vostri utenti la possibilità di mantenere le proprie voci nella sezione <envar role="rc-item-bugzilla">usermap</envar>. Il file <filename role="special">~/.hgrc</filename> principale potrebbe somigliare a questo:</para>
368 <programlisting># il normale file hgrc fa riferimento a un file di correlazioni esterno
369 [bugzilla]
370 usermap = /home/hg/repos/datiutente/bugzilla-usermap.conf</programlisting>
371 <para id="x_25c">Mentre il file <filename>usermap</filename> a cui fa riferimento potrebbe somigliare a questo:</para>
372 <programlisting># bugzilla-usermap.conf - all'interno di un repository Mercurial
373 [usermap]
374 stefania@example.com = stef</programlisting>
376 </sect3>
377 <sect3>
378 <title>Configurare il testo che viene aggiunto a un bug</title>
380 <para id="x_25d">Potete configurare il testo che questo hook aggiunge come commento specificandolo sotto forma di template Mercurial. Diverse voci del file <filename role="special">~/.hgrc</filename> (sempre nella sezione <literal role="rc-bugzilla">bugzilla</literal>) controllano questo comportamento.</para>
381 <itemizedlist>
382 <listitem><para id="x_25e"><literal>strip</literal>: il numero di parti iniziali da eliminare dal percorso di un repository per costruire un percorso parziale da usare in un URL. Per esempio, se i repository sul vostro server si trovano nella directory <filename class="directory">/home/hg/repos</filename>, e voi avete un repository il cui percorso è <filename class="directory">/home/hg/repos/app/test</filename>, allora impostando <literal>strip</literal> a <literal>4</literal> otterrete il percorso parziale <filename class="directory">app/test</filename>. L'hook renderà disponibile questo percorso parziale con il nome <literal>webroot</literal> durante l'espansione di un template.</para>
383 </listitem>
384 <listitem><para id="x_25f"><literal>template</literal>: il testo del template da usare. In aggiunta alle solite variabili relative ai changeset, questo template può usare <literal>hgweb</literal> (il valore dell'elemento di configurazione <literal>hgweb</literal> menzionato in precedenza) e <literal>webroot</literal> (il percorso costruito usando l'elemento <literal>strip</literal> appena descritto).</para>
385 </listitem></itemizedlist>
387 <para id="x_260">In più, potete aggiungere un elemento <envar role="rc-item-web">baseurl</envar> alla sezione <literal role="rc-web">web</literal> del vostro file <filename role="special">~/.hgrc</filename>. L'hook <literal role="hg-ext">bugzilla</literal> lo renderà disponibile durante l'espansione di un template, come la stringa di base da usare nel costruire un URL che permetterà agli utenti di navigare da un commento Bugzilla verso un changeset correlato. Ecco un esempio di come usare questo elemento:</para>
388 <programlisting>[web]
389 baseurl = http://hg.example.com/</programlisting>
391 <para id="x_261">Ecco un esempio dell'insieme di informazioni di configurazione da usare per l'hook <literal role="hg-ext">bugzilla</literal>.</para>
393 &ch10-bugzilla-config.lst;
395 </sect3>
396 <sect3>
397 <title>Collaudo e risoluzione dei problemi</title>
399 <para id="x_262">I problemi più comuni con la configurazione dell'hook <literal role="hg-ext">bugzilla</literal> sono relativi all'esecuzione dello script <filename>processmail</filename> di Bugzilla e alla correlazione tra nomi utente Mercurial e nomi utente Bugzilla.</para>
401 <para id="x_263">Se ricordate quanto detto nella <xref linkend="sec:hook:bugzilla:config"/>, l'utente che esegue il processo Mercurial sul server è anche quello che eseguirà lo script <filename>processmail</filename>. Questo script talvolta chiederà a Bugzilla di modificare i file nella sua directory di configurazione, e di solito i file di configurazione di Bugzilla sono proprietà dell'utente che esegue il processo del vostro server web.</para>
403 <para id="x_264">Potete far eseguire <filename>processmail</filename> con un'identità utente appropriata tramite il comando <command>sudo</command>. Ecco una voce di esempio da un file <filename>sudoers</filename>.</para>
404 <programlisting>hg_user = (httpd_user)
405 NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
406 <para id="x_265">Questo consente all'utente <literal>hg_user</literal> di eseguire il programma <filename>processmail-wrapper</filename> sotto l'identità dell'utente <literal>httpd_user</literal>.</para>
408 <para id="x_266">Questa invocazione indiretta attraverso uno script che funge da involucro è necessaria, perché <filename>processmail</filename> si aspetta di venire eseguito con la propria directory corrente impostata al percorso di installazione di Bugzilla, ma non è possibile specificare questo vincolo in un file <filename>sudoers</filename>. Il contenuto dello script involucro è semplice:</para>
409 <programlisting>#!/bin/sh
410 cd `dirname $0` && ./processmail "$1" nessuno@example.com</programlisting>
411 <para id="x_267">Non sembra che l'indirizzo email passato a <filename>processmail</filename> abbia importanza.</para>
413 <para id="x_268">Se la vostra sezione <literal role="rc-usermap">usermap</literal> non è impostata correttamente, gli utenti vedranno un messaggio di errore stampato dall'hook <literal role="hg-ext">bugzilla</literal> al momento di trasmettere i cambiamenti al server. Il messaggio di errore somiglierà al seguente:</para>
414 <programlisting>impossibile trovare un nome utente bugzilla per mario.rossi@example.com</programlisting>
415 <para id="x_269">Questo significa che l'indirizzo email dell'utente Mercurial, <literal>mario.rossi@example.com</literal>, non è un nome utente Bugzilla valido, né possiede una voce nella vostra sezione <literal role="rc-usermap">usermap</literal> che lo metta in relazione con un nome utente Bugzilla valido.</para>
417 </sect3>
418 </sect2>
420 <sect2>
421 <title><literal role="hg-ext">notify</literal>&emdash;inviare notifiche via email</title>
423 <para id="x_26a">Sebbene il server web predefinito di Mercurial fornisca i feed RSS dei cambiamenti per ogni repository, molte persone preferiscono ricevere le notifiche dei cambiamenti via email. L'hook <literal role="hg-ext">notify</literal> vi permette di inviare notifiche a un insieme di indirizzi email ogni volta che arrivano changeset a cui quelle persone sono interessate.</para>
425 <para id="x_26b">Come l'hook <literal role="hg-ext">bugzilla</literal>, anche l'hook <literal role="hg-ext">notify</literal> è guidato da un template, in modo che possiate personalizzare il contenuto dei messaggi di notifica inviati.</para>
427 <para id="x_26c">Di default, l'hook <literal role="hg-ext">notify</literal> include un diff di ogni changeset che spedisce, ma potete limitare le dimensioni del diff oppure disattivarlo interamente. L'inclusione del diff è utile per consentire agli interessati di revisionare i cambiamenti immediatamente piuttosto che obbligarli a cliccare per seguire un URL.</para>
429 <sect3>
430 <title>Configurare l'hook <literal role="hg-ext">notify</literal></title>
432 <para id="x_26d">Potete impostare l'hook <literal role="hg-ext">notify</literal> in modo che spedisca un messaggio email per ogni changeset in entrata, o uno per ogni gruppo di changeset in entrata (tutti quelli che sono arrivati in una singola estrazione o trasmissione).</para>
433 <programlisting>[hooks]
434 # spedisci un'email per gruppo di cambiamenti
435 changegroup.notify = python:hgext.notify.hook
436 # spedisci un'email per cambiamento
437 incoming.notify = python:hgext.notify.hook</programlisting>
439 <para id="x_26e">Le informazioni di configurazione per questo hook si trovano nella sezione <literal role="rc-notify">notify</literal> del file <filename role="special">~/.hgrc</filename>.</para>
440 <itemizedlist>
441 <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: di default, questo hook non spedisce alcuna email, ma stampa il messaggio che <emphasis>avrebbe</emphasis> inviato. Impostate questo elemento a <literal>false</literal> per consentire la spedizione delle email. La ragione per cui la spedizione delle email è disabilitata di default è che ci vogliono diverse prove per configurare questa estensione esattamente come vorreste, e non starebbe bene infastidire gli interessati con un certo numero di notifiche <quote>guaste</quote> mentre correggete la vostra configurazione.</para>
442 </listitem>
443 <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: il percorso di un file di configurazione che contiene le informazioni di iscrizione. Questo viene tenuto separato dal file <filename role="special">~/.hgrc</filename> principale in modo che possiate mantenerlo in un proprio repository. Le persone possono poi clonare quel repository, aggiornare le proprie iscrizioni e trasmettere i cambiamenti al vostro server.</para>
444 </listitem>
445 <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: il numero di parti iniziali da eliminare dal percorso di un repository quando state decidendo se è possibile iscriversi al servizio di notifica per un repository. Per esempio, se i repository sul vostro server si trovano in <filename class="directory">/home/hg/repos</filename>, e <literal role="hg-ext">notify</literal> sta considerando un repository chiamato <filename class="directory">/home/hg/repos/condivisi/test</filename>, impostare <envar role="rc-item-notify">strip</envar> a <literal>4</literal> farà in modo che <literal role="hg-ext">notify</literal> restringa il percorso da considerare a <filename class="directory">condivisi/test</filename> e associ le iscrizioni a questo percorso.</para>
446 </listitem>
447 <listitem><para id="x_272"><envar role="rc-item-notify">template</envar>: il testo del template da usare per inviare i messaggi. Questo specifica i contenuti sia delle intestazioni che del corpo del messaggio.</para>
448 </listitem>
449 <listitem><para id="x_273"><envar role="rc-item-notify">maxdiff</envar>: il massimo numero di righe di dati di diff da aggiungere alla fine di un messaggio. Se un diff è più lungo di questo limite, viene troncato. Di default, questo valore è impostato a 300. Impostate questo valore a <literal>0</literal> per omettere i diff dalle email di notifica.</para>
450 </listitem>
451 <listitem><para id="x_274"><envar role="rc-item-notify">sources</envar>: una lista di modalità di provenienza dei changeset da considerare. Questo vi permette di limitare <literal role="hg-ext">notify</literal> in modo che spedisca email riguardanti solo utenti remoti che hanno trasmesso modifiche a questo repository attraverso un server, per esempio. Leggete la <xref linkend="sec:hook:sources"/> per sapere quali modalità potete specificare qui.</para>
452 </listitem></itemizedlist>
454 <para id="x_275">Se impostate l'elemento <envar role="rc-item-web">baseurl</envar> nella sezione <literal role="rc-web">web</literal>, potete usarlo in un template, dove sarà disponibile con il nome <literal>webroot</literal>.</para>
456 <para id="x_276">Ecco un esempio dell'insieme di informazioni di configurazione da usare per l'hook <literal role="hg-ext">notify</literal>.</para>
458 &ch10-notify-config.lst;
460 <para id="x_277">Questo produrrà un messaggio che somiglierà al seguente:</para>
462 &ch10-notify-config-mail.lst;
464 </sect3>
465 <sect3>
466 <title>Collaudo e risoluzione dei problemi</title>
468 <para id="x_278">Non dimenticate che il comportamento predefinito dell'estensione <literal role="hg-ext">notify</literal> è quello di <emphasis>non spedire alcuna mail</emphasis> fino a quando non lo avete esplicitamente configurato per farlo, impostando <envar role="rc-item-notify">test</envar> a <literal>false</literal>. Fino a quel momento, si limiterà a stampare il messaggio che <emphasis>avrebbe</emphasis> inviato.</para>
470 </sect3>
471 </sect2>
472 </sect1>
473 <sect1 id="sec:hook:ref">
474 <title>Informazioni per gli implementatori di hook</title>
476 <sect2>
477 <title>Esecuzione degli hook interni</title>
479 <para id="x_279">Un hook interno viene invocato con argomenti della forma seguente:</para>
480 <programlisting>def miohook(ui, repo, **kwargs):
481 pass</programlisting>
482 <para id="x_27a">Il parametro <literal>ui</literal> è un oggetto di tipo <literal role="py-mod-mercurial.ui">mercurial.ui.ui</literal>. Il parametro <literal>repo</literal> è un oggetto di tipo <literal role="py-mod-mercurial.localrepo">mercurial.localrepo.localrepository</literal>. I nomi e i valori dei parametri <literal>**kwargs</literal> dipendono dall'hook coinvolto, ma hanno le seguenti caratteristiche comuni:</para>
483 <itemizedlist>
484 <listitem><para id="x_27b">Se un parametro si chiama <literal>node</literal> o <literal>parentN</literal>, conterrà un identificatore esadecimale di changeset. La stringa vuota viene usata per rappresentare l'identificatore di changeset <quote>nullo</quote> invece di una stringa di zeri.</para>
485 </listitem>
486 <listitem><para id="x_27c">Se un parametro si chiama <literal>url</literal>, conterrà l'URL di un repository remoto, nel caso possa essere determinato.</para>
487 </listitem>
488 <listitem><para id="x_27d">I parametri con valore booleano vengono rappresentati come oggetti Python di tipo <literal>bool</literal>.</para>
489 </listitem></itemizedlist>
491 <para id="x_27e">Un hook interno viene invocato senza cambiare la directory di lavoro del processo (a differenza degli hook esterni, che vengono eseguiti nella radice del repository). L'hook non deve mai cambiare questa directory, altrimenti causerà il fallimento di tutte le proprie invocazioni alla API di Mercurial.</para>
493 <para id="x_27f">Se un hook restituisce il valore booleano <quote>falso</quote>, si considera terminato con successo. Se restituisce il valore booleano <quote>vero</quote> oppure solleva un'eccezione, si considera fallito. Un modo utile di pensare a questa convenzione di esecuzione è <quote>dimmi se hai fallito</quote>.</para>
495 <para id="x_280">Notate che gli identificatori di changeset vengono passati agli hook Python sotto forma di stringhe esadecimali, non degli hash binari che la API Mercurial usa normalmente. Per convertire un hash da esadecimale a binario, usate la funzione <literal>mercurial.node.bin</literal>.
496 </para>
497 </sect2>
499 <sect2>
500 <title>Esecuzione degli hook esterni</title>
502 <para id="x_281">Un hook esterno viene passato alla shell dell'utente che sta eseguendo Mercurial e può disporre delle funzionalità di quella shell, come la sostituzione delle variabili e la redirezione dei comandi. L'hook viene eseguito nella directory radice del repository (a differenza degli hook interni, che vengono eseguiti nella stessa directory in cui è stato eseguito Mercurial).</para>
504 <para id="x_282">I parametri di hook sono passati all'hook sotto forma di variabili d'ambiente. Il nome di ogni variabile d'ambiente viene convertito in maiuscolo e fatto precedere dalla stringa <quote><literal>HG_</literal></quote>. Per esempio, se il nome di un parametro è <quote><literal>node</literal></quote>, il nome della variabile d'ambiente che rappresenta quel parametro sarà <quote><literal>HG_NODE</literal></quote>.</para>
506 <para id="x_283">Un parametro booleano è rappresentato come la stringa <quote><literal>1</literal></quote> se è <quote>vero</quote> o <quote><literal>0</literal></quote> se è <quote>falso</quote>. Se una variabile d'ambiente è chiamata <envar>HG_NODE</envar>, <envar>HG_PARENT1</envar>, o <envar>HG_PARENT2</envar>, conterrà un identificatore di changeset rappresentato come una stringa esadecimale. La stringa vuota viene usata per rappresentare l'identificatore di changeset <quote>nullo</quote> invece di una stringa di zeri. Se una variabile d'ambiente è chiamata <envar>HG_URL</envar>, conterrà l'URL di un repository remoto, nel caso possa essere determinato.</para>
508 <para id="x_284">Se un hook termina con uno stato uguale a zero, si considera terminato con successo. Se termina con uno stato diverso da zero, si considera fallito.</para>
509 </sect2>
511 <sect2>
512 <title>Scoprire da dove vengono i changeset</title>
514 <para id="x_285">Un hook che coinvolge il trasferimento di changeset tra un repository locale e un altro potrebbe essere in grado di trovare informazioni sul <quote>lato opposto</quote>. Mercurial conosce il <emphasis>modo</emphasis> in cui i cambiamenti vengono trasferiti e in molti casi conosce anche l'ubicazione del <emphasis>luogo</emphasis> da cui o verso cui vengono trasferiti.</para>
516 <sect3 id="sec:hook:sources">
517 <title>Le fonti dei changeset</title>
519 <para id="x_286">Mercurial dirà a un hook quali sono, o sono stati, i mezzi usati per trasferire i changeset tra repository, fornendo questa informazione in un parametro Python chiamato <literal>source</literal> o in una variabile d'ambiente chiamata <envar>HG_SOURCE</envar>.</para>
521 <itemizedlist>
522 <listitem><para id="x_287"><literal>serve</literal>: i changeset sono trasferiti da o verso un repository remoto via HTTP o ssh.</para>
523 </listitem>
524 <listitem><para id="x_288"><literal>pull</literal>: i changeset sono trasferiti attraverso un'estrazione da un repository a un altro.</para>
525 </listitem>
526 <listitem><para id="x_289"><literal>push</literal>: i changeset sono trasferiti attraverso una trasmissione da un repository a un altro.</para>
527 </listitem>
528 <listitem><para id="x_28a"><literal>bundle</literal>: i changeset sono trasferiti da o verso un bundle.</para>
529 </listitem></itemizedlist>
530 </sect3>
532 <sect3 id="sec:hook:url">
533 <title>La destinazione dei cambiamenti&emdash;gli URL dei repository remoti</title>
535 <para id="x_28b">Quando è possibile, Mercurial dirà a un hook l'ubicazione del <quote>lato opposto</quote> di un'attività che trasferisce i dati dei changeset tra repository, fornendo questa informazione in un parametro Python chiamato <literal>url</literal> o in una variabile d'ambiente chiamata <envar>HG_URL</envar>.</para>
537 <para id="x_28c">Questa informazione non è sempre nota. Se un hook viene invocato in un repository condiviso via HTTP o ssh, Mercurial non è in grado di dire dove si trova il repository, ma potrebbe sapere da dove si sta connettendo il client. In questi casi, l'URL prenderà una delle seguenti forme:</para>
538 <itemizedlist>
539 <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;client ssh remoto, all'indirizzo IP <literal>1.2.3.4</literal>.</para>
540 </listitem>
541 <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;client HTTP remoto, all'indirizzo IP <literal>1.2.3.4</literal>. Se il client sta usando SSL, questo URL sarà nella forma <literal>remote:https:1.2.3.4</literal>.</para>
542 </listitem>
543 <listitem><para id="x_28f">Vuoto&emdash;Mercurial non è riuscito a scoprire nessuna informazione sul client remoto.</para>
544 </listitem></itemizedlist>
545 </sect3>
546 </sect2>
547 </sect1>
548 <sect1>
549 <title>Guida di riferimento agli hook</title>
551 <sect2 id="sec:hook:changegroup">
552 <title><literal role="hook">changegroup</literal>&emdash;dopo l'aggiunta di changeset remoti</title>
554 <para id="x_290">Questo hook viene eseguito dopo che un gruppo di changeset preesistenti è stato aggiunto al repository, per esempio tramite <command role="hg-cmd">hg pull</command> o <command role="hg-cmd">hg unbundle</command>. Questo hook viene eseguito una volta per ogni operazione che aggiunge uno o più changeset, a differenza dell'hook <literal role="hook">incoming</literal>, che viene eseguito una volta per ogni changeset a prescindere dal fatto che il changeset sia arrivato in un gruppo.</para>
556 <para id="x_291">Alcuni possibili usi di questo hook includono l'avvio di un assemblaggio o di un collaudo automatico dei changeset aggiunti, l'aggiornamento di un database di bug, o la notifica che un repository contiene nuovi cambiamenti.</para>
558 <para id="x_292">I parametri di questo hook sono i seguenti.</para>
559 <itemizedlist>
560 <listitem><para id="x_293"><literal>node</literal>: un identificatore di changeset. L'identificatore del primo changeset nel gruppo che è stato aggiunto. Tutti i changeset tra questo e <literal role="tag">tip</literal> compresi sono stati aggiunti da una singola invocazione di <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command>, o <command role="hg-cmd">hg unbundle</command>.</para>
561 </listitem>
562 <listitem><para id="x_294"><literal>source</literal>: una stringa. La fonte di questi cambiamenti. Si veda la <xref linkend="sec:hook:sources"/> per i dettagli.</para>
563 </listitem>
564 <listitem><para id="x_295"><literal>url</literal>: un URL. L'ubicazione del repository remoto, nel caso sia nota. Si veda la <xref linkend="sec:hook:url"/> per maggiori informazioni.</para>
565 </listitem></itemizedlist>
567 <para id="x_296">Si vedano anche gli hook <literal role="hook">incoming</literal> (<xref linkend="sec:hook:incoming"/>), <literal role="hook">prechangegroup</literal> (<xref linkend="sec:hook:prechangegroup"/>) e <literal role="hook">pretxnchangegroup</literal> (<xref linkend="sec:hook:pretxnchangegroup"/>).</para>
568 </sect2>
570 <sect2 id="sec:hook:commit">
571 <title><literal role="hook">commit</literal>&emdash;dopo la creazione di un nuovo changeset</title>
573 <para id="x_297">Questo hook viene eseguito dopo che un nuovo changeset è stato creato.</para>
575 <para id="x_298">I parametri di questo hook sono i seguenti.</para>
576 <itemizedlist>
577 <listitem><para id="x_299"><literal>node</literal>: un identificatore di changeset. L'identificatore del changeset appena inserito.</para>
578 </listitem>
579 <listitem><para id="x_29a"><literal>parent1</literal>: un identificatore di changeset. L'identificatore di changeset del primo genitore del changeset appena inserito.</para>
580 </listitem>
581 <listitem><para id="x_29b"><literal>parent2</literal>: un identificatore di changeset. L'identificatore di changeset del secondo genitore del changeset appena inserito.</para>
582 </listitem></itemizedlist>
584 <para id="x_29c">Si vedano anche gli hook <literal role="hook">precommit</literal> (<xref linkend="sec:hook:precommit"/>) e <literal role="hook">pretxncommit</literal> (<xref linkend="sec:hook:pretxncommit"/>).</para>
585 </sect2>
587 <sect2 id="sec:hook:incoming">
588 <title><literal role="hook">incoming</literal>&emdash;dopo l'aggiunta di un changeset remoto</title>
590 <para id="x_29d">Questo hook viene eseguito dopo che un changeset preesistente è stato aggiunto al repository, per esempio attraverso l'invocazione di <command role="hg-cmd">hg push</command>. Se un gruppo di changeset è stato aggiunto in una singola operazione, questo hook viene eseguito una volta per ogni changeset aggiunto.</para>
592 <para id="x_29e">Potete usare questo hook per gli stessi scopi dell'hook <literal role="hook">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>). A volte è semplicemente più comodo eseguire un hook per ogni gruppo di changeset, mentre altre volte è più conveniente eseguirlo per ogni changeset.</para>
594 <para id="x_29f">I parametri di questo hook sono i seguenti.</para>
595 <itemizedlist>
596 <listitem><para id="x_2a0"><literal>node</literal>: un identificatore di changeset. L'identificatore del changeset appena aggiunto.</para>
597 </listitem>
598 <listitem><para id="x_2a1"><literal>source</literal>: una stringa. La fonte di questi cambiamenti. Si veda la <xref linkend="sec:hook:sources"/> per i dettagli.</para>
599 </listitem>
600 <listitem><para id="x_2a2"><literal>url</literal>: un URL. L'ubicazione del repository remoto, nel caso sia nota. Si veda la <xref linkend="sec:hook:url"/> per maggiori informazioni.</para>
601 </listitem></itemizedlist>
603 <para id="x_2a3">Si vedano anche gli hook <literal role="hook">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>), <literal role="hook">prechangegroup</literal> (<xref linkend="sec:hook:prechangegroup"/>) e <literal role="hook">pretxnchangegroup</literal> (<xref linkend="sec:hook:pretxnchangegroup"/>).</para>
604 </sect2>
606 <sect2 id="sec:hook:outgoing">
607 <title><literal role="hook">outgoing</literal>&emdash;dopo la propagazione dei changeset</title>
609 <para id="x_2a4">Questo hook viene eseguito dopo che un gruppo di changeset è stato propagato al di fuori di questo repository, per esempio attraverso l'invocazione dei comandi <command role="hg-cmd">hg push</command> o <command role="hg-cmd">hg bundle</command>.</para>
611 <para id="x_2a5">Un possibile impiego di questo hook è quello di notificare gli amministratori di un repository che alcuni cambiamenti sono stati estratti.</para>
613 <para id="x_2a6">I parametri di questo hook sono i seguenti.</para>
614 <itemizedlist>
615 <listitem><para id="x_2a7"><literal>node</literal>: un identificatore di changeset. L'identificatore del primo changeset del gruppo che è stato propagato.</para>
616 </listitem>
617 <listitem><para id="x_2a8"><literal>source</literal>: una stringa. La fonte dell'operazione (si veda la <xref linkend="sec:hook:sources"/>). Se un client remoto ha estratto i cambiamenti da questo repository, il valore di <literal>source</literal> sarà <literal>serve</literal>. Se il client che ha ottenuto i cambiamenti di questo repository era locale, il valore di <literal>source</literal> sarà <literal>bundle</literal>, <literal>pull</literal>, o <literal>push</literal>, a seconda dell'operazione effettuata dal client.</para>
618 </listitem>
619 <listitem><para id="x_2a9"><literal>url</literal>: un URL. L'ubicazione del repository remoto, nel caso sia nota. Si veda la <xref linkend="sec:hook:url"/> per maggiori informazioni.</para>
620 </listitem></itemizedlist>
622 <para id="x_2aa">Si veda anche l'hook <literal role="hook">preoutgoing</literal> (<xref linkend="sec:hook:preoutgoing"/>).</para>
623 </sect2>
625 <sect2 id="sec:hook:prechangegroup">
626 <title><literal role="hook">prechangegroup</literal>&emdash;prima di cominciare ad aggiungere changeset remoti</title>
628 <para id="x_2ab">Questo hook di controllo viene eseguito prima che Mercurial cominci ad aggiungere un gruppo di changeset proveniente da un altro repository.</para>
630 <para id="x_2ac">Questo hook non possiede alcuna informazione sui changeset che verranno aggiunti, perché viene eseguito prima che la trasmissione di quei changeset possa cominciare. Se questo hook fallisce, i changeset non verranno trasmessi.</para>
632 <para id="x_2ad">Un possibile impiego di questo hook è quello di evitare che i cambiamenti vengano aggiunti a un repository. Per esempio, potreste usarlo per <quote>congelare</quote> temporaneamente o permanentemente un ramo ospitato su un server in modo che gli utenti non possano trasmettervi alcuna modifica, consentendo comunque a un amministratore locale di modificare il repository.</para>
634 <para id="x_2ae">I parametri di questo hook sono i seguenti.</para>
635 <itemizedlist>
636 <listitem><para id="x_2af"><literal>source</literal>: una stringa. La fonte di questi cambiamenti. Si veda la <xref linkend="sec:hook:sources"/> per i dettagli.</para>
637 </listitem>
638 <listitem><para id="x_2b0"><literal>url</literal>: un URL. L'ubicazione del repository remoto, nel caso sia nota. Si veda la <xref linkend="sec:hook:url"/> per maggiori informazioni.</para>
639 </listitem></itemizedlist>
641 <para id="x_2b1">Si vedano anche gli hook <literal role="hook">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>), <literal role="hook">incoming</literal> (<xref linkend="sec:hook:incoming"/>) e <literal role="hook">pretxnchangegroup</literal> (<xref linkend="sec:hook:pretxnchangegroup"/>).</para>
642 </sect2>
644 <sect2 id="sec:hook:precommit">
645 <title><literal role="hook">precommit</literal>&emdash;prima di cominciare l'inserimento di un changeset</title>
647 <para id="x_2b2">Questo hook viene eseguito prima che Mercurial cominci l'inserimento di un nuovo changeset, quindi prima che Mercurial conosca i metadati dell'inserimento come i file da inserire, il messaggio e la data di commit.</para>
649 <para id="x_2b3">Questo hook può essere usato per disabilitare la possibilità di inserire nuovi changeset, pur permettendo la trasmissione di changeset in entrata. Un'altra possibilità è quella di eseguire l'assemblaggio o il collaudo e consentire l'avvio dell'inserimento solo se l'assemblaggio o il collaudo hanno successo.</para>
651 <para id="x_2b4">I parametri di questo hook sono i seguenti.</para>
652 <itemizedlist>
653 <listitem><para id="x_2b5"><literal>parent1</literal>: un identificatore di changeset. L'identificatore di changeset del primo genitore della directory di lavoro.</para>
654 </listitem>
655 <listitem><para id="x_2b6"><literal>parent2</literal>: un identificatore di changeset. L'identificatore di changeset del secondo genitore della directory di lavoro.</para>
656 </listitem></itemizedlist>
657 <para id="x_2b7">Se l'inserimento procede, i genitori della directory di lavoro diventeranno i genitori del nuovo changeset.</para>
659 <para id="x_2b8">Si vedano anche gli hook <literal role="hook">commit</literal> (<xref linkend="sec:hook:commit"/>) e <literal role="hook">pretxncommit</literal> (<xref linkend="sec:hook:pretxncommit"/>).</para>
660 </sect2>
662 <sect2 id="sec:hook:preoutgoing">
663 <title><literal role="hook">preoutgoing</literal>&emdash;prima di cominciare la propagazione dei changeset</title>
665 <para id="x_2b9">Questo hook viene invocato prima che Mercurial conosca le identità dei changeset da trasmettere.</para>
667 <para id="x_2ba">Un possibile impiego di questo hook è quello di evitare che i changeset vengano trasmessi a un altro repository.</para>
669 <para id="x_2bb">I parametri di questo hook sono i seguenti.</para>
670 <itemizedlist>
671 <listitem><para id="x_2bc"><literal>source</literal>: una stringa. La fonte dell'operazione che sta tentando di ottenere i cambiamenti da questo repository (si veda la <xref linkend="sec:hook:sources"/>). Leggete la documentazione del parametro <literal>source</literal> dell'hook <literal role="hook">outgoing</literal> nella <xref linkend="sec:hook:outgoing"/> per conoscere i possibili valori di questo parametro.</para>
672 </listitem>
673 <listitem><para id="x_2bd"><literal>url</literal>: un URL. L'ubicazione del repository remoto, nel caso sia nota. Si veda la <xref linkend="sec:hook:url"/> per maggiori informazioni.</para>
674 </listitem></itemizedlist>
676 <para id="x_2be">Si veda anche l'hook <literal role="hook">outgoing</literal> (<xref linkend="sec:hook:outgoing"/>).</para>
677 </sect2>
679 <sect2 id="sec:hook:pretag">
680 <title><literal role="hook">pretag</literal>&emdash;prima di etichettare un changeset</title>
682 <para id="x_2bf">Questo hook di controllo viene eseguito prima della creazione di un'etichetta. Se l'hook ha successo, la creazione dell'etichetta procede. Se l'hook fallisce, l'etichetta non viene creata.</para>
684 <para id="x_2c0">I parametri di questo hook sono i seguenti.</para>
685 <itemizedlist>
686 <listitem><para id="x_2c1"><literal>local</literal>: un booleano. Indica se l'etichetta è locale a questa istanza del repository (i.e. memorizzata nel file <filename role="special">.hg/localtags</filename>) o se è gestita da Mercurial (memorizzata nel file <filename role="special">.hgtags</filename>).</para>
687 </listitem>
688 <listitem><para id="x_2c2"><literal>node</literal>: un identificatore di changeset. L'identificatore del changeset da etichettare.</para>
689 </listitem>
690 <listitem><para id="x_2c3"><literal>tag</literal>: una stringa. Il nome dell'etichetta da creare.</para>
691 </listitem></itemizedlist>
693 <para id="x_2c4">Se l'etichetta da creare è soggetta a controllo di revisione, verranno eseguiti anche gli hook <literal role="hook">precommit</literal> e <literal role="hook">pretxncommit</literal> (<xref linkend="sec:hook:commit"/> e <xref linkend="sec:hook:pretxncommit"/>).</para>
695 <para id="x_2c5">Si veda anche l'hook <literal role="hook">tag</literal> (<xref linkend="sec:hook:tag"/>).</para>
696 </sect2>
698 <sect2 id="sec:hook:pretxnchangegroup">
699 <title><literal
700 role="hook">pretxnchangegroup</literal>&emdash;prima di completare l'aggiunta di changeset remoti</title>
702 <para id="x_2c6">Questo hook di controllo viene eseguito prima di completare la transazione che gestisce l'aggiunta di un gruppo di nuovi changeset provenienti dall'esterno del repository. Se l'hook ha successo, la transazione viene completata e tutti i changeset diventano permanenti all'interno di questo repository. Se l'hook fallisce, la transazione viene abortita e i dati relativi ai changeset vengono cancellati.</para>
704 <para id="x_2c7">Questo hook può accedere ai metadati associati ai changeset in procinto di essere aggiunti, ma dovrebbe evitare di modificarli in maniera permanente. L'hook deve anche evitare di modificare la directory di lavoro.</para>
706 <para id="x_2c8">Se altri processi Mercurial accedono al repository mentre questo hook è in esecuzione, saranno in grado di vedere i changeset quasi aggiunti come se fossero permanenti. Questo potrebbe portare a condizioni di corsa critica se non eseguite i passi necessari per evitarle.</para>
708 <para id="x_2c9">Questo hook può essere usato per esaminare automaticamente un gruppo di changeset. Se l'hook fallisce, tutti i changeset vengono <quote>respinti</quote> quando la transazione viene abortita.</para>
710 <para id="x_2ca">I parametri di questo hook sono i seguenti.</para>
711 <itemizedlist>
712 <listitem><para id="x_2cb"><literal>node</literal>: un identificatore di changeset. L'identificatore del primo changeset nel gruppo che è stato aggiunto. Tutti i changeset tra questo e <literal role="tag">tip</literal> compresi sono stati aggiunti da una singola invocazione di <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command>, o <command role="hg-cmd">hg unbundle</command>.</para>
713 </listitem>
714 <listitem><para id="x_2cc"><literal>source</literal>: una stringa. La fonte di questi cambiamenti. Si veda la <xref linkend="sec:hook:sources"/> per i dettagli.</para>
715 </listitem>
716 <listitem><para id="x_2cd"><literal>url</literal>: un URL. L'ubicazione del repository remoto, nel caso sia nota. Si veda la <xref linkend="sec:hook:url"/> per maggiori informazioni.</para>
717 </listitem></itemizedlist>
719 <para id="x_2ce">Si vedano anche gli hook <literal role="hook">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>), <literal role="hook">incoming</literal> (<xref linkend="sec:hook:incoming"/>) e <literal role="hook">prechangegroup</literal> (<xref linkend="sec:hook:prechangegroup"/>).</para>
720 </sect2>
722 <sect2 id="sec:hook:pretxncommit">
723 <title><literal role="hook">pretxncommit</literal>&emdash;prima di completare l'inserimento di un nuovo changeset</title>
725 <para id="x_2cf">Questo hook di controllo viene eseguito prima di completare la transazione che gestisce un nuovo inserimento. Se l'hook ha successo, la transazione viene completata e il changeset diventa permanente all'interno di questo repository. Se l'hook fallisce, la transazione viene abortita e i dati dell'inserimento vengono cancellati.</para>
727 <para id="x_2d0">Questo hook può accedere ai metadati associati al changeset in procinto di essere inserito, ma dovrebbe evitare di modificarli in maniera permanente. L'hook deve anche evitare di modificare la directory di lavoro.</para>
729 <para id="x_2d1">Se altri processi Mercurial accedono al repository mentre questo hook è in esecuzione, saranno in grado di vedere i changeset quasi aggiunti come se fossero permanenti. Questo potrebbe portare a condizioni di corsa critica se non eseguite i passi necessari per evitarle.</para>
731 <para id="x_2d2">I parametri di questo hook sono i seguenti.</para>
733 <itemizedlist>
734 <listitem><para id="x_2d3"><literal>node</literal>: un identificatore di changeset. L'identificatore del changeset sul punto di essere inserito.</para>
735 </listitem>
736 <listitem><para id="x_2d4"><literal>parent1</literal>: un identificatore di changeset. L'identificatore di changeset del primo genitore del changeset sul punto di essere inserito.</para>
737 </listitem>
738 <listitem><para id="x_2d5"><literal>parent2</literal>: un identificatore di changeset. L'identificatore di changeset del secondo genitore del changeset sul punto di essere inserito.</para>
739 </listitem></itemizedlist>
741 <para id="x_2d6">Si veda anche l'hook <literal role="hook">precommit</literal> (<xref linkend="sec:hook:precommit"/>).</para>
742 </sect2>
744 <sect2 id="sec:hook:preupdate">
745 <title><literal role="hook">preupdate</literal>&emdash;prima di eseguire un aggiornamento o un'unione della directory di lavoro</title>
747 <para id="x_2d7">Questo hook viene eseguito prima di cominciare un aggiornamento o un'unione della directory di lavoro. Viene eseguito solo se i normali controlli effettuati da Mercurial prima di un aggiornamento determinano che l'aggiornamento o l'unione possono procedere. Se l'hook ha successo, l'aggiornamento o l'unione possono procedere, ma se fallisce, l'aggiornameno o l'unione non vengono cominciati.</para>
749 <para id="x_2d8">I parametri di questo hook sono i seguenti.</para>
750 <itemizedlist>
751 <listitem><para id="x_2d9"><literal>parent1</literal>: un identificatore di changeset. L'identificatore del genitore a cui la directory di lavoro sta per essere aggiornata. Se si sta per effettuare un'unione, questo genitore non verrà modificato.</para>
752 </listitem>
753 <listitem><para id="x_2da"><literal>parent2</literal>: un identificatore di changeset. Il suo valore viene impostato solo se si sta eseguendo un'unione. Contiene l'identificatore della revisione con cui la directory di lavoro viene unita.</para>
754 </listitem></itemizedlist>
756 <para id="x_2db">Si veda anche l'hook <literal role="hook">update</literal> (<xref linkend="sec:hook:update"/>).</para>
757 </sect2>
759 <sect2 id="sec:hook:tag">
760 <title><literal role="hook">tag</literal>&emdash;dopo aver etichettato un changeset</title>
762 <para id="x_2dc">Questo hook viene eseguito dopo la creazione di un'etichetta.</para>
764 <para id="x_2dd">I parametri di questo hook sono i seguenti.</para>
765 <itemizedlist>
766 <listitem><para id="x_2de"><literal>local</literal>: un booleano. Indica se l'etichetta è locale a questa istanza del repository (i.e. memorizzata nel file <filename role="special">.hg/localtags</filename>) o se è gestita da Mercurial (memorizzata nel file <filename role="special">.hgtags</filename>).</para>
767 </listitem>
768 <listitem><para id="x_2df"><literal>node</literal>: un identificatore di changeset. L'identificatore del changeset che è stato etichettato.</para>
769 </listitem>
770 <listitem><para id="x_2e0"><literal>tag</literal>: una stringa. Il nome dell'etichetta creata.</para>
771 </listitem></itemizedlist>
773 <para id="x_2e1">Se l'etichetta creata è soggetta a controllo di revisione, l'hook <literal role="hook">commit</literal> (<xref linkend="sec:hook:commit"/>) verrà eseguito prima di questo hook.</para>
775 <para id="x_2e2">Si veda anche l'hook <literal role="hook">pretag</literal> (<xref linkend="sec:hook:pretag"/>).</para>
776 </sect2>
778 <sect2 id="sec:hook:update">
779 <title><literal role="hook">update</literal>&emdash;dopo aver eseguito un aggiornamento o un'unione della directory di lavoro</title>
781 <para id="x_2e3">Questo hook viene eseguito dopo il completamento di un aggiornamento o di un'unione della directory di lavoro. Dato che un'unione può fallire (nel caso il comando esterno <command>hgmerge</command> non sia in grado di risolvere i conflitti in un file), questo hook comunica se l'aggiornamento o l'unione sono stati completati in maniera pulita.</para>
783 <para id="x_ffe">I parametri di questo hook sono i seguenti.</para>
784 <itemizedlist>
785 <listitem><para id="x_2e4"><literal>error</literal>: un booleano. Indica se l'aggiornamento o l'unione sono stati completati con successo.</para>
786 </listitem>
787 <listitem><para id="x_2e5"><literal>parent1</literal>: un identificatore di changeset. L'identificatore del genitore a cui la directory di lavoro è stata aggiornata. Se è stata effettuata un'unione, questo genitore non viene modificato.</para>
788 </listitem>
789 <listitem><para id="x_2e6"><literal>parent2</literal>: un identificatore di changeset. Il suo valore viene impostato solo se è stata eseguita un'unione. Contiene l'identificatore della revisione con cui la directory di lavoro è stata unita.</para>
790 </listitem></itemizedlist>
792 <para id="x_2e7">Si veda anche l'hook <literal role="hook">preupdate</literal> (<xref linkend="sec:hook:preupdate"/>).</para>
794 </sect2>
795 </sect1>
796 </chapter>