En guide för att arbeta med GitHub Desktop.
- Förord
- Förberedelser
- Terminologi
- Skapa ett repository
- Arbeta lokalt med GitHub Desktop
- Göra ändringar
- Vanliga situationer
- Tips och tricks
Det rekommenderas att följa denna guide från start till slut för att få en bra helhet till hur ni kan arbeta med GitHub Desktop (Git och GitHub). När ni har gått igenom denna guide kan ni ta beslut om vilken arbetsprocess som lämpar sig bäst för ert projekt.
Det finns en hel del skärmdumpar som inte används i denna guiden som eventuellt kan vara till nytta, dessa hittar ni i mappen images i detta repository.
Till att börja med måste ni registrera er på GitHub. Sedan behöver ni installera GitHub Desktop.
I denna guiden används textredigeraren Atom för att den har en enkel integration med både Git och GitHub. Det finns så klart många bra alternativ till denna som Visual Studio Code. Många textredigerare och IDE:er (t.ex. IntelliJ, Eclipse, m.m.) har antingen inbyggt stöd eller plugins som kan integrera med Git och GitHub.
Syftet med Atom i denna guide är att den enkelt hanterar merge conflicts (mer om detta senare), den används alltså inte till programmering.
Nedan finner ni en tabell över några vanliga termer och en kortare beskrivning.
| Term | Betydelse |
|---|---|
| Repository | Ert projekt, dvs. alla era filer. |
.gitignore |
Innehåller sökvägar till filer som inte ska publiceras till GitHub. |
README.md |
Det innehåll som visas när någon besöker projektsidan på GitHub. Formateras enligt Markdown. |
| Add | Lägg till de filer och mappar som redigerats för att sedan spara dom (commit). |
| Commit | Att spara en eller flera ändringar med ett beskrivande meddelande. |
| Branch | En version av ert projekt. Ni skapar en branch varje gång någon vill göra ändringar (commits). |
| Merge | Sammanställ commits från en branch till en annan. |
| Working copy | Den nuvarande branch (version) som ni redigerar. |
| Checkout | Byta från en branch till en annan, dvs. er working copy ändras. |
| Remote | Den plats där era ändringar sparas, GitHub i ert fall. |
| Pull | Hämta commits från er remote. |
| Push | Publicera commits till er remote. |
| Pull request | Skapa ett förslag till en commit som sedan kan mergas, diskussion sker via GitHub. |
| Merge conflict | När en merge från en branch till en annan har filändringar som kolliderar. |
❗ Bara en person per projekt kommer skapa ert repository, ni andra kommer klona detta repository.
När ni har registrerat er och loggat in på GitHub kan ni i huvudmenyn välja att skapa ett nytt repository. På sidan för att skapa ett nytt repository har ni sedan möjlighet att fylla i följande uppgifter:
- Namnet på ert repository.
- En kort beskrivning över ert projekt (valfritt).
- Om ert repository ska vara publikt eller privat (välj publikt).
- Om ert repository ska skapas med en
README.md(checka i denna). - Om ert repository ska skapas med en
.gitignore.- Välj en1, till exempel: Unity, VisualStudio, Java eller Python.
- Om ert repository ska skapas med en licens (valfritt).
1Vi kommer redigera detta i ett senare skede.
Skapa ett nytt repository:
Ert nya repository:
Innan vi går vidare med att skapa mer innehåll i vårt repository så ska vi börja med att lägga till fler användare. Så att vi har möjlighet att börja samarbeta.
Nästa steg är nu att kunna börja arbeta lokalt och detta kommer ske med hjälp av GitHub Desktop. Första gången ni öppnar denna applikationen presenteras ni med följande:
Efter ni startat applikationen första gången ska ni sedan hämta ert repository från GitHub, detta kallas för att klona ett repository. För att göra detta klickar ni på "Clone a Repository [...]" och där ni kan ni sedan välja att logga in med ert GitHub-konto (då får ni tillgång till alla repositories ni har).
Därefter kommer ni i högerspalten se en lista över dessa men klicka istället på klona igen så ni kan välja till vilken mapp ni vill ha ert projekt i.
❗ Vi kommer att fortsätta göra ändringar i detta repository innan ni går vidare med att lägga till alla era egna filer och kan börja arbeta på riktigt.
När ni klonat ert första repository kommer ni till arbetsvyn och det är denna som ni sedan huvudsakligen kommer arbeta med. Denna är indelad i två sektioner, till vänster hittar ni de filer ni gjort ändringar i och till höger hittar ni vilka ändringar som gjorts (baserat på den fil ni markerat i vänsterspalten).
Om ni behöver ändra vilken textredigerare som ska gälla går ni in under inställningar. Välj "Preferences" -> "Integrations" och sedan kan ni byta textredigerare (t.ex. som i mitt fall, till Atom).
I vänsterspalten kan vi välja History istället för Changes vilket ger oss historikvyn som helt enkelt visar all historik över ändringar som gjorts.
Nu när vi är igång ska vi göra vår första ändring (commit) och skicka denna
till GitHub (push). Det första vi ska göra är att se till att vår .gitignore
är i ordning, skulle vi inte göra detta så kommer alla filer vi lägger till i
vårt repository att skickas till GitHub. Vissa filer vill vi endast ska finnas
lokalt och behövs inte finnas centralt på GitHub, till exempel kanske vi har en
fil med lösenord eller så kan det vara så att vår textredigerare skapar
temporära filer som inte heller ska finnas på GitHub.
Eftersom vi nu ska börja arbeta med vårt repository så ska vi skapa vår första
branch (en version av vårt repository). Detta gör vi för att vi ska kunna
arbeta flera stycken parallellt, det vill säga alla har varsin version
(branch) av samma kodbas och på så vis kan alla arbeta lokalt. Det finns
däremot en branch som alltid finns kvar och det är main - denna är
kärnan för hela ert repository.
När vi arbetat klart med vår branch, i detta fallet med .gitignore, kommer
vi att stoppa in våra ändringar i main, detta är vad som kallas att göra en
merge. Anledningen till detta är för att när vi färdigställt vårt arbete vill
vi att de andra i projektet ska kunna hämta dessa commits och fortsätta
arbeta.
Vi börjar med att skapa en ny branch, som vi kan döpa till update-gitignore.
Nu ska vi ersätta det innehåll som förvaldes i vår .gitignore när vi skapade
vårt repository. Det första steget är att bestämma oss för vad som ska
ignoreras, lyckligtvis så finns tjänsten gitignore.io för detta.
När ni söker så tänk på vilket operativsystem ni har, vilken textredigerare,
vilket programmeringsspråk och eventuella bibliotek eller ramverk.
Ett webbrelaterat projekt hade kunnat söka på följande:
Därefter skickas ni till en sida innehållande den text som ska placeras i
.gitignore, kopiera all text.
❗ Om ni utgår från MonoGame kan ni använda denna .gitignore.
I mitt fall hade jag öppnat min textredigerare Atom och klistrat in detta innehållet och sedan sparat filen:
Direkt när jag gjort detta, det vill säga gjort en ändring jag sedan vill spara på GitHub, så öppnar vi GitHub Desktop igen.
För att spara våra ändringar (push), det vill säga vår branch och det nya
innehållet i .gitignore, väljer vi "Publish branch".
Nu ska vår version och ändringar finnas på GitHub. Nu kan vi antingen fortsätta
att arbeta eller, om vi känner oss färdiga med denna versionen, stoppa in våra
ändringar i main (det vill säga en merge). Ett vanligt arbetssätt för
detta är att skapa en så kallad pull request, vilket kort kan beskrivas som
att vår version är redo för att granskas innan den mergas till main.
För att göra en pull request kan ni klicka på "Create Pull Request" där det tidigare stod "Publish branch". Ni kommer därefter skickas till en webbläsare som öppnar följande sida:
Därefter inväntar ni att andra granskar och ger feedback. Klicka inte på "Merge pull request" ännu.
Låt oss nu säga att någon ser att någonting behövs läggas till i vår
.gitignore, i detta fallet får jag simulera det på egen hand.
Kommentaren föreslår att vi ska även ignorera systemfiler från Windows i vår
.gitignore. Då går vi tillbaka till gitignore.io, söker upp
Windows och kopierar in detta innehåll i vår textredigare, det vill säga i
slutet av vår .gitignore.
Därefter sparar våra ändringar (commit) och skickar dom till GitHub (push).
❗ Glöm inte att klicka på "Push origin".
Nu kan vi gå in till vår pull request (på GitHub) och se att vår commit har dykt upp.
Nu känner vi oss redo med vår version och går därför vidare till att stoppa in
vår version (merge) till vår main.
Nu är vi färdiga med vår version (branch), som var till för att skapa
ändringar till .gitignore. Då kan vi radera den både lokalt och på GitHub.
Detta gör vi enklast genom GitHub Desktop, i huvudmenyn hittar ni "Branch" ->
"Delete".
Nästa steg är nu att hämta denna ändringen från GitHub (vår tidigare merge)
till vår lokala main.
Nu kan vi se historiken från vår branch (version) även i vår main.
Nu har ni gått igenom den process som kan nyttjas för alla era ändringar, dock finns det fler metoder men denna är något som ingår i GitHubs egna förslag till att arbeta med Git och GitHub - GitHub flow.
Kärnan för denna metod är att varje gång ni vill göra ändringar skapar ni en
branch, gör de commits som behövs, sedan skapar ni en pull request och
slutligen om allting ser bra ut så gör ni en merge till er main.
Ett alternativ till arbetsprocessen GitHub flow är att istället för att skapa
en pull request så bestämmer vi oss för att göra en merge till vår main
direkt (utan att någon granskar vår kod). Detta har både för- och nackdelar.
En fördel med detta är att processen blir snabbare och nackdelen att det ökar
risken för att någonting blir fel eftersom att ingen kommer granska vår kod.
För större ändringar rekommenderas det att utgå från GitHub flow och för mindre ändringar så kan en enkel merge vara tillräckligt.
Som exempel tänker jag redigera min README.md med en mindre ändring. Vi börjar
med att skapa en branch för denna ändring.
Sedan publicerar vi denna.
Därefter börjar jag göra mina ändringar.
Sedan gör vi en commit av dessa ändringar och därefter publicerar vi detta, "Publish branch" eller "Push origin".
Vi kan nu kontrollera att våra ändringar kommit upp till GitHub.
Nu är nästa steg att utföra vår merge. När vi gör en merge måste vi byta
branch (dvs. en checkout) till den branch vi vill merga till, i vårt
fall är detta vår main.
Sen väljer vi att vi ska merga update-project-description till main.
Konflikter i Git är vanligt förekommande och uppstår oftast när en person ändrar
någonting i en fil på samma ställe som en annan. Konflikten uppstår när vi utför
en merge från en branch till en annan. Till exempel låt oss säga att Lisa
skapar branchen update-readme och Petter skapar readme-edits, sedan gör
Lisa en merge till main, inga problem. Men när Petter sedan gör en merge
till main så upptäcker Git att ändringarna från Lisa krockar med dom från
Petter (till exempel kanske dom båda har ändrat ett par ord i samma rubrik), då
får vi en konflikt och Git kommer markera detta i den berörda filen. Därefter
måste vi bestämma oss för vilken av ändringarna vi vill behålla, det vill säga
den från Lisa eller Petter. Detta kan göras i valfri textredigerare men Atom
löser detta genom att vi enkelt kan klicka på den ändring vi vill behålla och
sedan fortsätta med vår merge.
Det kan vara svårt att förstå hur detta fungerar genom att bara läsa så istället
kommer jag demonstrera detta. I detta fallet kommer jag ha två stycken
branches som båda ska göra ändringar till filen README.md som sedan ska
mergas till min main, men båda dessa branches gör ändringar på samma
ställe vilket innebär att en konflikt kommer att uppstå.
Branch 1: update-working-with, ändringar och sedan en commit.
Branch 2: update-readme, ändringar och sedan en commit.
Merge 1: från update-working-with till main (inga konflikter).
Merge 2: från update-readme till main (en konflikt uppstår).
När vi går vidare (eftersom vi faktiskt vill merga våra ändringar till
vår main) presenteras vi med följande:
För att lösa denna konflikt så väljer jag att öppna Atom genom GitHub Desktop.
När vi har löst vår konflikt (valt vilka ändringar att behålla), så går vi tillbaka till GitHub Desktop och väljer att committa vår merge och sedan pushar vi till GitHub.
Att lösa en konflikt utan Atom innebär bara mer handpåläggning, att istället för
att klicka på "Use me" som i skärmdumparna ovan så kommer ni själva behöva
radera den del av konflikten (det är alltid två delar) som ni inte vill ha kvar.
Låt oss säga att vi får en konflikt där två personer har namnget en rubrik på
varsitt vis. Vår nuvarande branch kommer vara HEAD och den andras ändringar
kommer från branchen update-header, då hade vi kunnat få något likt:
<<<<<<< HEAD
## Översikt
=======
## Innehållsförteckning
>>>>>>> update-header
Här kan vi se de nuvarande ändringarna (dvs. ## Översikt) mot den andres (dvs.
## Innehållsförteckning). Om jag nu vill använda mig av den andras ändringar
får jag själv radera det som Git har lagt till.
## Innehållsförteckning
Så - för att lösa denna konflikten manuellt fick jag radera den övre rubriken
(## Översikt) men även det som märkte upp konflikten (det Git själv lägger
till): <<<<<<< HEAD, ======= och >>>>>>> update-header. Därefter kan jag
enkelt göra en commit igen och sedan fortsätta med min merge.
Ibland är det en bra idé att göra commits för antingen en fil eller flera filer samtidigt. Till exempel om vi lagt till alla våra filer för första gången eller om vi suttit en längre tid och arbetat på flera filer men känner oss färdiga med en och vill sedan spara just den.
Nedan finner ni ett par skärmdumpar som demonstrerar några exempel.
Ni kan i era markdownfiler, till exempel README.md, och i era commit
meddelanden inkludera Emojis. Detta görs genom att ni skriver :smiley: för
:smiley:. Här hittar ni en referenslista för
Emojis.
Att skriva en tydlig README.md är viktigt om ni arbetar i ett projekt med
många deltagare eller om projektet är publikt. Här hittar ni en bra
grundläggande mall och här är en sammanställning över bra skrivna
READMEs.