Guida del Committer
Indietro |  | Avanti

# 3 Operazioni sul CVS

Si assume che tu abbia già familiarità con le operazioni di base di CVS.

I CVS Repository Meisters `<cvsadm@FreeBSD.org>` sono i “proprietari” del repository CVS e sono responsabili delle sue modifiche dirette allo scopo di ripulire o sistemare dei gravi abusi di CVS da parte di un committer. Nel caso dovessi causare qualche problema al repository, diciamo una errata operazione di `cvs import` o `cvs tag`, invia un messaggio al membro responsabile fra i CVS Repository Meisters `<cvsadm@FreeBSD.org>`, come stabilito nella tabella qui sotto, (o chiama uno di loro) ed esponi il problema. Per questioni molto importanti che interessano l'intero albero CVS--non solo un'area specifica--puoi contattare i CVS Repository Meisters `<cvsadm@FreeBSD.org>`. Non contattare i CVS Repository Meisters `<cvsadm@FreeBSD.org>` per copie di repository o altre cose che possono gestire i team più specifici.

Gli unici che hanno il permesso di manipolare direttamente i bit del repository sono i “repomeister”. Per questo non ci sono shell di login disponibili sulle macchine del repository, tranne che per i repomeister.

> Nota: A seconda dell'area interessata del repository CVS, dovresti mandare la tua richiesta a uno dei seguenti indirizzi email:

> - ncvs@ - a proposito di `/home/ncvs`, il repository dei src

> - pcvs@ - a proposito di `/home/pcvs`, il repository dei port

> - dcvs@ - a proposito di `/home/dcvs`, il repository dei doc

> - projcvs@ - a proposito di `/home/projcvs`, il repository dei progetti di terze parti

L'albero CVS è attualmente diviso in quattro repository differenti, ovvero `doc`, `ports`, `projects` e `src`. Questi vengono ricomposti sotto un unico `CVSROOT` quando vengono distribuiti tramite CVSup per la convenienza dei nostri utenti.

> Nota: Nota che il modulo `www` che contiene i sorgenti del sito web di FreeBSD è contenuto all'interno del repository `doc`.

I repository CVS sono ospitati sulle macchine repository. Attualmente, ognuno dei repository elencati qui sopra risiede sulla stessa macchina fisica, `ncvs.FreeBSD.org`, ma per permettere la possibilità di averne ognuno su una macchina diversa in futuro, ci sono diversi nomi di host che i committer dovrebbero utilizzare. Inoltre, ogni repository risiede in una directory differente. La seguente tabella racchiude la situazione.

Tabella 1. Repository CVS, Host e Directory di FreeBSD

Repository | Host | Directory
--- | --- | ---
doc | dcvs.FreeBSD.org | /home/dcvs
ports | pcvs.FreeBSD.org | /home/pcvs
projects | projcvs.FreeBSD.org | /home/projcvs
src | ncvs.FreeBSD.org | /home/ncvs

Le operazioni sul CVS sono fatte da remoto impostando la variabile di ambiente `CVSROOT` a `ncvs.FreeBSD.org``:``/home/ncvs` e la variabile `CVS_RSH` a `ssh`, e quindi effettuando le appropriate operazioni di check-out/check-in. Molti committer definiscono degli alias che si espandono nella corretta invocazione di cvs per il repository appropriato. Per esempio, un utente di tcsh(1) può aggiungere le seguenti righe al suo `.cshrc` per questo scopo:

    alias dcvs env CVS_RSH=ssh cvs -d user@dcvs.FreeBSD.org:/home/dcvs
    alias pcvs env CVS_RSH=ssh cvs -d user@pcvs.FreeBSD.org:/home/pcvs
    alias projcvs env CVS_RSH=ssh cvs -d user@projcvs.FreeBSD.org:/home/projcvs
    alias scvs env CVS_RSH=ssh cvs -d user@ncvs.FreeBSD.org:/home/ncvs

