Versionshantering är ett sätt att spara ändringshistorik för ett projekt, d.v.s. hur de filer som projektet är uppbyggt av förändrats med tiden. Genom att regelbundet checka in labb- eller projektkod i ett filarkiv ("repository") lagrar du löpande kopior av hur koden har sett ut i olika steg under hela programutvecklingen. Det kan verka onödigt när man bara är ett par personer som jobbar på ett projekt under en kort tid, men kan spara mycket tid och besvär i längden.

• Det blir enkelt att gå tillbaka om man upptäcker att man är på fel väg, utan att manuellt spara versioner ("project", "project-old", "project-newer", "project-170823", ...).

• Man kan ta fram historiken och se vilka filer – eller vilka rader – som ändrats, och när. Man kan också se vem som har ändrat vad. (Detta är också användbart om en misstanke om fusk skulle uppstå -- en anledning att checka in ändringar ofta!) Se manualen.

  

• Det går att se i utvecklingsmiljöer som IDEA exakt vilka "lokala ändringar" man har gjort sedan den senaste incheckningen, genom färgläggning av marginalen till vänster om koden (högerklicka radnumren, välj "Annotate with..."). Enskilda ändringar kan lätt återställas (klicka färgläggningen, få fram hur det såg ut tidigare, välj rollback-ikonen). Se manualen.

  

• Genom att uppdatera projektet från Git kan man infoga andras ändringar (eller egna ändringar utförda på annan dator), utan att behöva skicka kod via epost och själv försöka hålla reda på vad som är nyast. Om någon har ändrat på samma rader som man själv har ändrat "lokalt" får man hjälpa till att välja vilka versioner som ska användas, men man riskerar i alla fall inte att helt missa sådana ändringar.

• Behöver assistenten kolla en eller flera versioner av din kod? Skicka en länk istället för att zippa ihop och eposta hela koden.

• Man får en "automatisk" säkerhetskopia, om något skulle gå katastrofalt fel (man råkar radera fel fil, klippa bort kod som man sedan behövde, ...).

Vi ger kortfattade instruktioner nedan. Bra och tydliga illustrationer av begreppen inom versionshantering finns här, för den som vill lära sig mer:

• A Visual Guide to Version Control (generellt)

• Intro to Distributed Version Control (Illustrated) (tillägg för distribuerad versionshantering, som Git)

Git är ett versionhanteringsystem som används av IDA och väldigt många andra runtom i världen. En skillnad mot många äldre system är att Git är distribuerat, vilket innebär att det inte bara kan finnas ett centralt filarkiv (repository) för ett projekt. Istället kan man ha flera arkiv på olika datorer, och föra över ändringar mellan dem.

GitLab är ett webbaserat system för att hantera projekt. Varje projekt har bland annat ett eget Git-arkiv, men det finns även väldigt mycket annan funktionalitet runtomkring, som att hantera buggrapporter (issues). GitLab är installerat centralt på LiU och där skapar kursledningen projekt med tillhörande filarkiv för alla kursdeltagare.

I den här kursen kommer varje grupp alltså att få ett projekt + filarkiv på gitlab.liu.se, men sedan kommer var och en att göra en klon av arkivet i sin hemkatalog. Arbetar du på egen laptop får du en klon även där. Sedan arbetar man främst mot den egna klonen. När flera personer arbetar på samma projekt har var och en sin egen klon.

För att faktiskt arbeta med filerna ska man checka ut den senaste versionen från den egna klonen av Git-arkivet. De filerna hamnar då i en egen katalog, en arbetskopia, där man gör alla sina ändringar. I en arbetskopia finns bara en version av filerna, "arbetsversionen".

När du har klarat av ett delmoment (eller jobbat färdigt för dagen) uppdaterar du filarkivet med de ändringar du just har gjort: git commit. Detta kan du göra relativt ofta, och eftersom ändringarna bara sparas i din egna lokala klon av filarkivet kan du göra det även om du inte har tillgång till Internet. Längre ner visar vi hur detta görs inifrån IDEA!

