9.2 Git i inne systemy - Migracja do Gita

Jeżeli przeczytałeś poprzednią sekcję na temat używania git svn, możesz z łatwością użyć tamtych instrukcji aby sklonować za pomocą git svn clone repozytorium; następnie, przestań używać serwera Subversion, wypchaj zmiany do serwera Git i zacznij tylko na nim współpracować. Jeżeli potrzebujesz historii projektu, będziesz mógł to osiągnąć tak szybko, jak tylko możesz ściągnąć dana z serwera Subversion (co może chwilę zająć).

Niemniej, importowanie nie jest idealnym rozwiązaniem; a dlatego że zajmie to dużo czasu, powinieneś zrobić to raz a dobrze. Pierwszym problemem są informacje o autorze. W Subversion, każda osoba wgrywająca zmiany posiada konto systemowe na serwerze który zapisuje zmiany. Przykłady w poprzedniej sekcji, pokazują użytkownika schacon w kilku miejscach, takich jak wynik komendy blame czy git svn log. Jeżeli chciałbyś zamienić je na dane zgodne z Gitem, musisz stworzyć mapowania z użytkownika Subversion na autora w Git. Stwórz plik users.txt, który ma przypisane adresy w ten sposób:

Aby otrzymać listę autorów używanych przez SVN, uruchom komendę:

Generuje to wyjście dziennika w formacie XML, następnie zachowuje tylko linie z informacjami o autorze, odrzuca duplikaty i usuwa znaczniki XML. (Oczywiście działa to tylko na maszynie z zainstalowanymi programami grep, sort i perl). Następnie przekieruj wynik komendy do pliku users.txt, tak abyś mógł dodać odpowiednik użytkownika w Gitcie dla każdego wpisu.

Możesz przekazać ten plik do komendy git svn, aby pomóc jej lepiej zmapować dane przypisane do autorów. Możesz również wskazać git svn, aby nie zaciągał meta-danych, które normalnie Subversion importuje, poprzez dodanie opcji --no-metadata do komend clone lub init. Twoja komenda import wygląda więc tak:

Teraz powinieneś mieć lepiej wyglądający projekt z Subversion w swoim katalogu my_project. Zamiast commitów, które wyglądają tak te:

masz takie:

Nie tylko dane dotyczące autora ("Author") wyglądają lepiej, ale nie ma również znaczników git-svn-id.

Musisz jeszcze trochę posprzątać po imporcie. Na początek, powinieneś poprawić dziwne referencje które ustawił git svn. Najpierw przeniesiesz tagi, tak aby były normalnymi tagami, zamiast dziwnych zdalnych gałęzi, następnie przeniesiesz resztę gałęzi tak aby były lokalne.

Aby przenieść etykiety i zrobić z nich prawidłowe tagi Gita, uruchom:

Pobierze to referencje które były zdalnymi gałęziami rozpoczynającymi się od remotes/origin/tags/ i zrobi z nich normalne (lekkie) etykiety.

Następnie, przenieś resztę referencji z refs/remotes, tak aby stały się lokalnymi gałęziami:

Teraz wszystkie stare gałęzie są prawdziwymi gałęziami Gita, a stare tagi prawdziwymi tagami w Git. Ostatnią rzeczą do zrobienia jest dodanie nowego serwera Git jako zdalnego i wypchnięcie danych do niego. Poniżej znajduje się przykład dodania Twojego serwera jako zdalnego:

Ponieważ chcesz aby wszystkie gałęzie i etykiety były na repozytorium, możesz uruchomić:

Wszystkie gałęzie i tagi powinny być już na Twoim serwerze Gita, zaimportowane w czysty i zgrabny sposób.

Since Mercurial and Git have fairly similar models for representing versions, and since Git is a bit more flexible, converting a repository from Mercurial to Git is fairly straightforward, using a tool called "hg-fast-export", which you’ll need a copy of:

The first step in the conversion is to get a full clone of the Mercurial repository you want to convert:

The next step is to create an author mapping file. Mercurial is a bit more forgiving than Git for what it will put in the author field for changesets, so this is a good time to clean house. Generating this is a one-line command in a bash shell:

This will take a few seconds, depending on how long your project’s history is, and afterwards the /tmp/authors file will look something like this:

In this example, the same person (Bob) has created changesets under four different names, one of which actually looks correct, and one of which would be completely invalid for a Git commit. Hg-fast-export lets us fix this by adding ={new name and email address} at the end of every line we want to change, and removing the lines for any usernames that we want to leave alone. If all the usernames look fine, we won’t need this file at all. In this example, we want our file to look like this:

The next step is to create our new Git repository, and run the export script:

The -r flag tells hg-fast-export where to find the Mercurial repository we want to convert, and the -A flag tells it where to find the author-mapping file. The script parses Mercurial changesets and converts them into a script for Git’s "fast-import" feature (which we’ll discuss in detail a bit later on). This takes a bit (though it’s much faster than it would be over the network), and the output is fairly verbose:

That’s pretty much all there is to it. All of the Mercurial tags have been converted to Git tags, and Mercurial branches and bookmarks have been converted to Git branches. Now you’re ready to push the repository up to its new server-side home:

Następnym systemem, któremu się przyjrzymy z perspektywy importu, jest Perforce. Jak wspomnieliśmy powyżej, istnieją dwa sposoby, aby Git i Perforce mogły ze sobą rozmawiać: git-p4 oraz Perforce Git Fusion.

If your team is converting their source control from TFVC to Git, you’ll want the highest-fidelity conversion you can get. This means that, while we covered both git-tfs and git-tf for the interop section, we’ll only be covering git-tfs for this part, because git-tfs supports branches, and this is prohibitively difficult using git-tf.

The first thing to do is map usernames. TFVC is fairly liberal with what goes into the author field for changesets, but Git wants a human-readable name and email address. You can get this information from the tf command-line client, like so:

This grabs all of the changesets in the history of the project and put it in the AUTHORS_TMP file that we will process to extract the data of the User column (the 2nd one). Open the file and find at which characters start and end the column and replace, in the following command-line, the parameters 11-20 of the cut command with the ones found:

The cut command keeps only the characters between 11 and 20 from each line. The tail command skips the first two lines, which are field headers and ASCII-art underlines. The result of all of this is piped to uniq to eliminate duplicates, and saved to a file named AUTHORS. The next step is manual; in order for git-tfs to make effective use of this file, each line must be in this format:

The portion on the left is the “User” field from TFVC, and the portion on the right side of the equals sign is the user name that will be used for Git commits.

Once you have this file, the next thing to do is make a full clone of the TFVC project you’re interested in:

Next you’ll want to clean the git-tfs-id sections from the bottom of the commit messages. The following command will do that:

That uses the sed command from the Git-bash environment to replace any line starting with “git-tfs-id:” with emptiness, which Git will then ignore.

Once that’s all done, you’re ready to add a new remote, push all your branches up, and have your team start working from Git.

Jeżeli Twój system kontroli wersji to nie jest żadnym ze wspomnianych wcześniej, powinieneś spojrzeć na importery dostępne w sieci – dobrej jakości importery dostępne są dla CVS, Clear Case, Visual Source Safe, a nawet zwykłego katalogu z archiwami. Jeżeli żadne z tych narzędzi nie zadziała, lub używasz mniej popularnego systemu, lub jeżeli potrzebujesz bardziej dostosowanego importu, powinieneś użyć git fast-import. Ta komenda odczytuje instrukcje przekazane na standardowe wejście programu i zapisuje dane w Git. Dużo łatwiej w ten sposób tworzyć obiekty Gita, niż uruchamiać jego niskopoziomowe komendy czy zapisywać surowe obiekty (por. Mechanizmy wewnętrzne w Git). W ten sposób możesz napisać skrypt importujący, który odczyta wszystkie potrzebne informacje z systemu z którego importujesz i wypisze instrukcje do wykonania na standardowe wyjście. Możesz następnie uruchomić ten program i przekazać wynik do git fast-import.

