Capitolo 12. Gestire il cambiamento con Mercurial Queues

Indice

Il problema della gestione delle patch
La preistoria di Mercurial Queues
Una «coperta a scacchi»
Da patchwork quilt a Mercurial Queues
L’enorme vantaggio di MQ
Capire le patch
Cominciare a usare Mercurial Queues
Creare una nuova patch
Aggiornare una patch
Impilare e registrare le patch
Manipolare la pila delle patch
Inserire ed estrarre molte patch
I controlli di sicurezza e come scavalcarli
Lavorare su diverse patch alla volta
Ulteriori informazioni sulle patch
Il numero di cancellazioni
Strategie per applicare una patch
Alcune stranezze nella rappresentazione delle patch
Fate attenzione all’incertezza
Gestire il rifiuto
Ulteriori informazioni sulla gestione delle patch
Cancellare le patch indesiderate
Convertire in e da revisioni permanenti
Ottenere le prestazioni migliori da MQ
Aggiornare le vostre patch quando il codice sottostante cambia
Identificare le patch
Informazioni utili
Gestire le patch in un repository
Il supporto di MQ per i repository di patch
Alcune cose a cui fare attenzione
Strumenti di terze parti che lavorano con le patch
Strategie valide per lavorare con le patch
Il ricettario di MQ
Gestire patch «elementari»
Combinare intere patch
Unire parte di una patch a un’altra
Differenze tra quilt e MQ

Il problema della gestione delle patch

Ecco uno scenario comune: avete bisogno di installare un pacchetto software dai sorgenti, ma trovate un bug che dovete correggere nei sorgenti prima di poter cominciare a usare il pacchetto. Fate le vostre modifiche, vi dimenticate del pacchetto per un po’ e alcuni mesi dopo avete bisogno di aggiornare il pacchetto a una nuova versione. Se la versione più nuova del pacchetto contiene ancora il bug, dovete estrarre la vostra correzione dal vecchio albero dei sorgenti e applicarla alla nuova versione. Questa è un’attività seccante durante la quale è facile commettere errori.

Questo è un semplice caso del problema di «gestione delle patch». Avete un albero di sorgenti «a monte» che non potete cambiare, avete bisogno di fare alcune modifiche locali all’albero a monte e vi piacerebbe essere in grado di mantenere separate quelle modifiche, in modo da poterle applicare a nuove versioni dei sorgenti a monte.

Il problema di gestione delle patch si presenta in molte situazioni. Probabilmente la più visibile è quella in cui un utente di un progetto software open source fornisce la correzione di un bug o una nuova funzione sotto forma di patch ai manutentori del progetto.

Chi distribuisce sistemi operativi che includono software open source ha spesso bisogno di effettuare modifiche ai pacchetti distribuiti in modo da assemblarli correttamente nel proprio ambiente.

Quando dovete mantenere solo alcune modifiche, potete facilmente gestire una singola patch usando i programmi standard diff e patch (si veda la sezione chiamata «Capire le patch» per una discussione di questi strumenti). Una volta che il numero di modifiche cresce, comincia ad avere senso l’idea di mantenere le patch come «frammenti di lavoro» distinti in modo che, per esempio, una singola patch contenga solo una correzione di bug (la patch potrebbe modificare diversi file, ma sta facendo «solo una cosa») e un certo numero di queste patch sia destinato a bug differenti che dovete correggere e a modifiche locali di cui avete bisogno. In questa situazione, se proponete una patch per la correzione di un bug ai manutentori del pacchetto a monte e questi includono la vostra correzione in una release successiva, potete semplicemente scartare quella singola patch quando state aggiornando il pacchetto a una nuova release.

Mantenere una singola patch per un albero a monte è un’attività un po’ noiosa e soggetta a errori, ma non è difficile. Tuttavia, la complessità del problema cresce rapidamente man mano che il numero di patch che dovete mantenere aumenta. Con più di un piccolo numero di patch in mano, il compito di capire quali sono quelle che dovete applicare e di mantenerle passa da sgradevole a opprimente.

Fortunatamente, Mercurial include una potente estensione, chiamata Mercurial Queues (letteralmente, Code di Mercurial) o semplicemente «MQ», che semplifica notevolmente il problema di gestione delle patch.

La preistoria di Mercurial Queues

Verso la fine degli anni ’90, diversi sviluppatori del kernel di Linux cominciarono a mantenere alcune «serie di patch» che modificavano il comportamento del kernel. Alcune di queste serie si concentravano sulla stabilità, alcune sull’inclusione di funzioni e altre erano più sperimentali.

La dimensione di queste serie di patch crebbe rapidamente. Nel 2002, Andrew Morton pubblicò alcuni script di shell che aveva usato per automatizzare la gestione delle proprie code di patch. Andrew era riuscito a usare questi script per gestire centinaia (talvolta migliaia) di patch per il kernel di Linux.

Una «coperta a scacchi»

All’inizio del 2003, Andreas Gruenbacher e Martin Quinson presero in prestito l’approccio degli script di Andrew e pubblicarono uno strumento chiamato «patchwork quilt» (letteralmente, coperta a scacchi) [Quilt], o semplicemente «quilt» (si veda [Gruenbacher2005] per un articolo che lo descrive). Dato che quilt sostanzialmente automatizzava la gestione delle patch, guadagnò rapidamente un grande seguito tra gli sviluppatori di software open source.

Quilt gestisce una pila di patch per un albero di directory. Per cominciare a usarlo, dite a quilt di gestire un albero di directory e quali file volete che gestisca, in modo che memorizzi i nomi e il contenuto di quei file. Per correggere un bug, create una nuova patch (usando un singolo comando), modificate i file che dovete correggere, poi «aggiornate» la patch.

L’operazione di aggiornamento induce quilt a esaminare l’albero di directory completando la patch con tutte le modifiche che avete fatto. Sulla base di questa prima patch, potete creare un’altra patch che terrà traccia dei cambiamenti richiesti per modificare l’albero da «albero con una patch applicata» ad «albero con due patch applicate».

Potete scegliere quali sono le patch da applicare all’albero. Se «estraete» una patch, i cambiamenti effettuati da quella patch spariranno dall’albero di directory. Quilt si ricorda quali patch avete estratto, comunque, così potete «inserire» nuovamente una patch estratta e l’albero di directory verrà ripristinato per contenere le modifiche di quella patch. La cosa più importante è che potete eseguire il comando di «aggiornamento» in ogni momento e la patch applicata più recentemente verrà aggiornata. Questo significa che, in ogni momento, potete modificare sia l’insieme delle patch da applicare sia l’insieme dei cambiamenti effettuati da quelle patch.

Quilt non ha nulla a che fare con gli strumenti di controllo di revisione, così funziona altrettanto bene con un gruppo di file estratti da un archivio compresso che con una copia di lavoro di Subversion.

Da patchwork quilt a Mercurial Queues

A metà del 2005, Chris Mason prese le funzioni di quilt e implementò un’estensione chiamata Mercurial Queues, che aggiungeva a Mercurial un comportamento simile a quello di quilt.

La differenza chiave tra quilt e MQ è che quilt non è progettato per interagire con alcun sistema di controllo di revisione, mentre MQ è integrata in Mercurial. Ogni patch che inserite è rappresentata sotto forma di changeset Mercurial. Se estraete una patch, il changeset relativo sparisce.

Dato che quilt non si preoccupa degli strumenti di controllo di revisione, rimane un software tremendamente utile da conoscere per impiegarlo nelle situazioni in cui non potete usare Mercurial e MQ.

L’enorme vantaggio di MQ

Non posso esagerare il valore dell’unificazione tra patch e controllo di revisione offerta da MQ.