När du vill dela med sig av ändringarna till andra ska git commit följas av git push, som i den här kursen "skickar vidare" till arkivet på gitlab.liu.se, som både assistenterna och de andra gruppmedlemmarna också kan komma åt. De kan ju inte "kopiera" direkt från ditt lokala filarkiv.

När nästa person sedan ska arbeta med projektet (eller man ska börja arbeta från en annan dator eller användare som har sin egen arbetskopia) börjar man med att hämta de senaste uppdateringarna från filarkivet: git pull.

Den som är intresserad kan få information om branching (förgreningar) i denna visuella introduktion. Detta är dock inte nödvändigt för kursen.

Då och då kör vi ett script som skapar filarkiv för anmälda webreg-grupper på gitlab.liu.se. Även assistenter/examinator får tillgång, så att de enklare kan granska koden utan att den behöver mailas in. För att just du ska få ett filarkiv krävs då att du:

• Har registrerat dig i Webreg.

• Har loggat in på gitlab.liu.se någon gång, så att ett konto har skapats. Detta bör ni ha gjort redan i tidigare kurser.

För att hitta ditt filarkiv loggar du in på gitlab.liu.se. Du kommer till listan över dina projekt. Där bör du se ett projekt som heter något i stil med TDDD78-2021 / tddd78-labbar-2021-u1a-g08-42 eller TDDE30-2021 / tdde30-labbar-2021-d1a-g01-42, där u1a-g08 är namnet på din "storgrupp" i WebReg och 42 är ett löpnummer. (Finns det inget projekt har du antagligen missat registrering eller inloggning.)

Klickar du på länken hittar du bland annat en URL till filarkivet, på formen git@gitlab.liu.se:tddd78-2020/tddd78-labbar-2020-u1a-g08-42.git. Detta kommer du att behöva snart.

För att "titta" på filarkivet på Gitlab krävs bara den vanliga inloggningen med studentkonto och lösenord. För att skapa en lokal klon/kopia av filarkivet är det istället bäst att varje kursdeltagare har en SSH-nyckel, vilket man först måste skapa om man inte redan har en. Man kan ha olika nycklar på olika datorer (rekommenderas!) och lägga till samtliga dessa nycklar till sitt GitLab-konto.

Skapa SSH-nyckel till GitLab, om du inte har en

Nu när det finns ett filarkiv på GitLab är nästa steg att klona detta arkiv, så att det finns tillgängligt på ditt eget konto.

Att göra: Klona filarkiv

Från IDEA finns flera ingångsvägar till detta:

• I det mindre uppstartsfönstret, som visas när inget projekt är öppet, kan man välja Get from VCS.

• När IDEA redan visar ett projekt använder man menyvalet VCS | Get from Version Control....

Det ska ge följande fönster:

• Se till att Git är valt (inte GitHub).

• Git Repository URL sätts till URL:en för ditt filarkiv på gitlab, till exempel git@gitlab.liu.se:tddd78-2020/tddd78-labbar-2020-u1a-g08-42.git.

  Tidigare år har vi rekommenderat att inte använda en URL som börjar med https: då det inte fungerade bra. Numera kanske det fungerar, men vi rekommenderar ändå ovanstående inloggningsmetod som använder SSH.

• Directory sätts till en katalog där du att projektet ska checkas ut. Filer kommer att skapas direkt i den katalogen, så se till att den inte pekar på en plats där det redan finns filer. Det kan t.ex. vara /home/liuid123/kurser/TDDD78/labbar (du kommer att ha separata arkiv och kataloger för labbarna och för projektet).

  I Windows-salarna är din vanliga hemkatalog monterad som X:\, så om du lägger projektet där är det även tillgängligt från Linuxmaskinerna. Lägg inget på C:\... på universitetets datorer! Inte heller i C:\Users eller liknande. Där kan sakerna försvinna till nästa gång.

• När du trycker Clone kan IDEA fråga efter lösenordet (passphrase) för din SSH-nyckel, om du har ett sådant.

  OBS! Om inget händer när du trycker på Clone så kan det bero på att du kör IDEA i en omgivning där Git saknas eller inte har pekats ut för IDEA. Kontrollera då att Git finns på datorn (Windows: Oftast C:\Program Files\Git\bin\git.exe eller C:\Program Files (x86)\Git\bin\git.exe)). Därefter pekar du ut den åt IDEA genom att sätta Configure | Settings | Version Control | Git |
  "Path to Git executable".

