Göm menyn

Förberedelse 2: Git och IDEA-projekt

Vi använder versionshanteringssystemet Git för att hålla reda på, och lämna in, både labbar och projekt. Här ska vi:

  • Kortfattat gå genom lite grunder i Git

  • Kortfattat diskutera kopplingen till Gitlab

  • Visa hur du hittar, klonar och öppnar de projekt och filarkiv (repositories) som skapas automatiskt för dig utifrån din anmälan i Webreg
  • Visa hur ett klonat projekt ser ut i IDEA, och hur du använder IDEAs Git-integration i projektet

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 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:

Hur använder vi Git och Gitlab?

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.

Hitta ditt filarkiv, skapa en nyckel

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-2022 / tddd78-labbar-2022-u1a-g08-42 eller TDDE30-2022 / tdde30-labbar-2022-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-2028-u1c-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

Det kan hända att du redan har en SSH-nyckel som är "installerad" i GitLab, till exempel om du använde detta i tidigare kurser. 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.

      Hemma kan du behöva installera Git och/eller Git Bash.

    2. Testa om du redan har en nyckel: cat ~/.ssh/id_rsa.pub. Om filen finns, och börjar med texten 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 om du inte hade en.

      • Kör ssh-keygen -t rsa -C "GitLab" -b 4096
      • 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.
      • 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: cat ~/.ssh/id_rsa.pub, och kopiera sedan nyckeltexten på vanligt sätt.

      Alternativ: xclip -sel clip < ~/.ssh/id_rsa.pub (om xclip finns). Detta kopierar helt enkelt innehållet i filen till clipboard.

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

      Hemma: Leta reda på id_rsa.pub och kopiera den på något sätt.

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

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 Projects följt av 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-2028/tddd78-labbar-2028-u1c-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.)

Från och med 2021 får du också ett "färdigkonfigurerat" IDEA-projekt med en färdig katalogstruktur, några extra klassbibliotek som kan vara bra att ha, exempel på hantering av "resurser" som t.ex. bilder, och så vidare.

IDEA öppnar projektet. Då kan du få en fråga om du litar på projektet, vilket du kan göra i det här fallet. Se säkerhetssidorna för mer information.

Därefter skapas 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

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 från och med 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): Java 17 finns på /usr/lib/jvm/java-17-openjdk-amd64/.

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

Arbeta med Git i IDEA-projektet

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

Du ska 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.
  3. Acceptera att lägga till filen i Git.

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 antingen en dialogruta som ser ut ungefär som nedan eller ett icke-modalt verktygsfönster med liknande utseende. Där bör du 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 ska 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>'.

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

Du ska 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 är allt "säkerhetskopierat", och dessutom kan andra som arbetar i projektet ta del av det du gjort!

    Som du ser ovan finns en del commits som inte du har gjort. Detta är de commits som har gjorts för att skapa "basen" i Gitlab-projektet så du slipper en del av arbetet med konfigureringen.

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.


Sidansvarig: Jonas Kvarnström
Senast uppdaterad: 2022-01-15