Una delle ragioni principali per cui le patch sono ancora continuamente usate nel mondo del software libero e open source—nonostante la disponibilità di strumenti di controllo di revisione sempre più sofisticati—è l’agilità che offrono.

I tradizionali strumenti di controllo di revisione effettuano una registrazione permanente di ogni vostra azione. Da un lato questo ha un grande valore, ma dall’altro è anche piuttosto soffocante. Se volete effettuare un esperimento stravagante, dovete stare molto attenti a come procedete, o rischiate di lasciare tracce inutili—o peggio, ingannevoli e destabilizzanti—dei vostri passi falsi e dei vostri errori nella registrazione permanente delle revisioni.

Al contrario, il matrimonio tra controllo di revisione distribuito e patch realizzato da MQ rende molto più facile isolare il vostro lavoro. Le vostre patch si basano sulla normale cronologia delle revisioni e potete farle sparire e comparire a piacere. Se non vi piace una patch, potete scartarla. Se una patch non è esattamente come volete che sia, vi basta correggerla—tutte le volte che ne avete bisogno, fino a quando non l’avete ritoccata facendole assumere la forma che desiderate.

Per esempio, l’integrazione delle patch con il controllo di revisione facilita enormemente la comprensione delle patch e delle interazioni con il codice su cui si basano, nonché la correzione dei loro effetti. Dato che ogni patch applicata è associata a un changeset, potete invocare hg log con un nome di file per vedere quali changeset e quali patch hanno avuto effetto sul file. Potete usare il comando hg bisect per condurre una ricerca binaria attraverso tutti i changeset e le patch applicate in modo da scoprire dov’è stato introdotto o corretto un bug. Potete usare il comando hg annotate per vedere quali changeset o patch hanno modificato una particolare riga di un file sorgente. E così via.

Capire le patch

Dato che MQ non nasconde la sua natura orientata alle patch, vi potrà essere d’aiuto capire cosa sono le patch e conoscere un po’ gli strumenti che lavorano con esse.

Il tradizionale comando Unix diff confronta due file e stampa una lista di differenze tra loro. Il comando patch interpreta queste differenze come modifiche da effettuare a un file. Date un’occhiata qui di seguito per vedere un semplice esempio di questi comandi in azione.

$ echo 'questo è il mio primo pensiero' > vecchiofile
$ echo 'ho cambiato idea' > nuovofile
$ diff -u vecchiofile nuovofile > piccola.patch
$ cat piccola.patch
--- vecchiofile	2009-06-05 15:50:32.000000000 +0000
+++ nuovofile	2009-06-05 15:50:32.000000000 +0000
@@ -1 +1 @@
-questo è il mio primo pensiero
+ho cambiato idea
$ patch < piccola.patch
correggo il file vecchiofile
$ cat vecchiofile
ho cambiato idea

Il tipo di file generato da diff (e che patch prende in ingresso) viene chiamato una «patch» (letteralmente, pezza) o un «diff». Non c’è alcuna differenza tra una patch e un diff, ma noi useremo il termine «patch», dato che è quello più comunemente usato.

Un file di patch può cominciare con testo arbitrario che il comando patch ignora, ma che MQ usa come messaggio di commit quando crea i changeset. Per trovare l’inizio del contenuto della patch, il comando patch cerca la prima riga che comincia con la stringa «diff -».

MQ lavora con i diff unificati (patch può accettare molti altri formati di diff, ma MQ no). Un diff unificato contiene due tipi di intestazione. L’intestazione di file descrive il file che viene modificato e contiene il nome del file da modificare. Quando patch vede una nuova intestazione di file, cerca il file con quel nome per cominciare a modificarlo.

L’intestazione di file è seguita da una serie di blocchi. Ogni blocco comincia con un’intestazione che identifica l’intervallo di numeri di riga del file che il blocco dovrebbe modificare. Dopo l’intestazione, un blocco comincia e finisce con alcune (di solito tre) righe di testo proveniente dal file originale che vengono chiamate il contesto del blocco. Se c’è solo una quantità ridotta di contesto tra blocchi successivi, diff non stampa una nuova intestazione, ma si limita a unire insieme i blocchi inserendo alcune righe di contesto tra le modifiche.

Ogni riga di contesto comincia con un carattere di spazio. Nell’ambito di un blocco, una riga che comincia con «-» significa «rimuovi questa riga», mentre una riga che comincia con «+» significa «inserisci questa riga». Per esempio, una riga modificata viene rappresentata da una cancellazione e da un inserimento.

Ritorneremo su alcuni degli aspetti più sottili delle patch più avanti (nella sezione chiamata «Ulteriori informazioni sulle patch»), ma ora dovreste avere abbastanza informazioni per usare MQ.

Cominciare a usare Mercurial Queues

Dato che MQ è implementata come un’estensione, dovete esplicitamente abilitarla prima di poterla usare. (Non avete bisogno di scaricare nulla, perché MQ è inclusa con la distribuzione standard di Mercurial.) Per abilitare MQ, modificate il vostro file ~/.hgrc aggiungendo le seguenti righe.

[extensions]
hgext.mq =

Una volta che avete abilitato l’estensione, vi verranno messi a disposizione alcuni nuovi comandi. Per verificare che l’estensione funzioni, potete usare hg help per vedere se il comando qinit viene elencato come disponibile.

$ hg help qinit
hg qinit [-c]

inizializza un nuovo repository di coda

    Per default, il repository di coda non è sotto controllo
    di revisione. Se viene specificato -c, qinit creerà un
    repository annidato separato per le patch (qinit -c può
    anche essere invocato più tardi per convertire un repository
    di patch non gestito in uno gestito). Potete usare qcommit
    per inserire modifiche in questo repository di coda.

opzioni:

 -c --create-repo  crea il repository di coda

usate "hg -v help qinit" per vedere le opzioni globali

MQ può essere usata con qualsiasi repository Mercurial e i suoi comandi operano solo all’interno di quel repository. Per cominciare, preparate semplicemente il repository usando il comando qinit.

$ hg init mq-prova
$ cd mq-prova
$ echo 'riga 1' > file1
$ echo "un'altra riga 1" > file2
$ hg add file1 file2
$ hg commit -m "Prima modifica."
$ hg qinit

Questo comando crea una directory vuota chiamata .hg/patches, dove MQ terrà i propri metadati. Come accade con molti comandi Mercurial, il comando qinit non stamperà nulla nel caso termini con successo.

Creare una nuova patch

Per cominciare a lavorare su una nuova patch, usate il comando qnew. Questo comando prende come argomento il nome della patch da creare.

MQ userà questo nome per memorizzare un file nella directory .hg/patches, come potete vedere qui sotto.

$ hg tip
changeset:   0:c6618fa9eed7
etichetta:   tip
utente:      Bryan O'Sullivan <[email protected]>
data:        Fri Jun 05 15:50:56 2009 +0000
sommario:    Prima modifica.

$ hg qnew prima.patch
$ hg tip
changeset:   1:f32697f1a94e
etichetta:   qtip
etichetta:   prima.patch
etichetta:   tip
etichetta:   qbase
utente:      Bryan O'Sullivan <[email protected]>
data:        Fri Jun 05 15:50:57 2009 +0000
sommario:    [mq]: prima.patch

$ ls .hg/patches
prima.patch  series  status

La directory .hg/patches contiene anche altri due nuovi file, series e status. Il file series elenca tutte le patch per questo repository di cui MQ è a conoscenza, con una patch per ogni riga. Mercurial usa il file status per tenere traccia internamente di tutte le patch che MQ ha applicato a questo repository.

[Nota]Nota

A volte potreste voler modificare il file series a mano, per esempio per cambiare la sequenza in cui sono applicate alcune patch. Tuttavia, modificare manualmente il file status è quasi sempre una cattiva idea, dato che così facendo si rischia facilmente di disorientare MQ.