In questo modo è possibile fare tutte le operazioni di CVS localmente ed usare ``X`cvs commit` per effettuare il commit sull'albero CVS ufficiale. Se desideri aggiungere qualcosa di totalmente nuovo (ad esempio dei sorgenti in contrib, ecc.), deve essere usato `cvs import`. Guarda come riferimento la pagina man di cvs(1) per l'utilizzo.

> Nota: Per favore non usare `cvs checkout` o `update` con la macchina con il repository ufficiale impostata come CVS Root per tenere aggiornato il tuo albero dei sorgenti. CVS da remoto non è ottimizzato per la distribuzione via rete e richiede un grande sovraccarico di lavoro e di amministrazione sul lato server. Utilizza il nostro metodo di distribuzione avanzato `cvsup` per ottenere i bit del repository, ed esegui solamente l'operazione di `commit` sull'host con il repository. Forniamo un'estesa rete di mirror cvsup per questo scopo, così come diamo accesso al `cvsup-master` se hai veramente bisogno di essere aggiornato alle ultime modifiche. Il `cvsup-master` ha la potenza necessaria a gestire questa cosa, il repository principale no. Jun Kuriyama `<kuriyama@FreeBSD.org>` è a capo del `cvsup-master`.

Se devi usare le operazioni `add` e `delete` di CVS come se fosse un'operazione mv(1), allora va effettuata una copia nel repository piuttosto che usare `add` e `delete` di CVS. In una copia nel repository, un CVS Meister copierà il/i file nei loro nuovi nomi e/o locazioni e ti avviserà ad operazione avvenuta. Lo scopo di una copia del repository è di preservare la cronologia dei cambiamenti del file, o i log. Noi del FreeBSD Project diamo molta importanza alla cronologia dei cambiamenti che CVS fornisce al progetto.

Informazioni di riferimento, tutorial, e FAQ su CVS possono essere trovate su: http://www.cvshome.org/docs/. Anche le informazioni contenute nei capitoli di Karl Fogel da “Open Source Development with CVS” sono molto utili.

Dag-Erling C. Smørgrav `<des@FreeBSD.org>` ha fornito inoltre il seguente “mini manuale” su CVS.

1. Effettua il check out di un modulo con il comando `co` o `checkout`.

       % cvs checkout shazam

   Questo estrae una copia del modulo `shazam`. Se non c'è alcun modulo `shazam` nel file dei moduli, cercherà allora una directory di primo livello chiamata `shazam`.

   Tabella 2. Opzioni utili con `cvs checkout`

   `-P` | Non crea le directory vuote
   `-l` | Estrae solo un livello, non le sottodirectory
   `-r`ver`` | Estrai la versione, il ramo, o il tag `ver`
   `-D`data`` | Estrai i sorgenti com'erano in data `data`

   Esempi pratici su FreeBSD:

   - Estrai il modulo `miscfs`, che corrisponde a `src/sys/miscfs`:

         % cvs co miscfs

     Ora hai una directory chiamata `miscfs` con le sottodirectory `CVS`, `deadfs`, `devfs`, e così via. Una di queste (`linprocfs`) è vuota.

   - Estrai gli stessi file, ma con il percorso completo:

         % cvs co src/sys/miscfs

     Ora hai una directory chiamata `src`, con le sottodirectory `CVS` e `sys`. La directory `src/sys` ha le sottodirectory `CVS` e `miscfs`, ecc.

   - Estrai gli stessi file, ma elimina le directory vuote:

         % cvs co -P miscfs

     Ora hai una directory chiamata `miscfs` con le sottodirectory `CVS`, `deadfs`, `devfs`... ma nota che non c'è nessuna sottodirectory `linprocfs`, perché non contiene alcun file.

   - Estrai la directory `miscfs`, ma nessuna delle sue sottodirectory:

         % cvs co -l miscfs

     Ora hai una a directory chiamata `miscfs` con solo una sottodirectory chiamata `CVS`.

   - Estrai il modulo `miscfs` com'è nel ramo 4.X:

         % cvs co -rRELENG_4 miscfs

     Puoi modificare i sorgenti ed effettuare il commit su questo ramo.

   - Estrai il modulo `miscfs` com'era nella 3.4-RELEASE.

         % cvs co -rRELENG_3_4_0_RELEASE miscfs

     Non potrai effettuare il commit delle modifiche, visto che `RELENG_3_4_0_RELEASE` corrisponde ad un preciso istante di tempo, non a un ramo.

   - Estrai il modulo `miscfs` com'era il 15 gennaio 2000.

         % cvs co -D'01/15/2000' miscfs

     Non potrai effettuare modifiche.

   - Estrai il modulo `miscfs` com'era una settimana fa.

         % cvs co -D'last week' miscfs

     Non potrai effettuare modifiche.

   Tieni presente che cvs salva i metadati in sottodirectory chiamate `CVS`.

   Gli argomenti di `-D` e `-r` sono fissi, che vuol dire che cvs se li ricorderà in seguito, ad esempio quando farai un `cvs update`.

