Pillole di Bazaar user manual consolidata pubblica v.1.0 del 20 ott 2009 autori: luciano de falco alfano Sommario Sommario...1 Obiettivi e contesto...1 Un esempio di flusso di lavoro...2 Un po' di terminologia...3 Struttura di directory da utilizzare in sviluppo...3 Operazioni di inizializzazione...4 Inizializzazione dello shared repository...4 Inizializzazione del repository...4 Utilizzo...4 Aggiungere file (add, remove)...5 Controllo della versione (commit, uncommit, tag)...5 Verifiche (status, diff, log)...6 Estrarre una copia del progetto (export)...7 Questo documento descrive le operazioni fondamentali per l'uso del sistema di controllo delle versioni 1 (VCS) Bazaar 2. Viene rilasciato con licenza Creative Commons Attribuzione (CC-By) senza alcuna garanzia, né assunzione di responsabilità. Obiettivi e contesto Un VCS permette di memorizzare in un contenitore, spesso detto repository, gruppi di file e directory che formano una determinata versione di un progetto. Questa caratteristica permette, ad esempio: di controllare passo passo l'evoluzione di un progetto; derivare un nuovo progetto a partire anche da versioni precedenti del progetto corrente; organizzare il modo di assemblare il progetto a partire da file assegnati in manutenzione a sviluppatori diversi, al fine di limitare le interferenze. Esistono vari VCS, che si differenziano sia per architettura che per modalità operative. Ad esempio: i VCS possono lavorare con, o senza, base dati (DBMS); il repository può essere unico, o ne possono coesistere più di uno; 1 In inglese Version Control System: VCS. 2 Sito WEB: http://bazaar-vcs.org/en/ Fname: bazaar-user manual-1.0
l'accettazione di uno stesso file proveniente da persone diverse può avvenire con un controllo centralizzato, o sotto la responsabilità dei singoli sviluppatori. Bazaar è un VCS moderno con varie caratteristiche interessanti: open source, quindi niente costi di licenza; sistema distribuito, è utilizzabile sia in stand alone (singolo sviluppatore), che in coppia, in gruppo, con o senza arbitro centrale al momento del merge, con o senza repository centralizzato; non richiede un DBMS; può essere utilizzato sia per progetti completamente nuovi, sia per progetti già avviati; infine, non guasta il fatto che sia sviluppato in python. In Bazaar, il contenitore è un insieme di directory e file detto repository. E la versione è detta identificativo di revisione. Un identificativo di revisione è un numero naturale a partire da 1, che viene incrementato di uno per ogni nuova revisione salvata. Nel seguito di questo documento si indicano i comandi da console. Esistono estensioni di Bazaar che permettono di avere interfacce GUI. Una di queste estensioni è Tortoise 3. Un esempio di flusso di lavoro Lavorare con Bazaar, per una singola persona 4, prevede le seguenti fasi: 1. identificare il progetto (nuovo o già avviato); 2. creare il (o i, si veda oltre) repository relativo; 3. catalogare nel repository i file che formano il progetto; 4. lavorare al progetto finché non si raggiunge il risultato voluto; 5. salvare il risultato raggiunto nel repository, dando luogo a una revisione. Le fasi 4 e 5 vengono reiterate a volontà. In questo modo è possibile: estrarre una qualunque revisione del progetto; controllare le differenze tra una revisione e lo stato corrente del progetto; creare un ramo secondario del progetto, e successivamente decidere se e come fonderlo nuovamente con il ramo principale. In questo ambito non si considera il lavoro di più persone allo stesso progetto. Per documentazione, si noti che a questo riguardo Bazaar prevede diverse possibilità: sharing with peers; team collaboration, central style; team collaboration, distributed style. 3 Sito WEB: http://bazaar-vcs.org/tortoisebzr. 4 In terminologia inglese: personal user control. Pag. 2 of 8
Un po' di terminologia Nell'ambito dei VCS esiste una terminologia che riflette concetti base. Riporto qui di seguito alcuni dei termini utilizzati nella manualistica di Bazaar. termine Branch Merge Related branches Repository Revision Working tree Linea di sviluppo per un progetto. spiegazione Operazione che consiste nell'applicare a una linea di sviluppo tutti i cambiamenti introdotti da un'altra linea di sviluppo. Linee di sviluppo che hanno in comune un antenato Contenitore di revisioni di un progetto. Versione di codice sorgente congelato in un repository. Directory gestita con controllo di versione. Struttura di directory da utilizzare in sviluppo In sviluppo si utilizzi la seguente struttura di progetto: sviluppo/ progetto/ progetto.main/ documentazione/ gestione/ ambienti/ La directory sviluppo è il livello superiore di progetto. Può essere un contenitore di diversi progetti. Al limite può essere la radice del file system. La directory progetto è la base in cui inserire tutto quel che deve essere scritto, o usato. Deve esistere ed ospiterà il repository condiviso del progetto (nel seguito: shared repository). La directory progetto.main contiene quanto sviluppato. E' il ramo principale del progetto. Si può usare un nome qualunque. In questa directory vi sarà il repository locale del progetto. Le altre directory (documentazione, gestione, ) possono esistere o meno, in funzione delle caratteristiche del progetto. In caso di progetti di sviluppo software, deve essere presente almeno la directory documentazione (con il relativo contenuto: analisi funzionale, test book,...). E' possibile gestire in versioning anche la documentazione. In tal caso è raccomandabile mettere questa directory sotto la directory del ramo principale. Pag. 3 of 8
Operazioni di inizializzazione Bazaar può gestire due repository: condiviso e locale. Il repository condiviso serve quando è necessario che più sviluppatori lavorino contemporaneamente allo stesso progetto. In generale è meglio crealo comunque. In tal modo è possibile iniziare a sviluppare (o modificare) il progetto con una persona, e se necessario successivamente affiancare un altro, o più, sviluppatori. Il repository locale è indispensabile. Ogni repository richiede una operazione di inizializzazione. Inizializzazione dello shared repository Lo shared repository è localizzato nella directory di progetto. Quindi: bzr init-repo directory_di_progetto crea lo shared repository nella directory directory_di_progetto. Se la directory non esiste, viene creata. Esempio: >cd sviluppi >bzr init-repo writer.bazaar_summary Shared repository with trees (format: 2a) Location: shared repository: writer.bazaar_summary crea la sottodirectory sviluppi\writer.bazaar_summary e vi costruisce lo shared repository. Inizializzazione del repository La inizializzazione del repository avviene con il comando bzr init branch_principale_di_progetto Anche in questo caso, se la directory non esiste viene creata. Ad esempio >cd writer.bazaar_summary >bzr init bazaar_summary.main Created a repository tree (format: 2a) Using shared repository: D:/Sviluppi/writer.bazaar_summary/ crea la directory sviluppi\writer.bazaar_summary\bazaar_summary.main, e vi costruisce il repository. Qui si nota che Bazaar ha osservato la presenza di uno shared repository nella directory padre (sviluppi\writer.bazaar_summary), e lo ha utilizzato per inizializzare il main branch repository che abbiamo appena creato. Utilizzo Aggiungere file a un repository, è una operazione di sola catalogazione. Il file non viene aggiunto fisicamente, ma solo elencato. Un file viene fisicamente inglobato nel repository solo quando si effettua una operazione di commit. Pag. 4 of 8
Aggiungere file (add, remove) add Quando si vogliono aggiungere dei nomi di file all'elenco dei nomi già conosciuti si usa il comando bzr add nomefile Se al posto di un nome file si dà il nome di una directory, Bazaar aggiungerà tutti i file contenuti nella directory indicata. E' possibile configurare Bazaar per escludere la catalogazione di determinate tipologie di file. Un esempio di catalogazione è il seguente. >bzr add. adding ".~lock.bazaar-user manual-1.0.odt#" adding "bazaar-user manual-1.0.odt" adding dir_progetto.odg adding dir_progetto.wmf Nell'esempio si è indicata la directory corrente (usando il punto), e Bazaar ha aggiunto i 4 file che vi ha trovato. remove Per togliere (dal catalogo) un file, il comando è: bzr remove --keep filename dove l'opzione keep è preceduta da due segni -. Attenzione. Esiste anche l'opzione force (--force) che, oltre rimuovere il file dal catalogo e dal repository, lo cancella anche dal disco. Questa opzione è pericolosa perché una volta cancellato, il file non è più possibile recuperarlo. Ad esempio, senza cancellare il file dal file system: >bzr remove --keep ".~lock.bazaar-user manual-1.0.odt#" removed.~lock.bazaar-user manual-1.0.odt# Controllo della versione (commit, uncommit, tag) commit Si effettua la commit con il seguente comando: bzr commit -m messaggio dove -m messaggio è facoltativo, e serve per dare un mnemonico che spiega il motivo della commit. Se il motivo della commit è articolato, si può scrivere in un file di testo, e inserirlo con il comando bzr commit -F file_messaggio Esempio: >bzr commit -m "initial import" Committing to: D:/Sviluppi/writer.bazaar_summary/bazaar_summary.main/ added bazaar-user manual-1.0.odt added dir_progetto.odg added dir_progetto.wmf Committed revision 1. Pag. 5 of 8
uncommit Per eliminare l'ultimo comando di versioning, utilizzare: bzr uncommit tag Il comando tag permette di assegnare una etichetta ad un livello di commit (identificativo di revisione). Si usa come segue: bzr tag nome Ad esempio: >bzr tag v.2.0 crea l'etichetta v.2.0 assegnata all'attuale identificativo di revisione. L'etichetta è intercambiabile con l'identificativo di revisione ovunque questo sia necessario. Le associazioni in uso sono elencabili con il comando (notare la s finale del plurale): bzr tags Ad esempio: >bzr tags v.2.0 2 Verifiche (status, diff, log) Per controllare lo stato delle attività rispetto il contenuto del repository sono utili questi comandi. status Lo status indica quali file sono modificati rispetto il contenuto del repository. Il comando è: bzr status Se vi sono file non catalogati, vengono indicati come unknown. Come nell'esempio che segue: >bzr status unknown:.~lock.bazaar-user manual-1.0.odt# bazaar-user manual-1.0.odt dir_progetto.odg dir_progetto.wmf File catalogati sono indicati added: >bzr status added:.~lock.bazaar-user manual-1.0.odt# bazaar-user manual-1.0.odt dir_progetto.odg dir_progetto.wmf File commessi e successivamente modificati sono indicati come tali: >bzr status modified: bazaar-user manual-1.0.odt diff Il comando diff può identificare e mostrare differenze in file ascii. Nel caso di file binari si limita ad indicare date ed orari dei file coinvolti. E' il seguente: Pag. 6 of 8
bzr diff Un esempio può essere: >bzr diff === modified file 'esempio.txt' --- esempio.txt 2009-10-19 14:12:00 +0000 +++ esempio.txt 2009-10-19 14:12:42 +0000 @@ -1,4 +1,4 @@ -linea uno +linea 1 linea due linea tre dove si evidenza la modifica delle linea n.ro uno del file exempio.txt. log Per verificare il livello di revisione, dare il comando: bzr log Ad esempio: >bzr log ------------------------------------------------------------ revno: 2 committer: De Falco <De Falco@defalcoII> branch nick: bazaar_summary.main timestamp: Mon 2009-10-19 16:12:00 +0200 message: an asci file to ckeck diff ------------------------------------------------------------ revno: 1 committer: De Falco <De Falco@defalcoII> branch nick: bazaar_summary.main timestamp: Mon 2009-10-19 16:04:50 +0200 message: initial import Estrarre una copia del progetto (export) export L'estrazione di una copia del progetto si ottiene con il comando bzr export package dove package è il nome di un file di archivio o di una directory. Bazaar decide come effettuare la copia in funzione del tipo di package indicato 5. Ad esempio per estrarre una copia di lavoro all'ultima versione in una nuova directory, dare il comando: >cd writer.bazaar_summary >bzr export..\bzr_summary-2.0\ > Questo crea la directory bzr_summary-2.0 di fianco al branch principale del progetto, e vi copia tutti i file in repository all'ultima revisione. Il risultato è il seguente: >cd..\bzr_summary-2.0 >dir Il volume nell'unità D non ha etichetta. Numero di serie del volume: 4351-4E90 5 Ad esempio possiamo indicare un file con estensione.tar o.zip per ottenere rispettivamente un archivio tar del progetto, o un archivio compresso in formato zip. Sono supportati anche i formati.tbz2 e.tgz Pag. 7 of 8
Directory di D:\Sviluppi\writer.bazaar_summary\bzr_summary-2.0 19/10/2009 16.38 <DIR>. 19/10/2009 16.38 <DIR>.. 19/10/2009 16.38 24.529 bazaar-user manual-1.0.odt 19/10/2009 16.38 10.201 dir_progetto.odg 19/10/2009 16.38 1.270 dir_progetto.wmf 19/10/2009 16.38 35 esempio.txt 4 File 36.035 byte 2 Directory 43.400.192.000 byte disponibili Pag. 8 of 8