Una volta che avete creato la vostra nuova patch, potete modificare i file nella directory di lavoro come fareste di solito. Tutti i normali comandi Mercurial, come hg diff e hg annotate, funzionano allo stesso modo in cui funzionavano prima.

Aggiornare una patch

Quando raggiungete un punto in cui volete salvare il vostro lavoro, usate il comando qrefresh per aggiornare la patch su cui state lavorando.

$ echo 'riga 2' >> file1
$ hg diff
diff -r f32697f1a94e file1
--- a/file1	Fri Jun 05 15:50:57 2009 +0000
+++ b/file1	Fri Jun 05 15:50:58 2009 +0000
@@ -1,1 +1,2 @@
 riga 1
+riga 2
$ hg qrefresh
$ hg diff
$ hg tip --style=compact --patch
1[qtip,prima.patch,tip,qbase]   18f39bf02ad5   2009-06-05 15:50 +0000   bos
  [mq]: prima.patch

diff -r c6618fa9eed7 -r 18f39bf02ad5 file1
--- a/file1	Fri Jun 05 15:50:56 2009 +0000
+++ b/file1	Fri Jun 05 15:50:59 2009 +0000
@@ -1,1 +1,2 @@
 riga 1
+riga 2

Questo comando include nella vostra patch i cambiamenti che avete fatto nella directory di lavoro e aggiorna il changeset corrispondente alla patch in modo che contenga quei cambiamenti.

Potete invocare qrefresh tutte le volte che volete, quindi questo comando rappresenta un buon modo per «controllare» il vostro lavoro. Aggiornate la vostra patch al momento opportuno, tentate un esperimento e se l’esperimento non funziona usate hg revert per ripristinare le vostre modifiche all’ultimo aggiornamento che avete compiuto.

$ echo 'riga 3' >> file1
$ hg status
M file1
$ hg qrefresh
$ hg tip --style=compact --patch
1[qtip,prima.patch,tip,qbase]   8593307a06ec   2009-06-05 15:51 +0000   bos
  [mq]: prima.patch

diff -r c6618fa9eed7 -r 8593307a06ec file1
--- a/file1	Fri Jun 05 15:50:56 2009 +0000
+++ b/file1	Fri Jun 05 15:51:00 2009 +0000
@@ -1,1 +1,3 @@
 riga 1
+riga 2
+riga 3

Impilare e registrare le patch

Una volta che avete finito di lavorare su una patch, o avete bisogno di lavorare su un’altra patch, potete usare di nuovo il comando qnew per creare una nuova patch. Mercurial applicherà questa patch a partire dalla vostra patch esistente.

$ hg qnew seconda.patch
$ hg log --style=compact --limit=2
2[qtip,seconda.patch,tip]   2d7ecb80769d   2009-06-05 15:51 +0000   bos
  [mq]: seconda.patch

1[prima.patch,qbase]   8593307a06ec   2009-06-05 15:51 +0000   bos
  [mq]: prima.patch

$ echo 'riga 4' >> file1
$ hg qrefresh
$ hg tip --style=compact --patch
2[qtip,seconda.patch,tip]   78d47e79ab59   2009-06-05 15:51 +0000   bos
  [mq]: seconda.patch

diff -r 8593307a06ec -r 78d47e79ab59 file1
--- a/file1	Fri Jun 05 15:51:00 2009 +0000
+++ b/file1	Fri Jun 05 15:51:02 2009 +0000
@@ -1,3 +1,4 @@
 riga 1
 riga 2
 riga 3
+riga 4

$ hg annotate file1
0: riga 1
1: riga 2
1: riga 3
2: riga 4

Notate che la patch contiene le modifiche della nostra patch precedente come parte del proprio contesto (potete vederlo più chiaramente nel risultato di hg annotate).

Finora, con l’eccezione di qnew e qrefresh, siamo stati attenti a usare solo gli ordinari comandi Mercurial. Tuttavia, MQ fornisce molti comandi che sono più facili da usare quando state pensando in termini di patch, come illustrato di seguito.

$ hg qseries
prima.patch
seconda.patch
$ hg qapplied
prima.patch
seconda.patch
  • Il comando qseries elenca tutte le patch per questo repository di cui MQ è a conoscenza, dalla più vecchia alla più recente (più recentemente creata).

  • Il comando qapplied elenca tutte le patch che MQ ha applicato a questo repository, sempre dalla più vecchia alla più recente (più recentemente applicata).

Manipolare la pila delle patch

La discussione precedente implica che ci deve essere una differenza tra patch «note» e patch «applicate», e in effetti c’è. MQ può gestire una patch senza che sia applicata al repository.

Una patch applicata ha un corrispondente changeset nel repository e gli effetti della patch e del changeset sono visibili nella directory di lavoro. Potete annullare l’applicazione di una patch usando il comando qpop. La patch estratta è ancora nota, cioè gestita da MQ, ma non ha più un corrispondente changeset nel repository, e la directory di lavoro non contiene più le modifiche apportate dalla patch. La Figura 12.1, «Patch applicate e non applicate nella pila delle patch di MQ» illustra la differenza tra patch applicate e registrate.

Figura 12.1. Patch applicate e non applicate nella pila delle patch di MQ

XXX add text

Potete riapplicare una patch non applicata o estratta usando il comando qpush. Questo comando crea un nuovo changeset da far corrispondere alla patch, e le modifiche della patch compaiono nuovamente nella directory di lavoro. Di seguito, vengono mostrati esempi di qpop e qpush in azione.

$ hg qapplied
prima.patch
seconda.patch
$ hg qpop
ora a: prima.patch
$ hg qseries
prima.patch
seconda.patch
$ hg qapplied
prima.patch
$ cat file1
riga 1
riga 2
riga 3

Notate che, dopo aver estratto una patch o due patch, il risultato di qseries è rimasto lo stesso, mentre quello di qapplied è cambiato.

Inserire ed estrarre molte patch

Sebbene i comandi qpush e qpop operino in maniera predefinita su una singola patch alla volta, potete inserire ed estrarre molte patch in un unico passaggio. L’opzione -a di qpush lo induce a inserire tutte le patch non applicate, mentre l’opzione -a di qpop lo induce a estrarre tutte le patch applicate. (Per ulteriori modi di inserire ed estrarre molte patch, si veda la sezione chiamata «Ottenere le prestazioni migliori da MQ» più avanti.)

$ hg qpush -a
applico seconda.patch
ora a: seconda.patch
$ cat file1
riga 1
riga 2
riga 3
riga 4

I controlli di sicurezza e come scavalcarli

Diversi comandi MQ esaminano la directory di lavoro prima di fare qualunque cosa e falliscono se trovano una qualsiasi modifica. Si comportano in questo modo per assicurarsi di non farvi perdere i cambiamenti che avete fatto ma che non avete ancora incorporato in una patch. L’esempio seguente illustra questo caso: il comando qnew eviterà di creare una nuova patch se ci sono cambiamenti in sospeso, causati in questo caso dall’invocazione di hg add su file3.

$ echo 'file 3, riga 1' >> file3
$ hg add file3
$ hg qnew aggiunto-file3.patch
fallimento: ci sono modifiche locali, aggiornate prima la patch corrente
$ hg qnew -f aggiunto-file3.patch

Tutti i comandi che esaminano la directory di lavoro accettano un’opzione «so cosa sto facendo» che si chiama sempre -f. L’esatto significato di -f dipende dal comando. Per esempio, hg qnew -f incorporerà i cambiamenti in sospeso nella nuova patch creata, ma hg qpop -f annullerà le modifiche a qualsiasi file coinvolto dalla patch che sta estraendo. Assicuratevi di leggere la documentazione per l’opzione -f di un comando prima di usarla!