Git klonar nu ditt projekt från Gitlab -- laddar ner alla filer i projektet och deras fullständiga historik. Du får även en underkatalog som heter ".git" som innehåller det lokala filarkivet, inklusive filer som git behöver för att veta var alla filer kom ifrån, hur de såg ut när de checkades ut, och så vidare. Den katalogen kan du ignorera – den är viktig men används bara internt av git-kommandot. (På Windows kan katalogen vara osynlig.)

IDEA öppnar projektet och skapar index för klasser och funktioner som finns tillgängliga i JDK och klassbibliotek. Under tiden kan man börja arbeta med de flesta av IDEAs funktioner. Du kan också välja "Download pre-built shared indexes" för snabbare indexering, om IDEA frågar om detta (kan spara någon minut i första uppstarten).

När ditt klonade IDEA-projekt öppnas kan vissa eller alla av följande saker hända.

Hitta JDK/SDK

IDEA behöver hitta en SDK, Software Development Kit, som innehåller utvecklingsverktyg för det språk vi har valt. För Java är detta alltså ett Java Development Kit, JDK.

Nytt för 2021 är att IDEA är relativt bra på att hitta och konfigurera detta själv, men det kan också hända att du får en fråga om var ett JDK finns. Se hjälpen eller fråga en assistent om något krånglar.

Linux-PUL (SU): Januari 2021 är korrekt sökväg /opt/liu/jdk/15.0.1/bin/java.

External file changes sync may be slow

På labbdatorerna eller via Thinlinc kan IDEA varna för att "external file changes sync may be slow". Detta beror på att er egen källkod ligger på en nätverksdisk och betyder helt enkelt att om ni gör ändringar i filerna utanför IDEA kan det ta något längre tid innan IDEA inser detta och läser om filen. Det är alltså inget problem i praktiken.

Projektfönstret öppnas

IDEA öppnar projektet i ett eget fönster.

Första gången kan detta fönster vara ganska tomt, för att projektvyn är dold. Då öppnas den med Alt+1, genom att trycka på Project uppe till vänster, eller genom att välja View | Tool Windows | Project. Du kan expandera vyn över ditt projekt för att se alla relevanta mappar och filer inklusive externa bibliotek.

Här är ett exempel – det exakta utseendet kan variera beroende på installerade plugins, teman och så vidare.

IDEA frågar om projektfiler ska adderas till Git

IDEAs konfiguration lagras i ett större antal olika filer i katalogen .idea. När du fortsätter använda IDEA kan fler konfigurationsfiler skapas och då får du en fråga om de ska läggas till i Git. De ska läggas till! Vi har redan en .gitignore som ser till att onödiga filer ignoreras.

Välj "View Files". Du kommer att se en popup liknande denna:

Välj "Add" så läggs filerna till i Git.

(Man kan också lägga till filer manuellt genom att högerklicka dem och välja Git | Add, eller genom att använda Git på kommandoraden "som vanligt".

Överkurs: En fil som inte läggs till är workspace.xml. Detta är en lokal "workspace-fil" där IDEA lagrar vilka filer du arbetar med just nu, vilken storlek du har på fönstret, med mera. Om du arbetar med labbarna på flera datorer blir du bara irriterad över att de ändringarna förs över. Dessutom kan det lätt uppstå konflikter när filen ändras på flera datorer.)

Se IDEA-hjälpen för mer detaljerad information om hur man använder Git i IDEA. Använd innehållslisten till vänster på websidan för att navigera mellan de olika Git-relaterade sidorna.

Lägga till filer i IDEA och Git

Varje gång du lägger till en fil i IDEA kommer du att få en fråga om denna fil också ska versionshanteras. Normalt ska den så klart göra det, så svaret är "ja". Detta motsvarar git add på kommandoraden.

Att göra: Lägga till filer

Motsvarande gäller när filer raderas och ska tas bort ur versionshanteringen, motsvarande git remove på kommandoraden.

Checka in / Commit