2. Controlla lo stato dei file estratti con il comando `status`.

       % cvs status shazam

   Questo visualizza lo stato del file `shazam` o di ogni file nella directory `shazam`. Per ogni file, lo stato è uno fra:

   Up-to-date | Il file à aggiornato e non è stato modificato.
   Needs Patch | Il file non è stato modificato, ma c'è una nuova versione nel repository.
   Locally Modified | Il file è aggiornato, ma è stato modificato.
   Needs Merge | Il file è stato modificato, e c'è una nuova versione nel repository.
   File had conflicts on merge | Ci sono stati conflitti l'ultima volta che il file è stato aggiornato, e non sono ancora stati risolti.

   Vedrai anche la versione e la data locale, il numero dell'ultima versione appropriata (“ultima appropriata” perché se hai una data, un tag o un ramo fissati, può non essere l'ultima versione), e i tag, le date o le opzioni applicate.

3. Dopo avere estratto qualcosa, puoi aggiornarlo con il comando `update`.

       % cvs update shazam

   Questo aggiorna il file `shazam` o il contenuto della directory `shazam` all'ultima versione sul ramo che hai estratto. Se hai estratto un “preciso instante di tempo”, non fa nulla a meno che i tag non siano stati spostati nel repository o qualche altra strana cosa sia in corso.

   Opzioni utili, in aggiunta a quelle elencate sopra, con `checkout`:

   `-d` | Estrae ogni directory aggiuntiva mancante.
   `-A` | Scarica l'ultima versione del ramo principale.
   `-j`ver`` | Altre magie (guarda sotto).

   Se hai estratto un modulo con `-r` o `-D`, l'esecuzione di `cvs update` con un argomento differente di `-r` o `-D` o con `-A` selezionerà un nuovo ramo, una nuova versione o una nuova data. L'opzione `-A` elimina tutti i tag, le date o le versioni fissate mentre `-r` e `-D` ne impostano di nuove.

   Teoricamente, specificando `HEAD` come argomento di `-r` avrai lo stesso risultato di `-A`, ma è solo in teoria.

   L'opzione `-d` è utile se:

   - qualcuno ha aggiunto delle sottodirectory al modulo che hai estratto dopo averlo estratto.

   - hai estratto con `-l`, e dopo cambi idea e vuoi estrarre anche le sottodirectory.

   - hai cancellato delle sottodirectory e vuoi estrarle nuovamente.

   Osserva l'output di `cvs update` con cura. La lettera all'inizio di ogni file indica cosa è stato fatto su di esso:

   `U` | Il file è stato aggiornato senza problemi.
   `P` | Il file è stato aggiornato senza problemi (vedrai questo solo quando lavorerai su un repository remoto).
   `M` | Il file è stato modificato, ed è stato fuso senza conflitti.
   `C` | Il file è stato modificato, ed è stato fuso con dei conflitti.

   La fusione è ciò che avviene quando estrai una copia di qualche codice sorgente, lo modifichi, quindi qualcun altro effettua il commit di un'altra modifica, e tu esegui `cvs update`. CVS nota che tu hai fatto dei cambiamenti locali, e cerca di fondere le tue modifiche con quelle fatte tra la versione che hai originariamente estratto e quella che stai aggiornando. Se i cambiamenti sono a due parti separate del file, solitamente non ci saranno problemi (sebbene il risultato possa non essere sintatticamente o semanticamente corretto).

   CVS stamperà una `M` davanti ad ogni file modificato localmente anche se non c'è una nuova versione nel repository, quindi `cvs update` è adatto per avere un resoconto di quello che hai cambiato in locale.

   Se appare una `C`, allora le tue modifiche sono in conflitto con i cambiamenti presenti nel repository (le modifiche sono sulle stesse righe, o righe vicine, o hai cambiato così tanto il file locale che `cvs` non è in grado di applicare le modifiche al repository). Dovrai allora andare a modificare il file a mano e risolvere i conflitti; questi saranno evidenziati da righe di simboli `<`, `=` e `>`. Per ogni conflitto, ci sarà una linea di demarcazione formata da sette `<` e il nome del file, seguita da una porzione di quello che il tuo file locale conteneva, seguita da una riga di separazione con sette `=`, seguita dalla porzione corrispondente presente nella versione del repository, seguita da una riga di separazione con sette `>` e il numero di versione che stai aggiornando.

   L'opzione `-j` è un po' voodoo. Aggiorna il file locale alla versione specificata come se avessi usato `-r`, ma non cambia il numero di versione o il ramo registrato del file locale. Non è realmente utile tranne quando usata due volte, nel qual caso fonderà le modifiche tra le due versioni specificate nella copia su cui stai lavorando.

   Per esempio, supponiamo che ti abbia effettuato il commit di una modifica a `shazam/shazam.c` in FreeBSD-CURRENT e che più tardi tu voglia effettuare l'MFC. Le modifiche che vuoi fondere sono nella versione 1.15:

   - Estrai la versione FreeBSD-STABLE del modulo `shazam`:

         % cvs co -rRELENG_5 shazam

   - Applica le modifiche tra la ver 1.14 e la 1.15:

         % cvs update -j1.14 -j1.15 shazam/shazam.c

   Quasi certamente avrai un conflitto a causa delle righe `$Id$` (o nel caso di FreeBSD, `$FreeBSD$`), quindi dovrai modificare a mano il file per risolvere il conflitto (rimuovi le righe di separazione e la seconda linea `$Id$`, lasciando la linea `$Id$` originale intatta).