Lavorare su diverse patch alla volta

Il comando qrefresh aggiorna sempre la patch applicata più recentemente. Questo significa che potete sospendere il lavoro su una patch (aggiornandola), operare estrazioni o inserimenti in modo che l’ultima patch applicata sia differente e lavorare su questa patch per un po’.

Ecco un esempio che illustra come potete sfruttare questa possibilità. Diciamo che state sviluppando una nuova funzione sotto forma di due patch. La prima è una modifica al nucleo del vostro software e la seconda—basata sulla prima—modifica l’interfaccia utente per usare il codice che avete appena aggiunto al nucleo. Se notate un bug nel nucleo mentre state lavorando sulla patch per l’interfaccia utente, per correggerlo vi basta usare qrefresh, in modo da salvare le modifiche in corso alla vostra patch di interfaccia, e poi usare qpop per poter operare sulla patch del nucleo. Correggete il bug nel nucleo, aggiornate la patch del nucleo con qrefresh e inserite la patch di interfaccia tramite qpush per continuare a lavorare dal punto dove avevate lasciato.

Ulteriori informazioni sulle patch

MQ usa il comando GNU patch per applicare le patch, quindi vi sarà d’aiuto conoscere qualche altro aspetto di dettaglio sul funzionamento di patch e sulle patch stesse.

Il numero di cancellazioni

Se osservate le intestazioni di file in una patch, noterete che i percorsi dei nomi di solito hanno un componente aggiuntivo iniziale che non è presente nel percorso reale. Questo è uno strascico del modo in cui le persone erano abituate a generare le patch (questo modo viene ancora impiegato, ma piuttosto raramente ora che sono disponibili strumenti di controllo di revisione più moderni).

Alice avrebbe estratto un archivio, modificato i file e poi deciso di voler creare una patch. Quindi avrebbe rinominato la directory di lavoro, estratto nuovamente l’archivio (da qui nasce il bisogno di modificare il nome) e usato le opzioni -r e -N del comando diff per generare ricorsivamente una patch tra la directory non modificata e quella modificata. Come risultato, il nome della directory non modificata si sarebbe trovato all’inizio del percorso sulla parte sinistra di ogni intestazione di file e il nome della directory modificata si sarebbe trovato all’inizio del percorso sulla parte destra.

Dato che chi riceveva una patch dalle Alice della rete probabilmente non avrebbe avuto le due copie, modificata e non, della directory con esattamente gli stessi nomi, il comando patch è stato dotato di un’opzione -p che indica il numero di elementi iniziali da eliminare dal percorso al momento di applicare una patch. Questo numero viene chiamato il numero di cancellazioni.

Un’opzione «-p1» significa «usa un numero di cancellazioni pari a uno». Se patch vede un nome di file foo/bar/baz in un’intestazione di file, eliminerà foo e proverà ad applicare la patch al file bar/baz. Strettamente parlando, il numero di cancellazioni si riferisce al numero di separatori di percorso (e dei relativi elementi) da eliminare. Un numero di cancellazioni pari a uno trasformerà foo/bar in bar, ma /foo/bar (notate lo slash iniziale) in foo/bar.

Il numero di cancellazioni «standard» per le patch è pari a uno, in quanto quasi tutte le patch contengono un elemento iniziale da eliminare nel percorso. Il comando hg diff di Mercurial genera nomi di percorso in questa forma e sia il comando hg import che MQ si aspettano patch con un numero di cancellazioni pari a uno.

Se qualcuno vi invia una patch che volete aggiungere alla vostra coda delle patch e la patch necessita di un numero di cancellazioni diverso da uno, non potete usare semplicemente qimport con la patch, perché qimport non è ancora dotato di un’opzione -p (si veda il problema 311 per i dettagli). L’alternativa migliore che avete è quella di creare una vostra patch con qnew e poi usare il comando patch -pN per applicare la patch che avete ricevuto, seguito da hg addremove per registrare qualsiasi file aggiunto o rimosso dalla patch, seguito da hg qrefresh. Questa complessità potrebbe diventare inutile una volta che il problema 311 verrà risolto.

Strategie per applicare una patch

Quando patch applica un blocco, prova a impiegare una serie di strategie successive sempre meno accurate per portare a termine l’operazione. Questo impiego di tecniche alternative rende spesso possibile prendere una patch che è stata generata a partire da una vecchia versione di un file e applicarla alla nuova versione di quel file.

Come prima cosa, patch cerca una corrispondenza esatta, dove i numeri di riga, il contesto e il testo da modificare devono applicarsi perfettamente. Se non riesce a trovare una corrispondenza esatta, cerca una corrispondenza esatta per il contesto, senza onorare le informazioni sulla numerazione delle righe. Se questa strategia ha successo, il comando stampa una riga dicendo che il blocco è stato applicato, ma con un certo scostamento rispetto al numero di riga originale.

Se la corrispondenza con il solo contesto fallisce, patch rimuove la prima e l’ultima riga del contesto e tenta una corrispondenza con la sola versione ridotta del contesto. Se il blocco con il contesto ridotto ha successo, stampa un messaggio dicendo di aver applicato il blocco con un fattore di incertezza (il numero dopo il fattore di incertezza indica quante righe del contesto sono state escluse da patch prima che la patch si potesse applicare).

Quando nessuna di queste tecniche funziona, patch stampa un messaggio dicendo che il blocco in questione è stato rifiutato. Il comando salva i blocchi rifiutati (anche chiamati semplicemente «rifiuti») in un file con lo stesso nome e un’estensione .rej aggiuntiva. Le copie non modificate del file vengono salvate con un’estensione .orig, mentre la copia del file senza alcuna estensione conterrà le modifiche fatte dai blocchi che sono stati effettivamente applicati. Se avete una patch che modifica il file foo con sei blocchi, ma uno di essi non si riesce ad applicare, otterrete una copia foo.orig non modificata del file originale, un file foo.rej contenente un blocco e il file foo contenente le modifiche effettuate dai cinque blocchi applicati con successo.

Alcune stranezze nella rappresentazione delle patch

Ci sono alcune cose utili da sapere sul modo in cui patch lavora con i file.

  • Questo dovrebbe già essere ovvio, ma patch non è in grado di gestire i file binari.

  • Il comando non si cura neanche del bit di esecuzione, bensì crea i nuovi file come leggibili, ma non eseguibili.

  • patch tratta la rimozione di un file come un diff tra il file da rimuovere e un file vuoto. Quindi la vostra idea di «cancellare un file» viene rappresentata in una patch come «ogni riga di questo file è stata cancellata».

  • Tratta l’aggiunta di un file come un diff tra un file vuoto e il file da aggiungere. Quindi la vostra idea di «aggiungere un file» viene rappresentata in una patch come «ogni riga di questo file è stata aggiunta».

  • Tratta un file rinominato come la rimozione del file con il vecchio nome e l’aggiunta del file con il nuovo nome. Questo significa che i file rinominati occupano molto spazio in una patch. (Notate anche che Mercurial attualmente non cerca di inferire se i file in una patch sono stati rinominati o copiati.)

  • patch non è in grado di rappresentare i file vuoti, quindi non potete usare una patch per rappresentare la nozione di «aggiungere questo file vuoto all’albero».

Fate attenzione all’incertezza

Anche se l’applicazione di un blocco con un certo scostamento o con un certo fattore di incertezza avrà spesso un successo completo, queste tecniche inesatte lasciano naturalmente aperta la possibilità di rovinare il file modificato. Il caso più comune è tipicamente quello in cui la patch viene applicata due volte o in una posizione sbagliata nel file. Se patch o qpush dovessero mai menzionare lo scostamento o il fattore di incertezza, dovreste assicurarvi che i file siano stati modificati in maniera corretta.

