Göm menyn

Förberedelse 2: Filarkiv och IDEA-projekt

Vi använder versionshanteringssystemet Git för att hålla reda på, och lämna in, både labbar och projekt. Därför behöver vi skapa både ett "filarkiv" (repository) i Git och ett IDEA-projekt. Vi ska gå genom detta steg för steg, och även förklara hur Git används under labbarna.

Rapportera eventuella problem så snabbt som möjligt!

Vad är versionshantering, och varför?

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 kännas som 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. Börja nu!

  • 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.

  • 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 manualen, välj Annotate). Enskilda ändringar kan lätt återställas (rollback i figuren nedan).

  • 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 ett versionsnummer 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:

En väldigt kort introduktion till Git

Git är ett versionhanteringsystem som används av IDA och väldigt många andra runtom i världen. GitLab är i princip ett webbaserat gränssnitt till Git-arkiv, som också gör det enklare att hålla reda på Git-arkiv, hantera buggrapporter, och så vidare. GitLab är installerat centralt på IDA och vi skapar konton och filarkiv där för alla kursdeltagare.

En skillnad mot många äldre system är att Git är distribuerat. I den här kursen innebär det att varje grupp kommer att få ett filarkiv på gitlab.ida.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.

För att faktiskt arbeta med projektet ska man checka ut den senaste versionen från den egna klonen. 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.ida.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.

Installera Git hemma

Git finns redan installerat i labbsalarna, både Linux och Windows. Om du kör på egen dator kan du behöva installera det själv.

Om du använder Ubuntu, Mint eller Debian, kan du installera git med:

sudo apt-get install git

På Windows är TortoiseGit en bra grafisk git-klient. För installation på andra system, se https://git-scm.com/downloads

GitLab finns installerat centralt och installeras inte hemma.

Hitta ditt filarkiv, skapa en nyckel

Då och då kör vi ett script som skapar filarkiv för labbar/Tetris på gitlab.ida.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 någon gång, så att ett konto har skapats.

Detta informerade vi om före kursstart, så vi hoppas att alla redan har gjort det. Annars: Gör det nu. Vi kör scriptet flera gånger under första labben.

För att hitta ditt filarkiv loggar du in på gitlab.ida.liu.se. Du kommer till projektlistan där du bör se ett projekt som heter något i stil med TDDD78-2017 / tddd78-labbar-d1a1-42, d1a1 ä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.ida.liu.se:tddd78-2017/tddd78-labbar-d1a1-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 av filarkivet kräver Gitlab istället 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 och lägga till samtliga dessa nycklar till sitt GitLab-konto.

Att göra: SSH-nyckel till GitLab

Det kan hända att du redan har en SSH-nyckel som är "installerad" i GitLab, till exempel om du använde detta i TDDD63. Annars måste du göra följande.

  • Skapa en SSH-nyckel:

    1. I Linux-PUL, öppna en kommandoprompt/shell.

      I Windows-PUL, starta den speciella kommandoprompten Git Bash (finns i startmenyn). Här finns en del Unix-program tillgängliga.

    2. Testa om du redan har en nyckel: cat ~/.ssh/id_rsa.pub. Om filen finns, och börjar med ssh-rsa, kan du hoppa över nästa steg. (Windows: Exakt samma kommando, eftersom vi är i Git Bash.)

    3. Skapa en ny SSH-nyckel.

      1. Kör ssh-keygen -t rsa -C "GitLab" -b 4096
      2. Du blir tillfrågad var nyckeln ska sparas. Använd defaultsökvägen (normalt ~/.ssh/......). Om ssh-keygen säger att det redan finns en nyckel missade du instruktionen om att hoppa över detta steg.
      3. Du blir tillfrågad om ett lösenord (passphrase) för nyckeln. Det krävs inte, men är så klart mycket bättre för säkerheten.
    4. Kopiera den nya eller gamla nyckeln till clipboard.

      Linux-PUL: xclip -sel clip < ~/.ssh/id_rsa.pub (eller klipp och klistra)

      Windows-PUL: Starta en vanlig kommandoprompt (cmd) och kör type Z:\.ssh\id_rsa.pub | clip, eller öppna Z:\.ssh\id_rsa.pub i till exempel Notepad och kopiera den därifrån.

  • Klistra in SSH-nyckeln i GitLab, så systemet vet att den som har motsvarande privata nyckel (du!) ska ha tillgång till ditt konto.

    Gå till profilhanteringssidan och klistra in nyckeln där. Välj "Add key".

    Om Gitlab säger att nyckelns "fingerprint" redan är upptaget, betyder det helt enkelt att din nyckel redan finns där och att du inte behöver lägga till den igen.

  • Om du vill använda en annan dator så är det bästa att registrera ytterligare en public key på samma sätt.