W celach demonstracyjnych, napiszesz prosty skrypt importujący. Załóżmy, że pracujesz na najnowszej kopii kodu źródłowego i wykonujesz czasami kopie zapasowe poprzez skopiowanie danych do katalogu z datą w formacie back_YYYY_MM_DD i chciałbyś je zaimportować do Gita. Twoja struktura katalogów wygląda następująco:

Aby zaimportować katalog do Gita, musisz przypomnieć sobie w jaki sposób Git przechowuje dane. Być może pamiętasz, Git z założenia jest zbiorem połączonych obiektów dotyczących commitów, które wskazują na ostatnią migawkę z zawartością. Wszystko co musisz zrobić, to wskazać fast-import jaka jest zawartość migawek, który commit na nie wskazuje, oraz kolejność w której występują. Twoją strategią będzie przejście kolejno przez wszystkie migawki, oraz stworzenie commitów z zawartością dla każdego z nich, łącząc każdy commit z poprzednim.

ak robiłeś już to w sekcji An Example Git-Enforced Policy, również napiszemy to w Ruby, ponieważ to na nim zazwyczaj pracuję, a jego kod jest dość czytelny. Możesz stworzyć ten przykład bardzo szybko, w praktycznie każdym innym języku który dobrze znasz – musi on wypisać na standardowe wyjście właściwe informacje. A jeżeli pracujesz na systemie Windows, będziesz musiał zwrócić szczególną uwagę, aby nie wprowadzić znaków powrotu karetki na końcach linii – git fast-import potrzebuje linie zakończone znakami nowej linii (LF), a nie powrotem karetki (CRLF), których używa Windows.

Aby rozpocząć, przejdziesz do docelowego katalogu i znajdziesz wszystkie podkatalogi, z których znajdują się migawki które chcesz zaimportować. Następnie wejdziesz do każdego podkatalogu i wypiszesz komendy konieczne do eksportu. Twoja pętla główna w programie wygląda tak:

Uruchamiasz print_export w każdym katalogu, która przyjmuje jako parametry nazwę katalogu oraz znacznik poprzedniej migawki, a zwraca znacznik obecnej; w ten sposób możesz połączyć je poprawnie ze sobą. "Mark" jest terminem używanym przez fast-import, dla identyfikatora który przypisujesz do commita; podczas tworzenia kolejnych commitów, nadajesz każdemu z nich znacznik, który będzie użyty do połączenia go z innymi commitami. Dlatego pierwszą rzeczą którą robisz w metodzie print_export jest wygenerowanie znacznika pobranego z nazwy katalogu:

Zrobisz to poprzez wygenerowanie tablicy z nazwami katalogów, która używa jako indeksu znacznika będącego liczbą całkowitą. Twoja metoda wygląda więc tak:

Teraz, gdy masz już liczbę reprezentującą Twój commit, potrzebujesz daty do zamieszczenia w meta-danych commita. Ponieważ data jest użyta w nazwie katalogu, pobierzesz ją z nazwy. Następną linią w pliku print_export jest:

gdzie convert_dir_to_date jest zdefiniowane jako:

Zwraca to liczbę całkowitą dla daty z katalogu. Ostatnią rzeczą potrzebną do zapisania meta-danych są informacje o osobie wprowadzającej zmiany, którą zapisujesz na stałe w zmiennej globalnej:

Teraz możesz rozpocząć wypisywanie danych dotyczących commitów dla swojego programu importującego. Początkowe informacje wskazują, że definiujesz nowy obiekt commit, oraz nazwę gałęzi do której będzie on przypisany, następnie podajesz znaczki który wygenerowałeś, informacje o osobie wprowadzającej zmiany oraz treść komentarza do zmiany, a na końcu poprzedni znacznik commita. Kod wygląda tak:

Wpisujesz na sztywno strefę czasową (-0700), ponieważ jest to najprostsze podejście. Jeżeli importujesz z innego systemu, musisz wskazać strefę czasową jako przesunięcie (ang. offset). Treść komentarza do zmiany musi być wyrażona w specjalnym formacie:

Format składa się z słowa kluczowego data, długości danych do wczytania, znaku nowej linii, oraz na końcu samych danych. Ponieważ musisz używać tego samego formatu, do przekazania zawartości plików w dalszych etapach, stwórz metodę pomocniczą, export_data:

Jedyne co pozostało, to wskazanie zawartości pliku dla każdej migawki. Jest to proste, ponieważ masz wszystkie pliki w katalogu – możesz wypisać komendę deleteall, a następnie zawartość wszystkich plików w katalogu. Następnie Git zapisze każdą migawkę:

Uwaga: Ponieważ spora część systemów kontroli wersji myśli o kolejnych rewizjach jako o zmianach z jednego commita do drugiego, fast-import może również pobrać komendy dla każdego commita, w których można wskazać jakie pliki zostały dodane, usunięte, lub zmodyfikowane i jaka jest ich nowa zawartość. Mógłbyś obliczyć różnice między migawkami i dostarczyć tylko te dane, ale działanie w ten sposób jest bardziej skomplikowane – łatwiej wskazać Gitowi wszystkie dane, a on sam się zajmie obliczaniem różnic. Jeżeli jednak uważasz, że ten sposób jest bardziej dopasowany do danych które posiadasz, sprawdź podręcznik systemowy dla komendy fast-import, aby dowiedzieć się w jaki sposób przekazać jej dane.

Format przekazywania zawartości nowego pliku lub wskazywania zmodyfikowanego z nową zawartością jest następujący:

W tym przykładzie, 644 oznacza uprawnienia do pliku (jeżeli masz pliki wykonywalne, musisz wskazać 755), a inline mówi o tym, że będziesz przekazywał dane zaraz po tej linii. Twoja metoda inline_data wygląda tak:

Używasz ponownie metody export_data, którą zdefiniowałeś wcześniej, ponieważ działa to tak samo jak podczas wskazywania treści komentarza do commita.

Ostatnią rzeczą, którą musisz zrobić, jest zwrócenie bieżącego znaku, aby można go było przekazać do następnej iteracji:

Tylko tyle. Oto cały skrypt:

Jeżeli uruchomisz ten skrypt, otrzymasz wynik podobny do tego:

Aby uruchomić importer, przekaż wynik do git fast-import będąc w katalogu z repozytorium Gita do którego chcesz zaimportować dane. Możesz stworzyć nowy katalog, następnie uruchomić git init w nim, a potem uruchomić skrypt:

Jak widzisz, gdy zakończy się powodzeniem, pokaże Ci trochę statystyk na temat tego co zdziałał. W tym przypadku, zaimportowałeś do jednej gałęzi łącznie 13 obiektów z 4 commitów. Teraz możesz uruchomić git log, aby zobaczyć swoją nową historię projektu:

Proszę bardzo – ładne, czyste repozytorium Git. Warto zauważyć, że żadne dane nie zostały pobrane – nie masz żadnych plików w swoim katalogu roboczym Aby je pobrać, musisz wykonać reset do momentu, w którym teraz jest master:

Możesz zrobić dużo więcej przy pomocy narzędzia fast-import – obsłużyć różne tryby, dane binarne, gałęzie i ich łączenie, etykiety, wskaźniki postępu i inne. Wiele przykładów o bardziej skomplikowanych scenariuszach działania jest dostępnych w katalogu contrib/fast-import w kodzie źródłowym Gita.