Spesso è una buona idea aggiornare una patch che è stata applicata con uno scostamento o un fattore di incertezza, perché l’aggiornamento della patch genera nuove informazioni di contesto che permetteranno di applicarla in maniera precisa. Dico «spesso», non «sempre», perché qualche volta l’aggiornamento di una patch ne renderà impossibile l’applicazione su una revisione differente dei file coinvolti. In alcuni casi, come quando state mantenendo una patch che deve essere applicabile a molteplici versioni di un albero di sorgenti, è considerato accettabile avere una patch che si applica con qualche incertezza, purché abbiate verificato i risultati del processo di applicazione in casi come questi.

Gestire il rifiuto

Se qpush non riesce ad applicare una patch, stamperà un messaggio di errore e terminerà. Se ha lasciato alcuni file .rej, normalmente è meglio correggere i blocchi rifiutati prima di inserire altre patch o fare qualsiasi ulteriore modifica.

Se di solito la vostra patch si applicava in maniera pulita e ora non lo fa più perché avete modificato il codice sottostante su cui si basavano le vostre patch, Mercurial Queues può aiutarvi: leggete la sezione chiamata «Aggiornare le vostre patch quando il codice sottostante cambia» per i dettagli.

Sfortunatamente, non esiste alcuna tecnica particolare per gestire i blocchi rifiutati. Molto spesso, dovrete esaminare il file .rej e modificare il file di destinazione, applicando a mano i blocchi rifiutati.

Un programmatore del kernel di Linux, Chris Mason (l’autore di Mercurial Queues), ha realizzato uno strumento chiamato mpatch [Mason], che adotta un metodo semplice per automatizzare l’applicazione dei blocchi rifiutati da patch. Il comando mpatch può aiutarvi nel caso il blocco sia stato rifiutato per quattro tipiche ragioni:

  • il contesto in mezzo a un blocco è cambiato;

  • all’inizio o alla fine del blocco manca una certa quantità di contesto;

  • un blocco più ampio potrebbe applicarsi meglio—interamente o in parte—se fosse suddiviso in blocchi più piccoli;

  • un blocco rimuove righe con un contesto leggermente differente rispetto a quello attualmente presente nel file.

Se usate il comando mpatch, dovreste stare doppiamente attenti quando controllate i risultati al termine dell’esecuzione. In effetti, mpatch impone questo metodo di doppio controllo sul risultato dello strumento, avviando automaticamente un programma di gestione delle unioni quando ha concluso il proprio lavoro, in modo che possiate verificare i risultati e risolvere qualsiasi conflitto rimanente.

Ulteriori informazioni sulla gestione delle patch

Man mano che acquisite familiarità con MQ, comincerete a voler eseguire altri tipi di operazioni di gestione delle patch.

Cancellare le patch indesiderate

Se volete sbarazzarvi di una patch, usate il comando hg qdelete per cancellare il file contenente la patch e rimuovere la sua voce dalla serie di patch. Se provate a cancellare una patch che è ancora applicata, hg qdelete si rifiuterà di operare.

$ hg init miorepo
$ cd miorepo
$ hg qinit
$ hg qnew cattiva.patch
$ echo a > a
$ hg add a
$ hg qrefresh
$ hg qdelete cattiva.patch
fallimento: non posso cancellare la patch applicata cattiva.patch
$ hg qpop
la coda delle patch è vuota
$ hg qdelete cattiva.patch

Convertire in e da revisioni permanenti

Una volta che avete finito di lavorare con una patch e volete trasformarla in un changeset permanente, usate il comando hg qfinish. Passate una revisione al comando per identificare la patch che volete trasformare in un normale changeset; questa patch deve essere già stata applicata.

$ hg qnew buona.patch
$ echo a > a
$ hg add a
$ hg qrefresh -m "Buona modifica."
$ hg qfinish tip
$ hg qapplied
$ hg tip --style=compact
0[tip]   8eae2605f537   2009-06-05 15:49 +0000   bos
  Buona modifica.

Il comando hg qfinish accetta un’opzione --all o -a per trasformare tutte le patch applicate in normali changeset.

È anche possibile trasformare un changeset esistente in una patch, passando l’opzione -r al comando hg qimport.

$ hg qimport -r tip
$ hg qapplied
0.diff

Notate che ha senso convertire un changeset in una patch solo se non avete propagato quel changeset in altri repository. L’identificatore del changeset importato cambierà ogni volta che aggiornate la patch, cosa che indurrà Mercurial a trattarlo come se non fosse correlato al changeset originale che avete trasmesso da qualche altra parte.

Ottenere le prestazioni migliori da MQ

MQ è molto efficiente nel gestire un grande numero di patch. Ho effettuato alcuni esperimenti sulle prestazioni a metà del 2006 per una presentazione che ho tenuto alla conferenza EuroPython 2006 (su macchine più moderne, dovreste aspettarvi risultati migliori di quelli che vedrete nel seguito). Come dati campione ho usato la serie di patch 2.6.17-mm1 per il kernel di Linux, contenente 1.738 patch. Ho applicato queste patch a un repository del kernel di Linux contenente tutte le 27.472 revisioni intercorse tra Linux 2.6.12-rc2 e Linux 2.6.17.

Sul mio vecchio e lento portatile, sono riuscito a eseguire hg qpush -a per tutte le 1.738 patch in 3.5 minuti e a eseguire hg qpop -a per tutte le patch in 30 secondi. (Su portatili più recenti, il tempo per estrarre tutte le patch è sceso a due minuti.) Ho potuto aggiornare una delle patch più grandi (che ha effettuato 22.779 righe di cambiamenti a 287 file) eseguendo qrefresh in 6.6 secondi.

Chiaramente, MQ è particolarmente adatto per lavorare su alberi di grandi dimensioni, ma ci sono alcuni trucchi che potete usare per ottenere prestazioni ancora migliori.

Prima di tutto, provate a «raggruppare» insieme le operazioni. Quando eseguite qpush o qpop, questi comandi esaminano la directory di lavoro una volta per assicurarsi che non abbiate effettuato alcuna modifica dimenticandovi poi di invocare qrefresh. Su alberi di piccole dimensioni, il tempo impiegato da questa disamina è insignificante. Tuttavia, su un albero di medie dimensioni (contenente decine di migliaia di file), questa operazione può impiegare anche più di un secondo.

I comandi qpush e qpop vi permettono di estrarre e inserire più patch alla volta. Come prima cosa, identificate la «patch di destinazione» che volete raggiungere. Quando usate qpush specificando una destinazione, il comando inserirà patch finché quella patch non si troverà in cima alla pila delle patch applicate. Quando usate qpop con una destinazione, MQ estrarrà patch finché la patch di destinazione non si troverà in cima a quella pila.

Potete indicare una patch di destinazione usando il nome della patch oppure un numero. Se usate un identificatore numerico, il conteggio delle patch parte da zero: questo significa che la prima patch corrisponde a zero, la seconda a uno, e così via.

Aggiornare le vostre patch quando il codice sottostante cambia

Capita spesso di mantenere una pila di patch su un repository sottostante che non modificate direttamente. Se state lavorando sui cambiamenti a codice di terze parti, o su una funzione che impiegate più tempo a sviluppare rispetto alla velocità di cambiamento del codice su cui si basa, avrete spesso bisogno di sincronizzarvi con il codice sottostante e di correggere ogni blocco delle vostre patch che non è più applicabile. Questa operazione si chiama rifondare la vostra serie di patch.

