Jak rozpocząć pracę z Subversion Jarosław Koszuk Politechnika Łódzka Instytut Informatyki v. 0.4.0, 2003-11-05 Historia zmian Zmiana 0.4.0 2003-11-05 jk Dodana sekcja z materiałami dodatkowymi. Zmiana 0.3.0 2003-10-27 jk Dodany opis przebiegu typowej sesji z Subversion. Zmiana 0.2.0 2003-10-11 jk/ag Poprawki stylistyczne Zmiana 0.1.0 2003-10-07 jk Wstępna wersja dokumentu. Zmiana 0.0.1 2003-09-30 jk Rozpoczęte prace nad dokumentem. Abstrakt Dokument zawiera najważniejsze informacje, pozwalające szybko rozpocząć pracę z Subversion. W zamierzeniach ma to być raczej podręczna "ściąga" niż kompletna dokumentacja. _________________________________________________________ Spis treści 1. Wstęp 2. Kontrola wersji 3. Praca z Subversion 3.1. Jak uzyskać pomoc? 3.2. Dodawanie nowego projektu 3.3. Pobieranie źródeł (checkout) 3.4. Wprowadzanie zmian (commit) 3.5. Dodawanie plików do repozytorium 3.6. Typowa sesja z Subversion Materiały dodatkowe 1. Wstęp Obecnie trudno sobie wyobrazić pracę nad projektem programistycznym bez wykorzystania systemu kontroli wersji. Podstawowym zadaniem tego typu narzędzi jest przechowywanie historii zmian zachodzących w plikach źródłowych. Umożliwia to dostęp do starszych wersji plików, jak również pozwala w łatwy sposób porównać dwie wybrane wersje. Dodatkowym (ale nie mniej ważnym) zadaniem jest wspomaganie pracy grupowej. Dzięki systemowi kontroli wersji możliwa jest jednoczesna praca zespołu programistów nad tym samym programem. Jednym z systemów kontroli wersji, które zyskuje coraz większą popularność, jest Subversion. Ten dokument zawiera instrukcje, pozwalające na rozpoczęcie pracy z Subversion. Nie jest to kompletna dokumentacja - wiele zagadnień zostało pominiętych. Celem było zebranie opisów podstawowych operacji, najczęściej wykonywanych w trakcie pracy z systemem kontroli wersji. Wyczerpujące informacje można znaleźć m.in. w podręczniku dostarczanym razem z Subversion. 2. Kontrola wersji Subversion przechowuje aktualną wersję kodu i historię jego zmian w centralnym repozytorium. Dane z repozytorium dostępne są w postaci systemu plików (czyli w naturalny dla plików sposób: w strukturze hierarchicznej, składającej się z katalogów i plików). Użytkownik, łącząc się z repozytorium, może odczytywać i zapisywać pliki. Tym, co odróżnia repozytorium od zwykłego systemu plików, jest fakt, że Subversion zapamiętuje wszystkie modyfikacje danych w repozytorium, m.in. zmiany zawartości plików oraz zmiany w strukturze katalogowej (dodawanie, usuwanie i zmiany nazw plików i katalogów). Problemem, który każdy system kontroli wersji stara się rozwiązać, jest problem jednoczesnego dostępu wielu użytkowników do tych samych danych. W sytuacji, gdy wszyscy oni jedynie odczytują dane z repozytorium, sprawa jest prosta: każdy z nich może otrzymać własną kopię plików. Trudności pojawiają się w momencie, gdy wielu użytkowników próbuje jednocześnie wprowadzać zmiany. Powszechnie wykorzystuje się dwa podstawowe modele, pozwalające radzić sobie z tą sytuacją: * model blokuj-modyfikuj-odblokuj (ang. lock-modify-unlock) - tylko jedna osoba może w danym momencie modyfikować plik; schemat postępowania jest następujący: użytkownik blokuje plik, który będzie modyfikował, następnie wprowadza zmiany, po czym usuwa blokadę; tak długo, jak długo plik jest zablokowany, nikt inny nie może dokonać w nim zmian; * model kopiuj-modyfikuj-włącz (ang. copy-modify-merge) - użytkownik odczytuje repozytorium i tworzy własną kopię roboczą pliku lub projektu; użytkownicy mogą pracować równolegle, wprowadzając zmiany do swoich kopii roboczych; ostatecznie, kopie robocze są łączone w nową, końcową wersję; zazwyczaj system kontroli wersji wspomaga łączenie, ale odpowiedzialność za poprawność tej operacji spada na użytkownika. Subversion wykorzystuje model kopiuj-modyfikuj-włącz. 3. Praca z Subversion Podstawowym narzędziem, wykorzystywanym przy pracy z Subversion, jest polecenie svn. Za jego pomocą można manipulować danymi w repozytorium i kopią roboczą. Podstawowe operacje, jakie udostępnia svn, to: * dodawanie plików do repozytorium * tworzenie kopii roboczej plików z repozytorium (ang. checkout) * wprowadzanie zmian do repozytorium (ang. commit) Składnia polecenia svn jest następująca: svn operacja [opcje] [argumenty] Część operacji wymaga określenia miejsca, w którym znajduje się repozytorium. Miejsce to podaje się w postaci URL-a. Jeśli mamy do czynienia z repozytorium zdalnym, najprawdopodobniej wykorzystywana będzie następująca forma: http://zdalny.serwer.org/repozytorium/. Jeśli odwołujemy się do konkretnego pliku lub katalogu w obrębie repozytorium, należy podać jego ścieżkę. Przy wykonywaniu operacji wprowadzania zmian do repozytorium (commit, import) svn uruchomi domyślny edytor, prosząc o podanie opisu modyfikacji. Komentarz ten będzie później widoczny w historii. Powinno się wtedy w zwięzły sposób opisać wprowadzone zmiany. Opis można również podać korzystając z odpowiedniej opcji (-m lub -F). 3.1. Jak uzyskać pomoc? Aby wyświetlić listę operacji udostępnianych przez polecenie svn, należy wywołać: bash$ svn help Do uzyskania pomocy na temat składni poszczególnych operacji można użyć następującego polecenia: bash$ svn help operacja Dostępna jest także obszerna dokumentacja poświęcona Subversion i jego wykorzystaniu. Znajduje się ona w pakietach źródłowych Subversion (jeśli korzystamy z gotowych binariów, istnieje duża szansa, że również ten podręcznik został dołączony) oraz pod adresem: http://svnbook.red-bean.com/ 3.2. Dodawanie nowego projektu Aby dodać nowy projekt do repozytorium, należy go zaimportować. Służy do tego operacja import. Zakładając, że chcemy dodać nowy projekt o nazwie "foo", którego źródła znajdują się w katalogu /home/user/foo, powinniśmy wykonać następujące polecenie: bash$ svn import /home/user/foo http://zdalny.serwer.org/repozyto rium/foo 3.3. Pobieranie źródeł (checkout) Aby pobrać źródła z repozytorium (plik lub katalog wskazany przez URL) do bieżącego katalogu, należy wywołać polecenie: bash$ svn checkout URL 3.4. Wprowadzanie zmian (commit) Aby wprowadzić zmiany do repozytorium, należy (będąc w katalogu ze źródłami pobranymi wcześniej z repozytorium) wykonać polecenie: bash$ svn commit 3.5. Dodawanie plików do repozytorium Aby dodać pliki lub katalogi do repozytorium (przy założeniu, że znajdujemy się w katalogu ze źródłami pobranymi wcześniej z repozytorium), należy wykonać polecenie: bash$ svn add ścieżka Należy pamiętać, że ta operacja nie wprowadza jeszcze zmian do repozytorium, a jedynie zaznacza wskazane pliki lub katalogi jako "dodane". Aby pliki rzeczywiście pojawiły się w repozytorium, konieczne jest wykonanie operacji commit. 3.6. Typowa sesja z Subversion Praca z wykorzystaniem Subversion przebiega zazwyczaj w cyklach, z których każdy składa się z następujących etapów: Update. Za pomocą polecenia: bash$ svn update pobieramy aktualną wersję projektu do naszego katalogu roboczego (w którym wcześniej nad tym projektem pracowaliśmy; jeśli chcemy pobrać źródła do nowego katalogu używamy operacji checkout). Po wykonaniu tej operacji w katalogu bieżącym będziemy mieli aktualną wersję projektu. Wprowadzanie zmian. Wprowadzamy zmiany do plików źródłowych, dodajemy lub usuwamy pliki. Sprawdzanie zmian. Za pomocą operacji status i diff sprawdzamy, co zostało przez nas zmienione, sprawdzamy, czy nie popełniliśmy błędów. Jeśli chcemy cofnąć wprowadzone modyfikacje, powinniśmy posłużyć się operacją revert. Pomocna może być również opcja -u operacji status. Pozwala ona sprawdzić, czy w repozytorium zaszły zamiany (jeśli w repozytorium znajduje się zmodyfikowana wersja pliku, w linii zawierającej nazwę tego pliku umieszczona zostanie gwiazdka). Rozwiązywanie konfliktów. Jeśli ktoś wprowadził zmiany do plików w repozytorium, należy uaktualnić swoją kopię roboczą za pomocą operacji update. Może się wtedy okazać, że zmiany te "zachodzą" na zmiany dokonane przez nas. Mamy wówczas do czynienia z konfliktem, który musimy rozwiązać przed umieszczeniem naszej wersji w repozytorium. Po rozwiązaniu konfliktów informujemy o tym Subversion za pomocą operacji resolved. Commit. Jeśli rozwiązaliśmy już wszystkie konflikty i jesteśmy pewni, że wprowadzone przez nas modyfikacje są poprawne (w szczególności powinniśmy np. sprawdzić, czy projekt kompiluje się i działa), możemy wreszcie przesłać nasze poprawki do repozytorium. Korzystamy przy tym z operacji commit. Materiały dodatkowe Strona domowa Subversion. http://subversion.tigris.org Subversion FAQ. http://subversion.tigris.org/project_faq.html B. Collins-Sussman, B. W. Fitzpatrick, C. M. Pilato. Version Control with Subversion. http://svnbook.red-bean.com/ J. Prucia. Subversion - nowy system kontroli wersji oprogramowania. Pingwinaria 2001, 6-8 lipca 2001, Szczytno. http://linux.gda.pl/Pingwinaria_2001/_other/jacekp/svn_talk.pd f