Subversion
Viimeksi muutettu: $Date: 2007-06-11 11:21:57 +0300 (Mon, 11 Jun 2007) $, $Revision: 411 $.
Muista välillä vilkaista JKK (Joskus Kysytyt Kysymykset)!
Kurssin harjoitustyö koodataan Subversion-versionhallinnan avulla. Tämä sivu selostaa lyhyesti Subversionin käyttöä (tästedes lyhyesti vain Svn).
Sisällys
- Subversionin käytöstä kurssilla ja yleisesti
- Svn:n asentaminen
- Svn-ohjeita tämän sivun lisäksi
- Tietovaraston hakemistorakenne
- Aloitus 1: työkopion hakeminen tietovarastosta
- Aloitus 2: Svn:n konfiguraation säätäminen
- Tiedostojen lisääminen (add)
- Tiedostojen talletus tietovarastoon (commit)
- Työhakemiston tilanteen kysely (status)
- Työkopion päivittäminen tietovarastosta (update, resolved)
- Muutosten tutkiminen (diff)
- Muutosten kumoaminen (revert, merge)
- Muutoskommenttien tutkiminen (log)
- Tiedostojen poistaminen, kopioiminen, siirtäminen (rm, cp, mv)
- Muita Svn-komentoja
Subversionin käytöstä kurssilla ja yleisesti
Versionhallinnan hyödyt:
- Tiedostojen jakaminen ihmisten kesken
- Tiedostojen pitäminen ajan tasalla monen hengen projektissa
- Päällekkäiset muutokset samaan tiedostoon
- Historia: miten muistaa, mitä on tehty
- Jo tehtyjen muutosten peruuttaminen
- ...
Versionhallinnan käyttö on osa kurssin harjoitustyötä. Tämä tarkoittaa sitä, että sen käytön arviointi vaikuttaa osaltaan harjoitustyön arvosanaan. Sen sijaan versionhallintaan talletettujen tiedostojen aiemmat sisällöt eivät arvosanaan vaikuta, eli Svn:ään voi huoletta tallettaa testiversioita, räpellyksiä yms, jos se helpottaa harjoitustyön tekemistä.
Termejä:
- Tietovarasto (repository) taltioi kaiken tiedon (verkon yli)
- Työkopio (working copy) on käyttäjän "työhakemisto" (kopiot tiedostoista)
- Revisio (revision) on numeroitu "valokuva" projektista tietyllä hetkellä
Yleinen kysymys on, kuinka suuria muutoksia kannattaa kerralla tallettaa (commit) versionhallintaan. Tähän ei voi antaa mitään mekaanista ratkaisua, mutta alla on joitain mietteitä:
- Liian harva talletusväli aiheuttaa sen, että projektin historiatieto hämärtyy ja mahdollisten mokien peruminen on hankalampaa.
- Toisaalta liian pienten muutosten tallettaminen tuottaa ylenmäärin lokiviestejä yms, ja lisäksi saatetaan tallettaa toimimattomia versioita jne.
- Tärkeintä on, että jokainen talletus (commit) on looginen kokonaisuus.
- Samoin olennaista on, että Svn:ssä muutosten peruuttaminen tapahtuu helpoiten revisio kerrallaan, eli yhteen talletukseen kannattaa laittaa vain sellaiset muutokset, jotka myös tarvittaessa perutaan kerralla.
Svn:n asentaminen
Svn löytyy useimpiin käyttöjärjestelmiin:
- Proffa/Lintula: löytyy valmiina (svn)
- Linux: saa valmiina pakettina (svn)
- Windows: esim. TortoiseSVN (http://tortoisesvn.tigris.org/)
- Mac OS X: Svn:n Mac-download-sivut
- Yleisesti: http://subversion. tigris.org/project_packages.html
- Myös Linux/Mac-ympäristöihin löytyy graafisia Svn-ympäristöjä, jos niistä pitää enemmän
Svn-ohjeita tämän sivun lisäksi
- Matti Rintalan Svn-esittelyluennon kalvot.
- Lyhyt svn-viitekortti (englanniksi). Ei kuitenkaan mikään aloittelijan opas.
- Virallinen Svn-kirja
- Vinkkejä muista hyvistä ohjeista otetaan vastaan!
Tietovaraston hakemistorakenne
Tämän kurssin harjoitustyössä Svn-tietovaraston hakemistorakenne on tehty valmiiksi seuraavasti:
- trunk : Varsinainen kehityshaara, jossa työ koodataan.
- trunk/julkinen : Kurssin julkinen materiaali.
- Päivittyy automaattisesti päivityksen (update) yhteydessä.
- Julkinen-hakemistoon ei kannata itse lisätä mitään tai muuttaa siellä olevia asioita. Muutokset eivät päivity minnekään.
- Poikkeuksen edelliseen tekevät julkisista .cc-tiedostoista käännetyt .o-objektitiedostot. Ne voivat hyvin olla julkinen-hakemiston alla, koska kurssin Svn on säädetty olemaan välittämättä objektitiedostoista.
- tags : "Julkaisuhaara", johon palautukset svn-kopioidaan.
- Palautuksen yksityiskohtaiset ohjeet tulevat myöhemmin.
- Harjoitustyön tietovarasto on säädetty siten, että tags-haaran alle voi vain luoda hakemistoja (esim. svn cp -komennolla).
- Jo luotuja tags-hakemistoja (palautuksia) ei voi muuttaa tai poistaa.
- Älä siis turhaan sotke tags-hakemistoa. :-)
- branches : Haara kokeiluja yms. varten. Edistyneemmille.
- arvostelu : Hakemisto, johon Boss ja assarit tallentavat palautusten tulokset.
Yksinkertainen ja lyhyt Svn-käyttöohje alkuun pääsemiseksi
Tämä ohje toimii muistin virkistäjänä ja auttaa alkuun. Kannattaa tutustua myös muuhun Svn-materiaaliin...
Ohje käsittelee komentorivipohjaista Unix/Linux-svn:ää. Windowsin TortoiseSVN toimii kyllä samoin, mutta komennot haetaan hiiren oikealla napilla.
Aloitus 1: työkopion hakeminen tietovarastosta
Alla <PORTTI> on kurssin käyttämä porttinumero (joka ilmoitetaan kurssilla) ja <RYHMA> on ryhmänne nimi (myös kurssikohtainen).
svn checkout https://kurssisvn.cs.tut.fi:<PORTTI>/ryhmat/<RYHMA>/trunk nimi_hakemistolle
Aloitus 2: Svn:n konfiguraation säätäminen
Ennen harkkatyön aloittamista Svn:lle täytyy kertoa, että C++-tiedostot ovat tekstitiedostoja, joihin tehdään avainsanakorvaukset ($Id$, $Date$ jne, kuten RCS:ssä) samoin kuin merkistö- ja rivinvaihtomuunnokset käyttöjärjestelmien välillä.
Svn:n konfigurointitiedoston loppupuolelta täytyy rivin
# enable-auto-props = yes
alusta poistaa kommenttimerkki "#" ja sen perässä oleva sanaväli. Lisäksi ko. tiedoston loppuun pitää lisätä seuraavat rivit (tiedostona).
*.cc = svn:eol-style=native;svn:keywords=Author Date Id Revision *.hh = svn:eol-style=native;svn:keywords=Author Date Id Revision *.cxx = svn:eol-style=native;svn:keywords=Author Date Id Revision *.hxx = svn:eol-style=native;svn:keywords=Author Date Id Revision *.cpp = svn:eol-style=native;svn:keywords=Author Date Id Revision *.hpp = svn:eol-style=native;svn:keywords=Author Date Id Revision *.c = svn:eol-style=native;svn:keywords=Author Date Id Revision *.h = svn:eol-style=native;svn:keywords=Author Date Id Revision *.txt = svn:eol-style=native Makefile = svn:eol-style=native;svn:keywords=Author Date Id Revision
- Unix/Linux-puolella tämä tapahtuu yksinkertaisesti editoimalla haluamallaan editorilla tiedostoa ~/.subversion/config. Huom: Kyseinen tiedosto ilmestyy vasta svn:n ensimmäisen käyttökerran jälkeen, joten ensin kannattaa tehdä edellisessä kohdassa selitetty työkopion 1. haku tietovarastosta (checkout).
- Windows-puolella TortoiseSVN:ssä editointi onnistuu esim. seuraavasti:
- Työpöydän päällä hiiren oikealla napilla menu auki
- Sieltä TortoiseSVN ja sen alta Settings
- Avautuvasti ikkunasta (General settings) "Subversion configuration file: Edit"
- Konfiguraatiotiedosto avautuu Notepadiin, jossa sitä voi editoida
Tiedostojen lisääminen
- Luodaan tiedoston normaalisti editorilla.
-
svn add tiedosto
- Ja vielä lopuksi, kun sopiva aika tulee
svn commit
Tiedostojen talletus tietovarastoon
Talletetaan kaikki muutokset
svn commit
Talletetaan vain tietyt tiedostot
svn commit tiedosto1 tiedosto2...
Ylläolevat avaavat editorin muutoskommenttia varten (käytetyn editorin määrää EDITOR-ympäristömuuttuja). Toinen mahdollisuus on antaa commit-sanan perään -m-vipu ja kommentti lainausmerkeissä:
svn commit -m "Muutettiin jotain" tiedosto
Työhakemiston tilanteen kysely
Tilannekysely tulostaa jokaisen työkopion tiedoston muutostilan. (Kysely ei vaadi verkkoyhteyttä tietovarastoon.)
svn status
Status-komennon tulostamien kirjainten merkitys:
- A : (Added) tiedosto lisätty
- D : (Deleted) tiedosto poistettu
- M : (Modified) tiedostoa muutettu
- ? : (?) tiedosto ei svn:n hallinnassa
- C : (Conflict) tiedosto konfliktitilassa (ristiriitaisia muutoksia)
- X : (eXternal) tiedosto haettu muualta (esim. hakemisto "julkinen")
- R : (Replaced) tiedosto on korvattu (vanha tuhottu, uusi lisätty)
- ! : (!) tiedosto puuttuu, vaikka sen pitäisi olla olemassa (esim. rm eikä svn rm)
- ...
(Status-komento ei tulosta mitään tiedostoista, joista Svn:n on käsketty olemaan välittämättä. Harjoitustyön tapauksessa tällaisia ovat .o- ja ~-loppuiset tiedostot.)
Työkopion päivittäminen tietovarastosta
svn update
Komento update näyttää tietovarastosta haetut muutokset samaan tapaan kuin status-komento. Uusia tai tärkeitä ovat seuraavat koodit:
- U : (Updated) työkopio muuttamaton, päivitetty muutos tietovarastosta
- G : (merGed) työkopiota muutettu, muutos myös tietovarastossa, muutokset yhdistetty onnistuneesti
- C : (Conflict) kuten yllä, mutta muutokset ristiriitaisia ja päällekkäisiä, pitää korjata käsin
Viimeisessä tapauksessa päällekkäiset muutokset näkyvät tiedostossa seuraavaan tapaan:
Koodia <<<<<<< .mine Oma muutos ======= Tietovaraston muutos >>>>>>> .r# Vielä koodia
Tiedosto pitää nyt muokata käsin "kelvolliseen" kuntoon (esim. valitsemalla toinen muutoksista tai yhdistelemällä ne käsin). Tietysti myös erotinrivit (<<<, ===, >>>) pitää poistaa. Korjauksen jälkeen tiedosto pitää vielä julistaa "valmiiksi" komennolla
svn resolved tiedosto
(Konfliktin sattuessa Svn luo myös väliaikaisesti seuraavat tiedostot, joita voi halutessaan käyttää avuksi konfliktin tutkimisessa:
- tiedosto.mine : Kopio paikallisesti muutetusta tiedostosta
- tiedosto.rX : Kopio viimeisimmästä tietovaraston "yhteisestä" versiosta (X revisionumero)
- tiedosto.rY : Kopio tietovarastossa olevasta muutetusta tiedostosta (Y revisionumero, ja Y > X)
)
Muutosten tutkiminen
Diff-komennolla voi tutkia, mitä tallentamattomia muutoksia työkopiossa on. (Komento ei vaadi verkkoyhteyttä tietovarastoon.)
- Tulostetaan kaikki muutokset hakemistossa
svn diff
- Tulostetaan yhden tiedoston muutokset
svn diff tiedosto
- Tulostetaan muutokset tiettyyn revisioon verrattuna (vaatii yhteyden
tietovarastoon)
svn diff -rRevisionumero tiedosto
- Tulostetaan muutokset kahden revision välillä (vaatii yhteyden
tietovarastoon)
svn diff -rRev1:Rev2 tiedosto
Muutosten kumoaminen
Muutoksen kumoaminen riippuu siitä, onko muutos jo tallennettu tietovarastoon (commit).
- Työkopioon tehdyn tallentamattoman muutoksen peruminen (ei vaadi yhteyttä
tietovarastoon)
svn revert tiedosto
- Tietovarastoon välillä Rev1-Rev2 tehtyjen muutosten kumoaminen. Rev1
on revisio, jossa muutoksia ei vielä ole, Rev2 viimeinen kumottava muutos.
(Komennosta voi aiheutua konflikti update-komennon tapaan.)
svn merge -rRev2:Rev1 tiedosto (HUOM! Numeroiden järjestys "käänteinen"!) (Tutkitaan, että on tapahtunut mitä pitikin) svn commit
Muutoskommenttien tutkiminen
Log-komento tulostaa tiedostoa tai hakemistoa koskevat muutoskommentit
svn log tiedosto/hakemisto
Jos halutaan nähdä myös luettelo muutetuista tiedostoista, lisätään log-komennon perään vipu -v. Tietyn revisiovälin voi valita vivulla -rRev1:Rev2.
Tiedostojen poistaminen, kopioiminen, siirtäminen
Svn:n alaisten tiedostojen poistaminen, kopioiminen ja siirtäminen on tehtävä Svn:n avulla (muuten historia ei kopioidu oikein). Kaikki alla olevat komennot vaativat vielä muutoksen talletuksen (commit).
- Tiedoston poistaminen
svn rm tiedosto
- Tiedoston kopioiminen (uuden tiedoston historiassa näkyy vanhankin historia)
svn cp vanha uusi
- Tiedoston siirtäminen (sama kuin svn cp + svn rm)
svn mv vanha uusi (tai svn rename vanha uusi)
Muita Svn-komentoja
Alla on lueteltu muita Svn:n komentoja, tarkemmat ohjeet esim. Svn-kirjasta.
- svn help : Apua Svn:n käytössä (myös svn komento --help)
- svn info : Tulostaa tiedoston/hakemiston tiedot
- svn mkdir : Luo hakemiston, lisää sen Svn:n hallintaan
- svn blame/praise/annotate : Tulostaa tiedoston rivikohtaisen historian
- svn propedit/propget/propset/proplist : Tiedostojen ja hakemistojen "ominaisuuslistojen" säätäminen (esim. svn:ignore niiden tiedostojen määräämiseen, joista Svn ei välitä)
- svn import/export: Hakemistohierarkian vieminen/hakeminen Svn:stä