Il modo più semplice per eseguire questa operazione è quello di usare hg qpop -a per estrarre le vostre patch, poi invocare hg pull per propagare i cambiamenti nel repository sottostante e infine eseguire hg qpush -a per inserire nuovamente le vostre patch. MQ interromperà l’inserimento ogni volta che incontra una patch che non riesce ad applicare a causa di qualche conflitto, dandovi la possibilità di risolvere i conflitti, aggiornare la patch interessata tramite qrefresh e continuare a inserire fino a quando non avrete corretto l’intera pila.

Questo approccio è semplice e funziona bene se non vi aspettate che le modifiche al codice sottostante influenzino l’applicabilità delle vostre patch. Tuttavia, se la vostra pila di patch coinvolge codice che viene modificato in maniera frequente o invasiva nel repository sottostante, correggere a mano i blocchi rifiutati diventa velocemente una seccatura.

È possibile automatizzare parzialmente il processo di rifondazione. Se le vostre patch si applicano in maniera pulita su una qualche revisione del repository sottostante, MQ può usare questa informazione per aiutarvi a risolvere i conflitti tra le vostre patch e una revisione differente.

Il processo è leggermente complicato.

  1. Come prima cosa, invocate hg qpush -a per inserire tutte le vostre patch sulla revisione su cui sapete che si applicano in maniera pulita.

  2. Salvate una copia di backup della vostra directory delle patch usando hg qsave -e -c. Questo comando salva le patch in una directory chiamata .hg/patches.N, dove N è un piccolo intero, e stampa il nome della directory in cui sono state salvate le patch. Il comando inserisce anche un «changeset di salvataggio» dopo quelli corrispondenti alle vostre patch applicate, per registrare internamente gli stati dei file series e status.

  3. Invocate hg pull per propagare i nuovi cambiamenti nel repository sottostante. (Non usate hg pull -u, perché l’aggiornamento dovrà essere fatto in maniera particolare, come vedrete nel prossimo punto.)

  4. Aggiornate la directory di lavoro alla nuova revisione di punta, usando hg update -C per sovrascrivere le modifiche apportate dalle patch che avete inserito.

  5. Unite tutte le patch usando hg qpush -m -a. L’opzione -m di qpush dice a MQ di effettuare un’unione a tre vie se l’applicazione di una patch fallisce.

Durante l’esecuzione di hg qpush -m, ogni patch nel file series viene applicata normalmente. Se una patch viene applicata con un fattore di incertezza o viene rifiutata, MQ esamina la coda che avete salvato tramite qsave ed effettua un’unione a tre vie con il changeset che corrisponde alla patch. Questa operazione sfrutta il normale meccanismo di unione di Mercurial, quindi potrebbe aprire uno strumento grafico di unione in modo da aiutarvi a risolvere i problemi.

Quando avete finito di risolvere gli effetti di una patch, MQ aggiornerà la vostra patch sulla base dei risultati dell’unione.

Alla fine di questo processo, il vostro repository conterrà una testa aggiuntiva proveniente dalla vecchia coda delle patch e la directory .hg/patches.N conterrà una copia della vecchia coda delle patch. Potete rimuovere la testa aggiuntiva usando hg qpop -a -n patches.N o hg strip. Potete cancellare .hg/patches.N una volta che siete sicuri di non averne più bisogno come backup.

Identificare le patch

I comandi MQ che lavorano con le patch vi permettono di fare riferimento a una patch usando il suo nome o un numero. Il riferimento per nome funziona in modo abbastanza ovvio: passate il nome foo.patch a qpush, per esempio, e il comando inserirà patch fino a quando foo.patch non verrà applicata.

Potete abbreviare il riferimento a una patch usando sia un nome che una differenza numerica: foo.patch-2 significa «due patch prima di foo.patch», mentre bar.patch+4 significa «quattro patch dopo bar.patch».

Il riferimento per indice non è molto diverso. La prima patch visualizzata da qseries è la patch numero zero (sì, è uno di quei sistemi di conteggio che partono da zero), la seconda è la patch numero uno, e così via.

MQ rende anche più facile lavorare con le patch usando i normali comandi Mercurial. Tutti i comandi che accettano un identificatore di changeset accettano anche il nome di una patch applicata. MQ aggiunge un’etichetta omonima per ogni patch applicata alle etichette normalmente presenti nel repository. In più, le etichette speciali qbase e qtip identificano rispettivamente la prima e l’ultima patch applicata.

Queste aggiunte alla funzione di etichettatura di Mercurial facilitano ulteriormente l’uso delle patch.

  • Volete bombardare di patch una mailing list con l’ultima serie dei vostri cambiamenti?

    hg email qbase:qtip

    (Non sapete cosa sia un «bombardamento di patch»? Leggete la sezione chiamata «Inviare cambiamenti via email con l’estensione patchbomb».)

  • Avete bisogno di vedere tutte le patch che da foo.patch in poi hanno coinvolto i file contenuti in una sottodirectory del vostro albero?

    hg log -r foo.patch:qtip sottodirectory

Dato che MQ rende disponibili i nomi delle patch alle altre parti di Mercurial tramite il meccanismo interno delle etichette, non avete bisogno di digitare l’intero nome di una patch quando volete identificarla per nome.

Un’altra piacevole conseguenza del rappresentare i nomi di patch come etichette è che il comando hg log mostrerà normalmente il nome di una patch come un’etichetta nel proprio elenco, rendendo facile distinguere visivamente le patch applicate dalle «normali» revisioni sottostanti. L’esempio seguente mostra alcuni comandi Mercurial in azione con le patch applicate.

$ hg qapplied
prima.patch
seconda.patch
$ hg log -r qbase:qtip
changeset:   1:32b3cae9e753
etichetta:   prima.patch
etichetta:   qbase
utente:      Bryan O'Sullivan <[email protected]>
data:        Fri Jun 05 15:50:45 2009 +0000
sommario:    [mq]: prima.patch

changeset:   2:dee839d89dc6
etichetta:   qtip
etichetta:   seconda.patch
etichetta:   tip
utente:      Bryan O'Sullivan <[email protected]>
data:        Fri Jun 05 15:50:46 2009 +0000
sommario:    [mq]: seconda.patch

$ hg export seconda.patch
# HG changeset di patch
# Utente Bryan O'Sullivan <[email protected]>
# Data 1244217046 0
# ID di nodo dee839d89dc6e420682b02551b31e8375929aa7c
# Genitore 32b3cae9e753537be60bb2fbfefe0de3e19ec4a3
[mq]: seconda.patch

diff -r 32b3cae9e753 -r dee839d89dc6 altro.c
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/altro.c	Fri Jun 05 15:50:46 2009 +0000
@@ -0,0 +1,1 @@
+double u;

Informazioni utili

Ci sono alcuni aspetti dell’uso di MQ che non trovano posto in sezioni dedicate, ma che è bene conoscere. Li presento qui, in un unico posto.

  • Normalmente, quando estraete una patch tramite qpop e poi la reinserite tramite qpush, il changeset che rappresenta la patch dopo l’estrazione/inserimento avrà una diversa identità rispetto al changeset che rappresentava l’hash in precedenza. Leggete la sezione chiamata «qpush—inserisce le patch in cima alla pila» per sapere perché.

  • Non è una buona idea usare hg merge per unire i cambiamenti provenienti da un altro ramo con un changeset corrispondente a una patch, almeno se volete mantenere la «natura di patch» di quel changeset e dei changeset che si trovano sotto a quello nella pila delle patch. Se provate a farlo, sembrerà avere successo, ma l’effetto sarà quello di disorientare MQ.

Gestire le patch in un repository

Dato che la directory .hg/patches di MQ risiede fuori dalla directory di lavoro di un repository Mercurial, il repository Mercurial «sottostante» non sa nulla della gestione o della presenza delle patch.