Klona det centrala filarkivet

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 Check out from Version Control längst ner, sedan Git (inte GitHub).
  • När IDEA redan visar ett projekt använder man menyvalet VCS | Checkout from Version Control | Git.

Detta ger följande dialog:

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

  • Parent Directory sätts till en katalog där du vill spara alla filer för TDDD78. Till exempel kan du skapa en ny katalog vid namn TDDD78 i din hemkatalog. I Windows-salarna är din vanliga hemkatalog monterad som Z:\, så om du lägger projektet där är det även tillgängligt från Linuxmaskinerna. Lägg inget på C:\!

  • Directory Name ger namnet på en ny katalog som ska skapas i Parent Directory. Default kommer från URLen, men ändra gärna till t.ex. "labbar" för labbdelen (och senare "projekt" för projektdelen).

  • När du väljer Clone kan IDEA fråga efter lösenordet för din SSH-nyckel.

    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 lägger nu till alla filer och kataloger i senaste revisionen av projektet (om det finns några!) i den valda katalogen, t.ex. ~/TDDD78/labbar. 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.

Windows: Katalogen .git "syns" inte! Eftersom den börjar med en punkt vill Windows Explorer inte visa den. Vill du ändra detta, se här.

Det är möjligt att katalogen som skapas är helt tom, om ingen annan har lagt till filer i det centrala filarkivet. Du behöver ändå gå genom stegen ovan för att katalogen ".git" ska skapas och fyllas med rätt innehåll. Det är på det sättet din katalog blir en arbetskopia där filer kan versionshanteras, och inte bara en vanlig katalog.

Skapa ett IDEA-projekt

Om du just ska börja med labb 1 eller projektet:

  • Du har precis checkat ut ett filarkiv med tillhörande arbetskopia. Det är dags att skapa ett IDEA-projekt i arbetskopian. Det första som händer är faktiskt att IDEA frågar om du vill skapa ett projekt från befintliga källkodsfiler. Eftersom projektet är tomt än så länge väljer du No.

    Istället skapar du ett IDEA projekt i den utcheckade katalogen, t.ex. ~/TDDD78/labbar i vårt exempel.

Om du ska börja med Tetris:

  • Gå vidare med samma arbetskopia som i labbarna.

Att göra: Skapa IDEA-projekt