När du har jobbat ett litet tag och känner att du har kommit framåt kan det vara dags att checka in en ny version i ditt lokala filarkiv. Detta görs med VCS | Commit changes (Ctrl-K). Vänta inte för länge utan checka gärna in ett antal gånger varje dag, när du har gjort några meningsfulla ändringar i koden.

Vid incheckning visar IDEA en dialogruta där du bör skriva en kommentar om de ändringar du har gjort. Det är viktigt att ge en bra beskrivning av vad som har uppdaterats i denna ändring. Dels vill man senare kunna kolla igenom sökhistoriken om man vill hitta den tidpunkt då något specifikt ändrades, dels vill andra som arbetar med samma projekt veta vad som hade ändrats när de uppdaterar med dina senaste ändringar.

Till din hjälp har du ett grafiskt diff-verktyg som visar exakt vad som ändrats sedan senaste versionen. Du kan också välja att formatera om kod (rekommenderat), optimera import-satser (rekommenderat), genomföra kodanalys (välj själva) och/eller kolla efter nya TODO-satser (välj själva).

Att göra: Checka in

På kommandoraden används kommandot
git commit -m '<ditt loggmeddelande>'.

Pusha till Gitlab

För att göra ändringarna tillgängliga för assistenten, andra gruppmedlemmar och dig själv på en annan dator, använder du VCS | Git | Push (Ctrl-Shift-K). Då förs alla de nya ändringarna över från ditt lokala filarkiv till gitlab. På kommandoraden kör du kommandot git push. I kursen är det oftast bra att göra det efter varje commit, men det kan tänkas finnas tillfällen när man vill hålla kod "för sig själv" ett tag.

Att göra: Pusha till gitlab

Kom ihåg Push även om du bara arbetar på en dator, så att assistenterna kan se gruppernas framsteg och hjälpa till vid behov.

Om någon har push:at nya ändringar till det centrala filarkivet efter att du senast hämtade ändringar därifrån, hindrar Git dig från att göra en egen push. Då skulle du ju riskera att skriva över dessa ändringar utan att ens ha sett dem. Istället måste du först uppdatera med "git pull" (se nedan) och därmed infoga de senaste ändringarna från repot. När detta är klart kan du pusha igen.

Hämta uppdateringar (pull)

För att hämta ny kod som någon annan (eller du på en annan dator) har lagt in på gitlab använder du VCS | Git | Pull. Då kommer alla ändringar som checkats in i repot sedan din senaste "git pull" att infogas i ditt lokala filarkiv och i din egen arbetskopia. Det kan vara ändringar som en arbetskamrat har gjort eller ändringar som du själv har gjort på en annan dator. På kommandoraden kör du kommandot git pull.

Denna infogning innebär inte att dina egna filer ersätts av den senaste versionen från repot. Istället tittar git på vilka ändringar som har gjorts (t.ex. att 10 rader har adderats på två olika platser i en fil) och gör sitt bästa för att infoga dessa ändringar på rätt plats i dina egna filer. Om du har egna lokala ändringar som du inte har checkat in ska dessa alltså finnas kvar även efter en "git pull".

Om någon har ändrat på precis samma rad som du kan det vara svårt för Git att se hur ändringarna ska kombinerats. Då får du en konflikt. Exempel:

• Person 1 och person 2 har den senaste versionen från gitlab.
• Person 2 ändrar "äpple" till "päron" på rad 33 och gör commit + push.
• Person 1 ändrar "äpple" till "apelsin" på rad 33.
• Person 1 gör commit och försöker göra push, men får veta att arbetskopian är inaktuell.
• Person 1 gör "git pull" för att få med de senaste ändringarna från gitlab.
• Git försöker införa person 2:s ändring på rad 33, men den raden är också ändrad lokalt. Git kan omöjligen veta om det ska stå "päron" eller "apelsin" på rad 33, om båda ska vara med, eller om det kanske ska vara "fruktsallad".

IDEA hjälper dig att lösa konflikten genom att öppna ett fönster där man ser de två varianterna av filen på var sin sida om en resultatfil där du avgör hur ändringarna ska kombineras. Se instruktionerna för mer information. Fråga gärna assistenterna om det uppstår större problem.