Questo presenta l’interessante possibilità di gestire i contenuti della directory delle patch come un repository Mercurial indipendente. Questo può essere un modo utile per lavorare. Per esempio, potete lavorare su una patch per un po’, aggiornarla tramite qrefresh, poi usare hg commit per registrare lo stato corrente della patch. Questo vi permette di «ritornare» a quella versione della patch più tardi.

Potete quindi condividere differenti versioni della stessa pila di patch tra molteplici repository sottostanti. Uso questa tecnica quando sto sviluppando una funzione del kernel di Linux. Ho una copia intatta dei miei sorgenti del kernel per ogni diversa architettura di CPU e un repository clonato su ognuna di queste architetture che contiene le patch su cui sto lavorando. Quando voglio collaudare una modifica su un’architettura differente, trasmetto le mie patch correnti al repository associato con il kernel di quell’architettura, estraggo e inserisco tutte le mie patch, infine assemblo e collaudo quel kernel.

Gestire le patch in un repository consente a più sviluppatori di lavorare sulla stessa serie di patch senza scontrarsi tra loro e basandosi su sorgenti sottostanti che potrebbero o non potrebbero essere sotto il loro controllo.

Il supporto di MQ per i repository di patch

MQ vi aiuta a lavorare con la directory .hg/patches in qualità di repository. Quando preparate un repository per lavorare con le patch usando qinit, potete passare l’opzione -c per creare la directory .hg/patches sotto forma di repository Mercurial.

[Nota]Nota

Se dimenticate di usare l’opzione -c, potete semplicemente posizionarvi nella directory .hg/patches in qualsiasi momento e invocare hg init. Non dimenticate, però, di aggiungere una voce per il file status al file .hgignore (hg qinit -c lo fa automaticamente per voi), perché il file status non andrebbe davvero amministrato.

Per convenienza, se MQ nota che la directory .hg/patches è un repository, userà automaticamente hg add per aggiungere ogni patch che create e importate.

MQ fornisce il comando abbreviato qcommit che esegue hg commit nella directory .hg/patches, per risparmiarvi noiose digitazioni.

Infine, sui sistemi Unix, potete definire l’alias mq come comando di convenienza per gestire la directory delle patch. Per esempio, sui sistemi Linux che usano la shell bash, potete aggiungere la riga seguente al vostro file ~/.bashrc.

