Indice
Mercurial vi offre un potente meccanismo basato sui template (letteralmente, modelli) per controllare il modo in cui visualizza le informazioni. Potete usare i template per generare una specifica presentazione dei risultati di un singolo comando, o per personalizzare l’intero aspetto dell’interfaccia web predefinita.
Mercurial include alcuni stili di formattazione che potete usare immediatamente. Uno stile è semplicemente un template già pronto che qualcuno ha scritto e installato in una posizione nota a Mercurial.
Prima di dare un’occhiata agli stili distribuiti con Mercurial, rivediamo il normale risultato di un suo comando.
$
hg log -r1
changeset: 1:fb5e3583537a etichetta: miaetichetta utente: Bryan O'Sullivan <[email protected]> data: Fri Jun 05 15:51:24 2009 +0000 sommario: Aggiunta una riga alla fine del file <<hello>>.
Questo messaggio ci dà alcune informazioni, ma porta via molto spazio—cinque righe per ogni changeset. Lo stile compact
riduce questo spazio a tre righe, presentate in maniera sparsa.
$
hg log --style compact
3[tip] 1102dd469cfc 2009-06-05 15:51 +0000 bos Aggiunta etichetta v0.1 per il changeset a5ff5617a0be 2[v0.1] a5ff5617a0be 2009-06-05 15:51 +0000 bos Aggiunta etichetta miaetichetta per il changeset fb5e3583537a 1[miaetichetta] fb5e3583537a 2009-06-05 15:51 +0000 bos Aggiunta una riga alla fine del file <<hello>>. 0 0afbebcdeafc 2009-06-05 15:51 +0000 bos Aggiunto file hello.
Lo stile changelog
ci dà un’idea di quale sia il potere espressivo del motore di template di Mercurial. Questo stile tenta di seguire le linee guida per la formattazione di un registro dei cambiamenti stabilite dal progetto GNU [GNU-Standard].
$
hg log --style changelog
2009-06-05 Bryan O'Sullivan <[email protected]> * .hgtags: Aggiunta etichetta v0.1 per il changeset a5ff5617a0be [1102dd469cfc] [tip] * .hgtags: Aggiunta etichetta miaetichetta per il changeset fb5e3583537a [a5ff5617a0be] [v0.1] * goodbye, hello: Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno possa considerarlo tale) di goodbye. [fb5e3583537a] [miaetichetta] * hello: Aggiunto file hello. [0afbebcdeafc]
Non vi sorprenderà sapere che lo stile di formattazione predefinito di Mercurial è chiamato default
.
Potete modificare lo stile di formattazione che Mercurial userà per ogni comando aggiungendo al vostro file ~/.hgrc
il nome dello stile che preferireste usare.
[ui] style = compact
Se create un vostro stile, potete usarlo inserendo il percorso del vostro file di stile, oppure copiando il vostro file di stile in un luogo dove Mercurial possa trovarlo (tipicamente la sottodirectory templates
della vostra directory di installazione di Mercurial).
Tutti i comandi Mercurial di tipo log
vi permettono di usare stili e template: hg incoming, hg log, hg outgoing e hg tip.
Al momento di scrivere questo manuale, quelli elencati sono i comandi che finora supportano stili e template. Dato che questi sono i comandi più importanti per i quali è necessaria una formattazione personalizzabile, la comunità utenti di Mercurial non ha fatto molta pressione per aggiungere il supporto per stili e template ad altri comandi.
Nella sua forma più semplice, un template Mercurial è un frammento di testo. Parte del testo non cambia mai, mentre altre parti vengono espanse, cioè sostituite con nuovo testo, quando è necessario.
Prima di continuare, diamo un’altra occhiata al semplice esempio del normale risultato di un comando Mercurial.
$
hg log -r1
changeset: 1:fb5e3583537a etichetta: miaetichetta utente: Bryan O'Sullivan <[email protected]> data: Fri Jun 05 15:51:24 2009 +0000 sommario: Aggiunta una riga alla fine del file <<hello>>.
Ora, eseguiamo lo stesso comando, ma usando un template per cambiare il messaggio visualizzato.
$
hg log -r1 --template 'ho visto un changeset\n'
ho visto un changeset
Questo esempio illustra il template più semplice possibile, composto solo da un messaggio di testo statico stampato una volta per ogni changeset. L’opzione --template
del comando hg log dice a Mercurial di usare il testo dato come template per stampare ogni changeset.
Notate che la stringa di template appena usata termina con il testo «\n
». Questa è una sequenza di escape che dice a Mercurial di stampare una carattere di nuova riga alla fine di ogni elemento di template. Se omettete questa nuova riga, Mercurial mostrerà un messaggio di testo di seguito all’altro. Leggete la sezione chiamata «Sequenze di escape» per maggiori dettagli sulle sequenze di escape.
Un template che stampa una stringa di testo fissa tutte le volte non è molto utile, perciò proviamo qualcosa di un po’ più complesso.
$
hg log --template 'ho visto un changeset: {desc}\n'
ho visto un changeset: Aggiunta etichetta v0.1 per il changeset a5ff5617a0be ho visto un changeset: Aggiunta etichetta miaetichetta per il changeset fb5e3583537a ho visto un changeset: Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno possa considerarlo tale) di goodbye. ho visto un changeset: Aggiunto file hello.
Come potete vedere, la stringa «{desc}
» nel template è stata sostituita con la descrizione di ogni changeset nel messaggio. Ogni volta che Mercurial trova un testo racchiuso tra parentesi graffe («{
» e «}
»), proverà a sostituire le parentesi e il testo con l’espansione di qualunque cosa vi sia contenuta. Per stampare una parentesi graffa letterale dovete effettuarne l’escape, come descritto nella sezione chiamata «Sequenze di escape».
Potete cominciare immediatamente a scrivere semplici template usando le seguenti parole chiave.
author
: stringa. Il nome non modificato dell’autore del changeset.
branches
: stringa. Il nome del ramo su cui il changeset è stato inserito. Sarà vuoto se il nome del ramo è default
.
date
: informazioni di data. La data in cui il changeset è stato inserito. Questa informazione non è rappresentata in maniera comprensibile, bensì dovete passarla attraverso un filtro per presentarla in maniera appropriata. Leggete la sezione chiamata «Filtrare le parole chiave per modificarne i risultati» per maggiori informazioni sui filtri. La data viene espressa come una coppia di numeri. Il primo numero è una marcatura temporale che segue l’UTC Unix (e indica il numero di secondi trascorsi dal 1° gennaio 1970); il secondo è la differenza tra il fuso orario dell’autore del commit e l’UTC, espressa in secondi.
files
: lista di stringhe. Tutti i file modificati, aggiunti, o rimossi da questo changeset.
file_adds
: lista di stringhe. I file aggiunti da questo changeset.
file_dels
: lista di stringhe. I file rimossi da questo changeset.
node
: stringa. L’hash di identificazione del changeset, sotto forma di una stringa esadecimale di 40 caratteri.
rev
: intero. Il numero di revisione del changeset locale per il repository.
tags
: lista di stringhe. Qualsiasi etichetta associata al changeset.
Alcuni semplici esperimenti ci mostreranno cosa aspettarci quando usiamo queste parole chiave. Potete vederne i risultati qui di seguito.
$
hg log -r1 --template 'autore: {author}\n'
autore: Bryan O'Sullivan <[email protected]>$
hg log -r1 --template 'desc:\n{desc}\n'
desc: Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno possa considerarlo tale) di goodbye.$
hg log -r1 --template 'file: {files}\n'
file: goodbye hello$
hg log -r1 --template 'file aggiunti: {file_adds}\n'
file aggiunti: goodbye$
hg log -r1 --template 'file rimossi: {file_dels}\n'
file rimossi:$
hg log -r1 --template 'nodo: {node}\n'
nodo: fb5e3583537ab9d278f45d18bcb07262af1e7226$
hg log -r1 --template 'genitori: {parents}\n'
genitori:$
hg log -r1 --template 'revisione: {rev}\n'
revisione: 1$
hg log -r1 --template 'etichette: {tags}\n'
etichette: miaetichetta
Come abbiamo notato prima, la parola chiave per la data non produce un risultato comprensibile, così dobbiamo trattarla in maniera speciale. Questo implica l’uso dei filtri, che verranno trattati in maniera più approfondita nella sezione chiamata «Filtrare le parole chiave per modificarne i risultati».
$
hg log -r1 --template 'data: {date}\n'
data: 1244217084.00$
hg log -r1 --template 'data: {date|isodate}\n'
data: 2009-06-05 15:51 +0000
Il motore di template di Mercurial riconosce le sequenze di escape più comunemente usate nelle stringhe. Quando trova un carattere di backslash («\
»), esamina il carattere successivo e rimpiazza i due caratteri con un unico sostituto, come descritto qui di seguito.
Come appena indicato, se volete che l’espansione di un template contenga un carattere «\
», «{
», o «{
» letterale, dovete effettuarne l’escape.
Alcuni dei risultati dell’espansione dei template non sono immediatamente facili da usare. Mercurial vi permette di specificare una catena opzionale di filtri per modificare il risultato dell’espansione di una parola chiave. Avete già visto in azione un filtro comune, isodate
, usato precedentemente per rendere leggibile una data.
Qui di seguito viene presentata una lista dei filtri più comunemente usati che Mercurial supporta. Mentre alcuni filtri possono essere applicati a qualunque testo, altri possono essere usati solo in circostanze specifiche. Il nome di ogni filtro è seguito prima da un’indicazione del contesto in cui può essere usato e poi da una descrizione dei suoi effetti.
addbreaks
: qualunque testo. Aggiunge un elemento XHTML «<br/>
» prima della fine di ogni riga tranne l’ultima. Per esempio, «foo\nbar
» diventa «foo<br/>\nbar
».
age
: parola chiave date
. Rappresenta l’età della data, relativa all’ora corrente. Produce stringhe come «10 minuti
».
basename
: qualunque testo, ma utile soprattutto per la parola chiave files
e simili. Tratta il testo come un percorso e restituisce il nome di base. Per esempio, «foo/bar/baz
» diventa «baz
».
date
: parola chiave date
. Presenta una data in un formato simile al comando Unix date
, ma includendo il fuso orario. Produce stringhe come «Mon Sep 04 15:13:13 2006 -0700
».
domain
: qualunque testo, ma utile soprattutto per la parola chiave author
. Trova la prima stringa che somiglia a un indirizzo email e ne estrae il componente del dominio. Per esempio, «Bryan O'Sullivan <[email protected]>
» diventa «serpentine.com
».
email
: qualunque testo, ma utile soprattutto per la parola chiave author
. Estrae la prima stringa che somiglia a un indirizzo email. Per esempio, «Bryan O'Sullivan <[email protected]>
» diventa «[email protected]
».
escape
: qualunque testo. Sostituisce i caratteri speciali XML/XHTML «&
», «<
» e «>
» con entità XML.
fill68
: qualunque testo. Manda a capo il testo per farlo stare in 68 colonne. Questo filtro è utile da applicare prima di combinarlo con il filtro tabindent
, se volete che il testo non esca dai bordi di una finestra di 80 colonne con caratteri a spaziatura fissa.
fill76
: qualunque testo. Manda a capo il testo per farlo stare in 76 colonne.
firstline
: qualunque testo. Produce la prima riga del testo, senza alcun carattere di nuova riga alla fine.
hgdate
: parola chiave date
. Rappresenta la data come una coppia di numeri leggibili. Produce una stringa come «1157407993 25200
».
isodate
: parola chiave date
. Rappresenta una data come stringa di testo in formato ISO 8601. Produce una stringa come «2006-09-04 15:13:13 -0700
».
obfuscate
: qualunque testo, ma utile soprattutto per la parola chiave author
. Riproduce il testo in ingresso rappresentandolo come una sequenza di entità XML. Questo è utile per impedire ad alcuni programmi particolarmente stupidi utilizzati dagli spammer per raccogliere indirizzi email di copiare i dati destinati a essere visualizzati su schermo.
person
: qualunque testo, ma utile soprattutto per la parola chiave author
. Produce il testo che precede un indirizzo email. Per esempio, «Bryan O'Sullivan <[email protected]>
» diventa «Bryan O'Sullivan
».
rfc822date
: parola chiave date
. Rappresenta una data usando lo stesso formato impiegato nelle intestazioni email. Produce una stringa come «Mon, 04 Sep 2006 15:13:13 -0700
».
short
: hash di changeset. Produce la forma breve di un hash di changeset, cioè una stringa esadecimale di 12 caratteri.
shortdate
: parola chiave date
. Rappresenta l’anno, il mese e il giorno della data. Produce una stringa come «2006-09-04
».
strip
: qualunque testo. Rimuove lo spazio bianco all’inizio e alla fine di una stringa.
tabindent
: qualunque testo. Produce il testo, facendo cominciare ogni riga tranne la prima con un carattere di tabulazione.
urlescape
: qualunque testo. Effettua l’escape di tutti i caratteri che sono considerati «speciali» dai riconoscitori di URL. Per esempio, foo bar
diventa foo%20bar
.
user
: qualunque testo, ma utile soprattutto per la parola chiave author
. Restituisce la porzione dell’«utente» di un indirizzo email. Per esempio «Bryan O'Sullivan <[email protected]>
» diventa «bos
».
$
hg log -r1 --template '{author}\n'
Bryan O'Sullivan <[email protected]>$
hg log -r1 --template '{author|domain}\n'
serpentine.com$
hg log -r1 --template '{author|email}\n'
[email protected]$
hg log -r1 --template '{author|obfuscate}\n' | cut -c-76
Bryan O'Sulli$
hg log -r1 --template '{author|person}\n'
Bryan O'Sullivan$
hg log -r1 --template '{author|user}\n'
bos$
hg log -r1 --template 'sembra quasi giusta, ma in realtà è inutilizzabile: {date}\n'
sembra quasi giusta, ma in realtà è inutilizzabile: 1244217084.00$
hg log -r1 --template '{date|age}\n'
10 secondi$
hg log -r1 --template '{date|date}\n'
Fri Jun 05 15:51:24 2009 +0000$
hg log -r1 --template '{date|hgdate}\n'
1244217084 0$
hg log -r1 --template '{date|isodate}\n'
2009-06-05 15:51 +0000$
hg log -r1 --template '{date|rfc822date}\n'
Fri, 05 Jun 2009 15:51:24 +0000$
hg log -r1 --template '{date|shortdate}\n'
2009-06-05$
hg log -r1 --template '{desc}\n' | cut -c-76
Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno$
hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76
Aggiunta una riga alla fine del file <<hello>>.<br/> <br/> In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno$
hg log -r1 --template '{desc|escape}\n' | cut -c-76
Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno$
hg log -r1 --template '{desc|fill68}\n'
Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno possa considerarlo tale) di goodbye.$
hg log -r1 --template '{desc|fill76}\n'
Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno possa considerarlo tale) di goodbye.$
hg log -r1 --template '{desc|firstline}\n'
Aggiunta una riga alla fine del file <<hello>>.$
hg log -r1 --template '{desc|strip}\n' | cut -c-76
Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno$
hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76
Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qu$
hg log -r1 --template '{node}\n'
fb5e3583537ab9d278f45d18bcb07262af1e7226$
hg log -r1 --template '{node|short}\n'
fb5e3583537a
È facile combinare filtri per produrre un testo formattato nel modo che preferite. La seguente catena di filtri ripulisce una descrizione, poi si assicura che stia tranquillamente in 68 colonne, infine la indenta ulteriormente di 8 caratteri (almeno sui sistemi di tipo Unix, dove una tabulazione è convenzionalmente larga 8 caratteri).
$
hg log -r1 --template 'descrizione:\n\t{desc|strip|fill68|tabindent}\n'
descrizione: Aggiunta una riga alla fine del file <<hello>>. In più, aggiunto un file con il nome indicativo (almeno spero che qualcuno possa considerarlo tale) di goodbye.
Notate l’uso di «\t
» (un carattere di tabulazione) nel template per indentare la prima riga, necessario dato che tabindent
indenta tutte le righe tranne la prima.
Tenete a mente che l’ordine dei filtri in una catena è significativo. Il primo filtro viene applicato al risultato della parola chiave, il secondo al risultato del primo filtro, e così via. Per esempio, usare fill68|tabindent
dà risultati molto diversi rispetto a tabindent|fill68
.
Un template a riga di comando fornisce un modo semplice e veloce per formattare il risultato di un certo comando. Ma i template possono diventare prolissi, quindi è utile essere in grado di dare un nome a un template. Un file di stile è un template con un nome, memorizzato in un file.
Ma soprattutto, l’impiego di un file di stile sfrutta la potenza del motore di template di Mercurial in modi che non sono possibili usando l’opzione --template
a riga di comando.
Il nostro semplice file di stile contiene solo una riga:
$
echo 'changeset = "revisione: {rev}\n"' > rev
$
hg log -l1 --style ./rev
revisione: 3
Questo dice a Mercurial: «se stai stampando un changeset, usa il testo sulla destra come template».
Le regole della sintassi per un file di stile sono semplici.
Gli spazi bianchi all’inizio e alla fine di una riga vengono ignorati.
Se una riga comincia con un carattere «#
» o «;
», l’intera riga viene trattata come un commento e saltata come se fosse vuota.
Una riga comincia con una parola chiave, che deve iniziare con un carattere alfabetico o di sottolineatura e successivamente può contenere qualsiasi carattere alfanumerico o di sottolineatura. (Nella notazione per le espressioni regolari, una parola chiave deve corrispondere a [A-Za-z_][A-Za-z0-9_]*
.)
L’elemento successivo deve essere un carattere «=
», che può essere preceduto o seguito da una quantità arbitraria di spazio bianco.
Se il resto della riga comincia e finisce con caratteri corrispettivi di apice o di virgolette, viene trattato come il corpo di un template.
Se il resto della riga non comincia con caratteri di apice o di virgolette, viene trattato come il nome di un file i cui contenuti saranno letti e usati come il corpo di un template.
Per illustrare come scrivere un file di stile, ne costruiremo alcuni esempi. Piuttosto che fornire un file di stile completo e ripercorrerlo passo per passo, replicheremo il classico processo di sviluppo di un file di stile cominciando con qualcosa di molto semplice e proseguendo attraverso una serie di esempi successivi più completi.
Se Mercurial incontra un problema in un file di stile su cui state lavorando, stampa uno stringato messaggio di errore che si rivela in effetti piuttosto utile una volta scoperto cosa significa.
$
cat stile.errato
changeset =
Notate che stile.errato
tenta di definire una parola chiave changeset
, ma dimentica di darle un contenuto qualsiasi. Quando gli si chiede di usare questo file di stile, Mercurial si lamenta prontamente.
$
hg log -r1 --style stile.errato
fallimento: stile.errato:1: errore di riconoscimento
Questo messaggio di errore sembra minaccioso, ma non è troppo difficile da seguire.
Il primo componente è semplicemente il modo in cui Mercurial dice «rinuncio».
___fallimento___: stile.errato:1: errore di riconoscimento
Subito dopo, trovate il nome del file di stile che contiene l’errore.
fallimento: ___stile.errato___:1: errore di riconoscimento
Il nome del file è seguito dal numero di riga dove l’errore è stato incontrato.
fallimento: stile.errato:___1___: errore di riconoscimento
Infine, viene fornita una descrizione di quello che è andato storto.
fallimento: stile.errato:1: ___errore di riconoscimento___
La descrizione del problema non è sempre chiara (come in questo caso) ma, anche quando è criptica, è quasi sempre banale trovare la causa dell’errore inspezionando visivamente la riga del file di stile che contiene il problema.
Se volete essere in grado di identificare un repository Mercurial in maniera «abbastanza univoca» usando una breve stringa come identificatore, potete usare la prima revisione contenuta nel repository.
$
hg log -r0 --template '{node}'
6d6d6f73864f8fc2d56e1f788c751e0445bdb13e
È molto probabile che questo identificatore sia unico, quindi si rivela utile in molti casi. Ci sono alcune avvertenze.
Questa tecnica non funzionerà in un repository completamente vuoto, perché un tale repository non possiede la revisione zero.
Questa tecnica non funzionerà nemmeno nel caso (estremamente raro) in cui un repository sia l’unione di due o più repository precedentemente indipendenti e quei repository siano ancora nei paraggi.
Ecco alcuni usi che potete fare di questo identificatore:
come chiave nella tabella di un database che gestisce i repository presenti su un server;
come metà di una tupla {identificatore di repository, identificatore di revisione}. Salvate questa informazione da qualche parte quando eseguite un assemblaggio automatico o un’altra attività simile, in modo che possiate «rieseguire» lo stesso assemblaggio in seguito se necessario.
Supponete di voler elencare i file modificati da un changeset uno per riga, aggiungendo una piccola indentazione prima di ogni nome di file.
$
cat > multiriga << EOF
>
changeset = "Modificati in {node|short}:\n{files}"
>
file = " {file}\n"
>
EOF
$
hg log --style multiriga
Modificati in 7daf1d1b51e4: .bashrc .hgrc test.c
Proviamo a emulare il formato predefinito usato da un altro strumento di controllo di revisione, Subversion, per mostrare le voci del proprio registro.
$
svn log -r9653
------------------------------------------------------------------------ r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 6 righe Indicando un errore di connessione, includi anche il codice di stato per l'errore, piuttosto che usare un codice di stato pari a 0 quando è avvenuto un errore. Firmato-da: Sean Hefty <[email protected]> ------------------------------------------------------------------------
Dato che lo stile della rappresentazione di Subversion è abbastanza semplice, è facile copiare e incollare uno dei suoi messaggi in un file e rimpiazzare il testo prodotto da Subversion con i valori di template che vorremmo vedere espansi.
$
cat svn.template
r{rev} | {author|user} | {date|isodate} ({date|rfc822date}) {desc|strip|fill76} ------------------------------------------------------------------------
Questo template si discosta in alcuni modi dalla presentazione prodotta da Subversion.
Subversion stampa una data «leggibile» (il «Wed, 27 Sep 2006
» nel risultato dell’esempio precedente) tra parentesi. Il motore di template di Mercurial non fornisce un modo per visualizzare una data in questo formato senza stampare anche l’ora e il fuso orario.
Emuliamo la stampa di righe «separatrici» piene di caratteri «-
» da parte di Subversion concludendo il template con una riga di quel tipo. Usiamo la parola chiave header
del motore di template per stampare una riga separatrice come prima riga (vedete più avanti), quindi ottenendo un risultato simile a quello di Subversion.
Il formato di Subversion include nell’intestazione il conteggio del numero di righe del messaggio di commit. Non possiamo replicare questa caratteristica in Mercurial, poiché attualmente il motore di template non fornisce un filtro che conti il numero di righe generate dal template.
Non mi ci sono voluti più di uno o due minuti di lavoro per sostituire il testo letterale di un esempio del messaggio di Subversion con alcune parole chiave e alcuni filtri per ottenere il template appena visto. Il file di stile fa semplicemente riferimento al template.
$
cat svn.stile
header = '------------------------------------------------------------------------\n\n' changeset = svn.template
Avremmo potuto includere il testo del file di template direttamente nel file di stile, circondandolo con virgolette e rimpiazzando le nuove righe con sequenze «\n
», ma questo avrebbe reso il file di stile troppo difficile da leggere. La leggibilità è un buon criterio da cui farsi guidare per decidere se un certo testo appartiene a un file di stile o a un file di template a cui il file di stile fa riferimento. Nel caso il file di stile vi sembri troppo grande o disordinato se inserite un frammento letterale di testo, allora spostate il testo in un template.