Nu skall vi skapa ett första IDEA-projekt som ska innehålla filerna för labb 1.

  1. Stäng eventuella öppna projekt (File | Close Project).

  2. Välj "Create New Project" som öppnar följande dialog:

  3. Se till att "Java" är valt i listan till vänster. IDEA har stöd för många andra projekttyper, men nu ska vi programmera i ren Java. Inga "additional libraries and frameworks" behöver väljas.

  4. IDEA behöver hitta en SDK, Software Development Kit, som innehåller utvecklingsverktyg för det språk vi har valt. Det kan hända att ingen Java SDK är konfigurerad. I så fall välj "New..." och sedan "JDK", alltså Java Development Kit.

    Linux: Som standard kan det hända att IDEA tittar i mappen /usr/lib/jvm. Där ligger visserligen några Java-versioner, men inte den vi ska använda, som är nyare. Därför behöver du navigera till mappen /sw/jdk8. Den här mappen pekar automatiskt ut den senaste versionen av JDK 1.8, t.ex. jdk1.8.0_112.

    Windows: Här skall du välja den mapp för Java som troligen ligger i C:\Program Files\Java\jdk1.8.0_112 eller i C:\Program Files (x86)\Java\jdk1.8.0_112.

    Tryck sedan på OK följt av Next.

  5. Vi ska inte välja "Create project from template", så tryck Next.

  6. Ge projektet ett namn vid Project name, t.ex. "TDDD78-labbar". Namnet spelar egentligen inte så stor roll, men det ska vara unikt för varje projekt du skapar.

  7. Tala om för IDEA var projektfilerna skall lagras vid Project location (alla kodfiler kommer att hamna här). Välj katalogen där det klonade filarkivet ligger, samma katalog som innehåller .git. Det kan vara till exempel ~/TDDD78/labbar eller Z:\TDDD78\labbar i exemplet ovan, där vi skapade katalogen TDDD78 i hemkatalogen och sedan angav Directory Name "labbar". Det ska inte vara en underkatalog till "labbar"!

  8. Ett IDEA-projekt består av en eller flera moduler, där varje modul kan användas av flera projekt. Vi kommer enbart att ha en modul per projekt. Ändra följande:

    • Module name kan vara "labbar" för ditt första projekt.

      Om du skapar flera projekt på samma plats (Tetris på samma plats som labbarna) behöver du se till att du har ett nytt namn på modulen, inte samma som i förra projektet.

    • Content root och Module file location kan lämnas som de är.

  9. Expandera "More Settings" och säkerställ att Project format är ".ipr (file based)".

  10. Tryck på "Finish".

Nu har ett IDEA-projekt skapats. Det tar en stund för IDEA att starta upp eftersom den första gången behöver indexera alla de klasser och funktioner som finns tillgängliga för er som standard i Java. Indexeringen kan ta runt en halv minut och sker i bakgrunden. Under tiden kan man börja arbeta med de flesta av IDEAs funktioner.

Fönstret ska nu se ut ungefär så här, men vissa saker kan skilja sig. Till exempel kan src och .iml-filen ligga i en underkatalog.

IDEA varnar 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. Rutan kan stängas (peka på den så ser ni ett kryss att klicka på).

Projektvyn kan vara dold när IDEA startas. Då öppnas den med Alt+1, genom att trycka på 1: 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, för närvarande bara JDK.

Det sista som behöver göras är att lägga till modulfilen lab1.iml och projektfilen lab1.ipr till git. Detta görs genom att markera dem, högerklicka och välja Git | Add. Vi kommer strax att checka in dessa i det lokala filarkivet. Har du inte Git | Add? I så fall har du antagligen inte skapat projektet i arbetskopian, det vill säga den katalog där .git ligger.

Du behöver/bör inte lägga till lab1.iws. 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.

Arbeta med IDEA-projektet

  • 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

    Du skall nu testa hur filer läggs till i git.
    1. Skapa en katalog doc i projektet genom att högerklicka på projektroten och välja New | Directory.
    2. Skapa en fil readme.txt i doc-katalogen genom att högerklicka på katalogen och välja New | File.

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

  • 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.

    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

    Du skall nu testa hur incheckning går till.
    1. Skriv text i readme.txt. Det spelar ingen roll vad, bara läsbar text. Checka sedan in. Första gången du checkar in kan du behöva du ange dina användaruppgifter så andra i projektet senare vet vem som checkat in. Detta behöver bara anges en gång i följande dialog:

    2. Ändra nu i filen genom att ta bort eller lägga till text och checka in. Notera att de ändringar du gjort syns markerat i den nedre delen. Det kan t.ex. se ut så här:

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

  • 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

    Du skall nu testa hur pushning till det centrala filarkivet på gitlab går till.
    1. Välj VCS | Git | Push (Ctrl-Shift-K) för att ta fram dialogen för Push Commits. Det ger en dialog liknande den här :

      På vänster sida syns de olika lokala incheckingar som gjorts och till höger kan man se vilka filer de påverkat. Tryck Push för att skicka vidare detta till Gitlab.

    2. Gå in på GitLab och verifiera att dina ändringar syns. Nu kan andra som arbetar i projektet ta del av det du gjort!

    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 "hämta ny kod" nedan) och därmed infoga de senaste ändringarna från repot. När detta är klart kan du pusha igen.

  • 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.


Sidansvarig: Jonas Kvarnström
Senast uppdaterad: 2018-01-04