4. Guarda le differenze tra la versione locale e quella sul repository con il comando `diff`.

       % cvs diff shazam

   mostra ogni modifica che hai fatto al file o al modulo `shazam`.

   Tabella 3. Opzioni utili con `cvs diff`

   `-u` | Utilizza il formato diff unificato.
   `-c` | Utilizza il formato diff contestuale.
   `-N` | Visualizza i file mancanti o aggiunti.

   Vorrai sempre utilizzare `-u`, visto che le diff unificate sono molto più semplici da leggere rispetto a quasi tutti gli altri formati (in alcune circostanze, le diff contestuali generate con l'opzione `-c` possono essere meglio, ma sono molto più voluminose). Una diff unificata consiste di una serie di parti. Ogni parte inizia con una riga con due caratteri `@` e specifica dove si trovano le differenze nel file e su quante linee si estendono. Questa è seguita da un certo numero di righe; alcune (precedute da uno spazio) fanno parte del contesto; altre (precedute da un `-`) sono quelle eliminate e altre ancora (precedute da un `+`) sono quelle aggiunte.

   Puoi anche effettuare una diff con una versione differente rispetto a quella che hai estratto specificando la versione con `-r` o `-D` come per il `checkout` o l'`update`, o anche visualizzare le differenze tra due versioni arbitrarie (indipendentemente da quella che hai localmente) specificando due versioni con `-r` o `-D`.

5. Guarda le righe di log con il comando `log`.

       % cvs log shazam

   Se `shazam` è un file, questo stamperà un'intestazione con le informazioni sul file, come la locazione nel repository dove il file è salvato, a quale versione è l'`HEAD` per questo file, in quali rami si trova il file, e qualsiasi tag valido per questo file. Quindi, per ogni versione del file, viene stampato un messaggio di log. Questo include la data e l'ora del commit, chi ha fatto il commit, quante righe sono state aggiunte e/o tolte, e alla fine il messaggio di log che il committer ha scritto quando ha inviato la modifica.

   Se `shazam` è una directory, allora le informazioni di log descritte sopra vengono stampate a turno per ogni file presente nella directory. A meno che tu abbia dato l'opzione `-l` a `log`, vengono stampati anche i log per tutte le sottodirectory di `shazam`, in maniera ricorsiva.

   Usa il comando `log` per vedere la storia di uno o più file, come è salvata nel repository CVS. Puoi anche usarlo per vedere il messaggio di log di una versione specifica, se aggiungi `-r`ver`` al comando `log`:

       % cvs log -r1.2 shazam

   Questo stamperà solamente il messaggio di log per la versione `1.2` del file `shazam` se è un file, oppure i messaggi di log per le versioni 1.2 di ogni file sotto `shazam` se è una directory.

6. Guarda chi ha fatto cosa con il comando `annotate`. Questo comando visualizza ogni riga del file o dei file specificati, insieme all'utente che ha modificato più recentemente quella riga.

       % cvs annotate shazam

7. Aggiungi nuovi file con il comando `add`.

   Crea il file, usa `cvs add` su di esso, quindi `cvs commit`.

   In modo analogo, puoi aggiungere nuove directory creandole e poi utilizzando `cvs add` su di esse. Nota che non c'è bisogno di usare il commit sulle directory.

8. Rimuovi i file obsoleti con il comando `remove`.

   Rimuovi il file, quindi usa `cvs rm` su di esso, ed infine `cvs commit`.

9. Effettua il commit con il comando `commit` o `checkin`.

   Tabella 4. Opzioni utili con `cvs commit`

   `-f` | Forza il commit di un file non modificato.
   `-m`msg`` | Specifica un messaggio di commit sulla riga di comando anziché invocare un editor.

   Usa l'opzione `-f` se ti accorgi che hai lasciato fuori informazioni importanti dal messaggio di commit.

   Buoni messaggi di commit sono importanti. Dicono agli altri perché hai fatto le modifiche che hai fatto, non solo qui ed ora, ma per mesi o anni quando qualcuno si chiederà perché dei pezzi di codice all'apparenza illogici o inefficienti sono entrati nel file sorgente. È inoltre un aiuto inestimabile per decidere su quali modifiche va effettuato l'MFC e su quali no.

   I messaggi di commit devono essere chiari, concisi, e fornire un ragionevole sommario per dare un'indicazione di cosa è stato cambiato e perché.

   I messaggi di commit devono fornire abbastanza informazioni affinché una terza parte possa decidere se la modifica è rilevante per lei e se debba leggere la modifica stessa.

   Evita di effettuare il commit di più modifiche scollegate in una volta sola. Questo rende difficile la fusione, e inoltre rende più complicato determinare quale modifica è colpevole se salta fuori un bug.

   Evita di effettuare il commit di correzioni di stile o di spaziatura insieme a correzioni di funzionalità. Questo rende difficile la fusione, e inoltre rende più complicato capire quali modifiche alle funzionalità sono state fatte. Nel caso di file di documentazione, può rendere il lavoro dei gruppi di traduzione più complicato, visto che diventa difficile per loro determinare esattamente quali modifiche al contenuto vanno tradotte.

   Evita di effettuare il commit di cambiamenti a più file con un unico messaggio generico o vago. Invece, effettua il commit di un file alla volta (o di piccoli gruppi di file correlati) con un messaggio di commit appropriato.

   Prima di effettuare il commit, devi sempre:

   - verificare su che ramo stai effettuando il commit, tramite `cvs status`.

   - revisionare i tuoi cambiamenti, con `cvs diff`

   Inoltre, devi SEMPRE specificare esplicitamente sulla riga di comando su quali file deve essere effettuato il commit, in modo da non toccare incidentalmente altri file non voluti - `cvs commit` senza argomenti effettuerà il commit di ogni modifica nella directory corrente ed ogni sottodirectory.

Suggerimenti e trucchi aggiuntivi:

1. Puoi inserire le opzioni più comunemente usate nel tuo `~/.cvsrc`, come in questo caso:

       cvs -z3
       diff -Nu
       update -Pd
       checkout -P

   Questo esempio dice:

   - usa sempre il livello di compressione 3 quando si parla con un server remoto. Questo è un salvavita quando si lavora su una connessione lenta.

   - usa sempre le opzioni `-N` (visualizza i file aggiunti o rimossi) e `-u` (formato diff unificato) con diff(1).

   - usa sempre le opzioni `-P` (elimina le directory vuote) e `-d` (estrai le nuove directory) quando si effettua l'update.

   - usa sempre l'opzione `-P` (elimina le directory vuote) quando si estrae.

2. Usa lo script `cdiff` di Eivind Eklund per visualizzare le diff unificate. È un wrapper per less(1) che aggiunge i codici colore ANSI per far risaltare le intestazioni delle sezioni, le righe rimosse e quelle aggiunte; il contesto rimane invariato. Inoltre espande i tab correttamente (i tab spesso appaiono errati nelle diff a causa del carattere aggiuntivo all'inizio di ogni riga).

   `textproc/cdiff`

   Semplicemente usalo al posto di more(1) o less(1):

       % cvs diff -Nu shazam | cdiff

   Alternativamente alcuni editor come vim(1) (`editors/vim5`) hanno il supporto al colore e quando vengono usati con l'evidenziazione della sintassi attiva evidenzieranno molti tipi di file, incluse le diff, le patch, e i log CVS/RCS.

       % echo "syn on" >> ~/.vimrc
       % cvs diff -Nu shazam | vim -
       % cvs log shazam | vim -

3. CVS è vecchio, arcano, complesso e buggato, e a volte esibisce comportamenti non deterministici che qualcuno sostiene siano la prova che CVS non sia niente di più di una manifestazione Newtoniana di una entità ultradimensionale sensibile. Non è umanamente possibile conoscere ogni dettaglio di CVS, quindi non essere dispiaciuto di chiedere aiuto all'Intelligenza Artificiale (CVS Repository Meisters `<cvsadm@FreeBSD.org>`).

4. Non lasciare il comando `cvs commit` nella modalità di inserimento del messaggio di commit per troppo tempo (più di 2-3 minuti). Questo blocca la directory in cui stai lavorando ed impedirà ad altri sviluppatori di effettuare commit nella stessa directory. Se devi digitare un messaggio di commit lungo, scrivilo prima di eseguire `cvs commit` e inseriscilo successivamente oppure salvalo in un file prima di effettuare il commit ed usa l'opzione `-F` di CVS per leggere il messaggio di commit da quel file, cioè:

       % vi logmsg
       % cvs ci -F logmsg shazam

   Questo è il metodo più veloce per passare un messaggio di commit a CVS ma devi stare attento quando modifichi il file `logmsg` prima del commit, perché CVS non ti darà la possibilità di modificare il messaggio quando effettuerai realmente il commit.

Indietro | Partenza | Avanti
Tipi di Bit di Commit |  | Convenzioni e Tradizioni

Questo, ed altri documenti, possono essere scaricati da ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Per domande su FreeBSD, leggi la documentazione prima di contattare <questions@FreeBSD.org>.
Per domande su questa documentazione, invia una e-mail a <doc@FreeBSD.org>.