alias mq=`hg -R $(hg root)/.hg/patches'

Potete poi invocare comandi della forma mq pull dal repository principale.

Alcune cose a cui fare attenzione

Il supporto di MQ per lavorare con un repository pieno di patch è limitato in alcuni aspetti di dettaglio.

MQ non può automaticamente scoprire quali modifiche avete fatto alla directory delle patch. Se usate hg pull, apportate cambiamenti a mano, o invocate hg update per aggiornare le modifiche alle patch o al file series, dovrete usare hg qpop -a e poi hg qpush -a nel repository sottostante per fare in modo che quelle modifiche compaiano anche là. Se dimenticate di fare questo, potreste confondere le idee a MQ in merito a quali patch sono state effettivamente applicate.

Strumenti di terze parti che lavorano con le patch

Una volta che avete lavorato con le patch per un po’, vi troverete desiderosi di utilizzare strumenti che vi aiutino a capire e manipolare le patch di cui vi state occupando.

Il comando diffstat [Dickey] genera un istogramma delle modifiche effettuate a ogni file in una patch. Fornisce un buon modo per «farsi un’idea» di una patch—quali file coinvolge e quante modifiche introduce a ogni file e nell’insieme. (Trovo che sia una buona idea usare regolarmente l’opzione -p di diffstat, poiché altrimenti il comando proverà a manipolare i prefissi dei nomi di file in un modo che almeno io trovo inevitabilmente confuso.)

$ diffstat -p1 rimuove-controlli-ridondati-su-null.patch
 drivers/char/agp/sgi-agp.c        |    5 ++---
 drivers/char/hvcs.c               |   11 +++++------
 drivers/message/fusion/mptfc.c    |    6 ++----
 drivers/message/fusion/mptsas.c   |    3 +--
 drivers/net/fs_enet/fs_enet-mii.c |    3 +--
 drivers/net/wireless/ipw2200.c    |   22 ++++++----------------
 drivers/scsi/libata-scsi.c        |    4 +---
 drivers/video/au1100fb.c          |    3 +--
 8 file modificati, 19 inserimenti(+), 38 cancellazioni(-)
$ filterdiff -i '*/video/*' rimuove-controlli-ridondati-su-null.patch
--- a/drivers/video/au1100fb.c~rimuove-controlli-ridondanti-su-null-prima-di-free-nei-driver
+++ a/drivers/video/au1100fb.c
@@ -743,8 +743,7 @@ void __exit au1100fb_cleanup(void)
 {
 	driver_unregister(&au1100fb_driver);
 
-	if (drv_info.opt_mode)
-		kfree(drv_info.opt_mode);
+	kfree(drv_info.opt_mode);
 }
 
 module_init(au1100fb_init);

Il pacchetto patchutils [Waugh] è inestimabile. Fornisce un insieme di piccole utilità che seguono la «filosofia Unix»: ognuna effettua una singola operazione utile su una patch. Il comando di patchutils che uso di più è filterdiff, che estrae sottoinsiemi di un file di patch. Per esempio, data una patch che modifica centinaia di file attraverso dozzine di directory, una singola invocazione di filterdiff può generare una patch più piccola che coinvolge solo i file il cui nome corrisponde a un particolare pattern di tipo glob. Leggete la sezione chiamata «Visualizzare la cronologia di una patch» per un altro esempio.

Strategie valide per lavorare con le patch

Sia che stiate lavorando su una serie di patch da sottoporre a un progetto software libero od open source, oppure su una serie che intendete trattare come una sequenza di normali changeset una volta che avete finito, potete usare alcune semplici tecniche per mantenere bene organizzato il vostro lavoro.

Date nomi descrittivi alle vostre patch. Un buon nome per una patch potrebbe essere riorganizza-allocazione-dispositivi.patch, perché vi suggerirà immediatamente qual è lo scopo della patch. I nomi lunghi non dovrebbero essere un problema: non digiterete i nomi spesso, ma invocherete comandi come qapplied e qtop più e più volte. Una buona denominazione diventa particolarmente importante quando state lavorando con un certo numero di patch, o se vi state destreggiando tra un certo numero di attività differenti e le vostre patch ottengono solo una frazione della vostra attenzione.

Siate consapevoli della patch su cui state lavorando. Usate frequentemente il comando qtop e date un’occhiata al testo delle vostre patch—per esempio, usando hg tip -p—per assicurarvi di sapere dove vi trovate. Mi è capitato molte volte di modificare e aggiornare una patch diversa da quella che intendevo, ed è spesso complicato trasferire le modifiche nella patch giusta dopo averle inserite in quella sbagliata.

Per questo motivo, vale davvero la pena di investire un po’ di tempo per imparare a usare alcuni degli strumenti di terze parti che ho descritto nella sezione chiamata «Strumenti di terze parti che lavorano con le patch», in particolare diffstat e filterdiff. Il primo vi darà velocemente un’idea di quali sono le modifiche effettuate dalla vostra patch, mentre il secondo vi renderà più facile selezionare blocchi particolari di una patch e inserirli in un’altra.

Il ricettario di MQ

Gestire patch «elementari»

Dato che il costo di aggiungere file in un nuovo repository Mercurial è così basso, ha molto senso gestire le patch in questo modo anche se volete semplicemente fare alcune modifiche a un archivo di sorgenti che avete scaricato.

Cominciate con lo scaricare l’archivio dei sorgenti, estraendone i contenuti e trasformandoli in un repository Mercurial.

# Scarichiamo netplug-1.2.5.tar.bz2
$ tar jxf netplug-1.2.5.tar.bz2
$ cd netplug-1.2.5
$ hg init
$ hg commit -q --addremove --message netplug-1.2.5
$ cd ..
$ hg clone netplug-1.2.5 netplug
aggiorno la directory di lavoro
18 file aggiornati, 0 file uniti, 0 file rimossi, 0 file irrisolti

Continuate creando una pila di patch e facendo le vostre modifiche.

$ cd netplug
$ hg qinit
$ hg qnew -m 'corregge un problema di assemblaggio con gcc 4' correzione-assemblaggio.patch
$ perl -pi -e 's/int addr_len/socklen_t addr_len/' netlink.c
$ hg qrefresh
$ hg tip -p
changeset:   1:5227ba4b6a8b
etichetta:   qtip
etichetta:   correzione-assemblaggio.patch
etichetta:   tip
etichetta:   qbase
utente:      Bryan O'Sullivan <[email protected]>
data:        Fri Jun 05 15:50:51 2009 +0000
sommario:    corregge un problema di assemblaggio con gcc 4

diff -r e709896f2959 -r 5227ba4b6a8b netlink.c
--- a/netlink.c	Fri Jun 05 15:50:49 2009 +0000
+++ b/netlink.c	Fri Jun 05 15:50:51 2009 +0000
@@ -275,7 +275,7 @@
         exit(1);
     }
 
-    int addr_len = sizeof(addr);
+    socklen_t addr_len = sizeof(addr);
 
     if (getsockname(fd, (struct sockaddr *) &addr, &addr_len) == -1) {
         do_log(LOG_ERR, "Could not get socket details: %m");

Diciamo che trascorrono alcune settimane o mesi e gli autori di quel pacchetto rilasciano una nuova versione. Prima di tutto, propagate i loro cambiamenti nel repository.

$ hg qpop -a
la coda delle patch è vuota
$ cd ..
# Scarichiamo netplug-1.2.8.tar.bz2
$ hg clone netplug-1.2.5 netplug-1.2.8
aggiorno la directory di lavoro
18 file aggiornati, 0 file uniti, 0 file rimossi, 0 file irrisolti
$ cd netplug-1.2.8
$ hg locate -0 | xargs -0 rm
$ cd ..
$ tar jxf netplug-1.2.8.tar.bz2
$ cd netplug-1.2.8
$ hg commit --addremove --message netplug-1.2.8

La coppia di comandi che comincia con hg locate appena invocata cancella tutti i file dalla directory di lavoro, in modo che l’opzione --addremove di hg commit possa effettivamente dirvi quali file sono stati davvero rimossi nella nuova versione dei sorgenti.

Infine, potete applicare le vostre patch al nuovo albero.

$ cd ../netplug
$ hg pull ../netplug-1.2.8
estraggo da ../netplug-1.2.8
cerco i cambiamenti
aggiungo i changeset
aggiungo i manifest
aggiungo i cambiamenti ai file
aggiunti 1 changeset con 12 cambiamenti a 12 file
(eseguite 'hg update' per ottenere una copia di lavoro)
$ hg qpush -a
(la directory di lavoro non è alla punta)
applico correzione-assemblaggio.patch
ora a: correzione-assemblaggio.patch

Combinare intere patch

MQ vi fornisce il comando qfold per consentirvi di combinare intere patch tra loro. Questo comando «include» le patch che nominate, nell’ordine in cui le nominate, nell’ultima patch applicata e concatena le loro descrizioni aggiungendole alla fine della descrizione di questa patch. Se le patch che includete sono applicate, devono essere estratte prima di poterle includere.

L’ordine in cui includete le patch è importante. Se la vostra ultima patch applicata è foo e voi utilizzate qfold per includervi bar e quux, otterrete una patch che opererà come se aveste applicato prima foo, poi bar, seguita da quux.

Unire parte di una patch a un’altra

Unire parte di una patch a un’altra patch è più difficile che combinare intere patch tra loro.

Se volete spostare alcune modifiche su interi file, potete usare le opzioni -i e -x di filterdiff per scegliere le modifiche che desiderate ricavare da una patch, aggiungendo il risultato del comando in coda alla patch a cui unire i cambiamenti. Di solito non avrete bisogno di modificare la patch da cui prelevate le modifiche da unire. Piuttosto, MQ rifiuterà alcune parti della patch quando invocate qpush su di essa (a causa dei blocchi che avete spostato nell’altra patch) e voi potrete semplicemente aggiornare la patch tramite qrefresh per scartare i blocchi duplicati.

Se avete una patch con più blocchi che modificano un file e volete spostare solo alcuni di questi blocchi, il lavoro diventa più complicato, ma potete comunque automatizzarlo parzialmente. Usate lsdiff -nvv per stampare alcuni metadati sulla patch.

$ lsdiff -nvv rimuove-controlli-ridondati-su-null.patch
22	File #1  		a/drivers/char/agp/sgi-agp.c
	24	Blocco #1	static int __devinit agp_sgi_init(void)
37	File #2  		a/drivers/char/hvcs.c
	39	Blocco #1	static struct tty_operations hvcs_ops = 
	53	Blocco #2	static int hvcs_alloc_index_list(int n)
69	File #3  		a/drivers/message/fusion/mptfc.c
	71	Blocco #1	mptfc_GetFcDevPage0(MPT_ADAPTER *ioc, in
85	File #4  		a/drivers/message/fusion/mptsas.c
	87	Blocco #1	mptsas_probe_hba_phys(MPT_ADAPTER *ioc)
98	File #5  		a/drivers/net/fs_enet/fs_enet-mii.c
	100	Blocco #1	static struct fs_enet_mii_bus *create_bu
111	File #6  		a/drivers/net/wireless/ipw2200.c
	113	Blocco #1	static struct ipw_fw_error *ipw_alloc_er
	126	Blocco #2	static ssize_t clear_error(struct device
	140	Blocco #3	static void ipw_irq_tasklet(struct ipw_p
	150	Blocco #4	static void ipw_pci_remove(struct pci_de
164	File #7  		a/drivers/scsi/libata-scsi.c
	166	Blocco #1	int ata_cmd_ioctl(struct scsi_device *sc
178	File #8  		a/drivers/video/au1100fb.c
	180	Blocco #1	void __exit au1100fb_cleanup(void)

Questo comando stampa tre tipi diversi di numeri:

  • (nella prima colonna) un numero di file per identificare ogni file modificato dalla patch;

  • (sulla riga seguente, indentato) il numero di riga del file modificato dove comincia il blocco;

  • (sulla stessa riga) un numero di blocco per identificare quel blocco.

Dovrete leggere e ispezionare visivamente la patch per identificare i numeri di file e di blocco che volete, ma poi potrete passarli alle opzioni --files e --hunks di filterdiff per selezionare esattamente quel file e il blocco che volete estrarre.

Una volta che avete questo blocco, potete aggiungerlo in coda alla vostra patch di destinazione e continuare con il resto della sezione chiamata «Combinare intere patch».

Differenze tra quilt e MQ

Se avete già familiarità con quilt, MQ fornisce un insieme di comandi simile. Ci sono alcune differenze nel modo in cui questi comandi lavorano.

Avrete già notato che la maggior parte dei comandi di quilt hanno una controparte MQ che comincia semplicemente con una «q». Le eccezioni sono i comandi add e remove di quilt, le cui controparti sono i normali comandi Mercurial hg add e hg remove. Non c’è alcun comando MQ equivalente al comando quilt edit.

Volete rimanere aggiornati? Abbonatevi al feed delle modifiche per il libro italiano.

Copyright 2006, 2007, 2008, 2009 Bryan O’Sullivan. Icone realizzate da Paul Davey alias Mattahan.

Copyright 2009 Giulio Piancastelli per la traduzione italiana.