5.2 Distribuerat Git - Bidra till ett projekt

Innan vi går in på användarfallen kommer en kort kommentar om incheckningsmeddelanden. Att ha bra riktlinjer för incheckningar, och att hålla sig till dem, gör det betydligt enklare att använda Git tillsammans med andra. I Git‑projektet finns ett dokument med flera bra tips på saker att tänka på för att göra incheckningar till en ändringsserie. Du hittar det i filen Documentation/SubmittingPatches i Gits källkod.

Först av allt bör dina bidrag inte ha några felaktiga mellanslag. Git har ett enkelt sätt att kontrollera det – innan du gör en incheckning, kör kommandot git diff --check. Det ger dig en lista över möjliga mellanslag som kan vara felaktiga.

Kör kommandot innan en incheckning för att snabbt kontrollera om du är på väg att checka in mellanslag som kan irritera andra utvecklare.

För det andra, försök att göra varje incheckning till en logiskt separat enhet. Om du kan, försök att hålla dina ändringar lättsmälta – koda inte en hel helg på fem olika uppgifter för att sedan skicka dem som en enda gigantisk incheckning på måndag. Även om du inte har checkat in på en hel helg, använd köytan för att dela upp ditt arbete i flera incheckningar på måndagen, med ett tydligt meddelande per incheckning. Om några av ändringarna är i samma fil, försök att använda git add --patch för att delvis köa filer (läs mer i Interaktiv köläggning). Projektets ögonblicksbild längst ut på grenen kommer att se likadan ut oavsett om du gör en incheckning eller fem, så länge alla ändringar läggs till förr eller senare. Försök därför att göra det så enkelt som möjligt för dina kollegor när de ska granska dina ändringar.

Med det tillvägagångssättet blir det också enklare att dra ut eller återställa någon av ändringarna i efterhand, om det skulle behövas. I avsnittet Skriva om historik finns en mängd användbara tips för att skriva om Git‑historiken och interaktivt köa filer – använd dessa verktyg för att få en logisk och förståelig historik innan du skickar arbetet vidare till någon annan.

Slutligen behövs en struktur för incheckningsmeddelandet. Med vanan att alltid skriva bra meddelanden blir användningen av – och samarbetet i – Git betydligt enklare. Tumregeln är att dina meddelanden ska börja med en mening på max 50 tecken som sammanfattar ändringen, följt av en blank rad och en mer detaljerad beskrivning. Git‑projektet menar att beskrivningen bör inkludera anledningen till ändringen och en jämförelse med tidigare beteende – det är en bra riktlinje att följa. Det är också bra att skriva i imperativ form. Med andra ord, ge order. I stället för "Jag lade till test för" eller "Lägger till test för" skriver du "Lägg till test för". Här är en mall ursprungligen skriven av Tim Pope:

Om alla dina incheckningsmeddelanden följer den här mallen blir det lättare, både för dig och dem du samarbetar med. Git‑projektet har välformaterade incheckningsmeddelanden – kör git log --no-merges där för att få inspiration till hur en välformaterad incheckningshistorik kan se ut.

Det enklaste arbetssättet du sannolikt kommer stöta på är ett privat projekt med en eller två utvecklare. I den här kontexten betyder "privat" sluten källkod – den är inte tillgänglig för utomstående. Du och de andra utvecklarna har skrivrättigheter till kodförrådet.

I den här uppsättningen liknar arbetssättet det som du kanske stöter på när du använder Subversion eller något annat centraliserat versionshanteringssystem. Du behåller fördelar som att kunna checka in utan uppkoppling och att ha enkel grenhantering, men arbetsprocessen är mycket lik; den största skillnaden är att sammanslagningar sker i klienten i stället för på servern vid incheckning.

Sedan skickar Jessica upp sina ändringar till servern, vilket går bra:

Den sista raden i utdata är ett nyttigt meddelande. Formateringen är <gammalref>..<nyref> frånref → tillref, där gammalref betyder tidigare referens, nyref är den nya referensen, frånref är den lokala referens som ändringen kommer från och tillref är fjärrreferensen som har uppdaterats. Du kommer att se liknande utdata i exemplen nedan; en grundförståelse gör det lättare att tolka kodförrådets olika lägen.

I det här fallet kan John inte skicka sina incheckningar på grund av Jessicas tidigare incheckning. Det här är särskilt viktigt att förstå om du tidigare har använt Subversion – du kommer att märka att de två utvecklarna inte ändrade i samma fil. Subversion sammanfogar automatiskt på servern om olika filer har ändrats, men i Git måste du själv först sammanfoga incheckningarna lokalt.

Johns kodförråd ser nu ut ungefär så här:

Om den lokala sammanslagningen går smidigt kommer Johns uppdaterade historik se ut ungefär så här:

Nu kanske John vill testa den nya koden för att vara helt säker på att ingen av Jessicas ändringar påverkat hans, och om allt går bra kan han skicka sina sammanfogade ändringar till servern:

Till sist ser Johns incheckningshistorik ut så här:

Under tiden har Jessica skapat en ny gren med namnet issue54 och gjort tre incheckningar till den nya grenen. Hon har inte uppdaterat Johns ändringar än, så hennes historik ser ut så här:

Nu uppdateras Johns incheckade ändringar. Jessicas historik kommer att se ut så här:

Syntaxen issue54..origin/master används för att filtrera loggar. Git ombeds att bara visa de incheckningar i den senare referensen (origin/master) som inte finns på den första referensen (här issue54). Vi går igenom syntaxen i detalj i Incheckningsintervall.

Utifrån ovan ser vi att det bara är en enda av Johns incheckningar som Jessica inte har sammanfogat lokalt. Om hon sammanfogar sina ändringar med origin/master är det bara den incheckningen som påverkar hennes lokala kodförråd.

Allt slogs ihop utan problem, Jessicas historik ser nu ut så här:

Fjärrreferensen origin/master kan nås från Jessicas huvudgren, så hon borde kunna skicka utan problem (förutsatt att John inte har skickat fler ändringar under tiden):

Båda utvecklarna har nu checkat in sina versioner av filerna några gånger och fått in varandras ändringar i sina lokala kodbaser.

Det här är en av de enklaste arbetsprocesserna.

Du arbetar ett tag (ofta i en funktionsgren) och sammanfogar arbetet i huvudgrenen när det är klart. När du vill dela ditt arbete uppdaterar du och sammanfogar din huvudgren med origin/master och skickar tillbaka din huvudgren till servern. Den generella arbetsprocessen ser ut så här:

Nästa exempel gäller ett större, privat team. Här tittar vi på hur arbetsprocessen kan se ut när mindre team samarbetar på funktioner som sedan sammanfogas av andra team.

Säg att John och Jessica arbetar tillsammans på en funktion (vi kallar den "featureA"). Samtidigt samarbetar Jessica och en tredje utvecklare, Josie, på en annan ("featureB"). I det här fallet använder organisationen ett integrationsstyrt arbetsflöde där arbetet från ett enskilt team sammanfogas med huvudgrenen av särskilda ingenjörer. Huvudgrenen kan endast uppdateras av dessa. Allt arbete sker i grenar som sedan sammanfogas senare.

I det här läget behöver hon dela arbetet med John, så hon skickar sin featureA-gren till servern. Jessica har inte behörighet att sammanfoga i huvudgrenen, så hon måste skicka till en separat gren för att kunna samarbeta:

Jessicas kodförråd ser nu ut så här:

Nu vill Jessica skicka allt i featureB tillbaka till servern, men utan att skicka sin egen gren. Eftersom Josie redan har en uppströmsgren featureBee vill Jessica skicka till den grenen. Det gör hon så här:

Detta kallas en referensspecifikation. Se Refspecen för mer information om referensspecifikationer. Lägg också märke till -u; det är kort för --set-upstream och sparar vilken fjärrgren den lokala grenen spårar.

Plötsligt får Jessica ett e-postmeddelande från John, som berättar att han har skickat några ändringar till featureA och ber henne kolla på dem. Återigen kör Jessica git fetch för att uppdatera allt nytt innehåll från servern, inklusive Johns senaste arbete:

Jessica kan nu läsa loggen med Johns senaste ändringar genom att jämföra det som uppdaterats för featureA med den lokala kopian av samma gren:

Om Jessica gillar det hon ser kan hon sammanfoga Johns nya arbete till sin lokala featureA-gren med:

Till sist kanske Jessica vill göra några mindre ändringar i det sammanfogade innehållet. Hon har full frihet att göra sina ändringar, checka in dem i sin lokala featureA-gren och skicka slutresultatet till servern.

Jessicas incheckningshistorik kommer nu att se ut ungefär så här:

Vid någon tidpunkt behöver Jessica, John och Josie meddela de som ansvarar för huvudgrenen att featureA och featureB är redo att sammanfogas. När sammanslagningen i huvudgrenen är klar kommer en uppdatering att ge den nya incheckningen. Historiken ser då ut så här:

Många byter till Git på grund av möjligheten för flera team att arbeta parallellt och kombinera sina grenar sent i processen. Möjligheten att mindre grupper inom ett team kan samarbeta via fjärrgrenar utan att involvera hela teamet är en av Gits stora fördelar. Arbetsprocessen som precis beskrivits ser ut ungefär så här:

Att bidra till öppna projekt är ofta lite annorlunda än privata. Eftersom du vanligtvis inte har behörighet att ändra direkt i projektet behöver förvaltarna få ditt arbete på något annat sätt. I det första exemplet tittar vi på hur man avgrenar ett kodförråd på värdtjänster som tillåter det. Många värdtjänster har stöd för avgreningar (till exempel GitHub, BitBucket, repo.or.cz) och många projektansvariga förväntar sig att andra medverkar på det sättet. Det andra exemplet beskriver arbetsprocessen i projekt som i stället föredrar att ta emot ändringspatchar via e-post.

Det första du behöver göra är troligen att klona grundkodförrådet och skapa en funktionsgren för ändringspatcharna du planerar att bidra med. Flödet ser ut så här:

När arbetet är klart och du vill dela det går du till grundkodförrådets projektsida och klickar på knappen "Avgrena" för att skapa en avgrening som du har full behörighet till. Därefter lägger du till den nya kodförrådets URL som ett nytt fjärrkodförråd; i det här exemplet kallar vi den min-avgrening:

Sedan behöver du skicka arbetet till avgreningen. Det är enklare att skicka funktionsgrenen du arbetar på till ditt kopierade kodförråd än att sammanfoga den i din huvudgren och skicka den. Om ditt arbete inte godkänns, eller om din incheckning inte blir handplockad, slipper du spola tillbaka din huvudgren (läs mer om handplockning i Arbetsflöden med ombasering och handplockning). Om förvaltarna sammanfogar, ombaserar eller handplockar din funktion får du ändå tillbaka den när du drar ner deras ändringar. Hur du än gör kan du skicka arbetet med:

När ditt arbete har skickats till din avgrening behöver du meddela förvaltarna av originalprojektet att du har arbete du vill att de ska sammanfoga. Det kallas ofta en ändringsförfrågan och du gör det antingen via webbsida – GitHub har sin egen mekanism som vi går igenom i GitHub – eller genom kommandot git request-pull och skickar utdatan via e-post.

Kommandot git request-pull tar basgrenen (den gren du vill att din funktionsgren dras in i) och URL:en till kodförrådet som ska acceptera koden, och sammanfattar ändringarna som ska tas in. Om Jessica till exempel vill skicka en ändringsförfrågan till John och hon har gjort två incheckningar på funktionsgrenen hon just har skickat, kan hon göra så här:

Den här utdatan kan skickas till förvaltarna – den beskriver från vilken gren arbetet avgrenades, sammanfattar incheckningarna och anger varifrån den nya funktionen kan uppdateras.

I ett projekt där du inte är ansvarig är det oftast enklast att ha en huvudgren, t.ex. master, som alltid följer origin/master och sedan arbeta i funktionsgrenar som du enkelt kan radera om de inte godkänns. Att isolera funktioner i funktionsgrenar gör det också lättare för dig att flytta ditt arbete om änden i huvudkodförrådet har rört sig under tiden. Om du till exempel vill skicka in en andra funktionsgren till projektet, fortsätt inte att arbeta i den funktionsgren du nyss skickade upp – börja i stället om från kodförrådets huvudgren:

Nu är varje funktion isolerad i ett eget fack – som en kö av ändringspatchar – som du kan skriva om, ombasera och ändra utan att funktionerna påverkar eller blir beroende av varandra:

Om projektets förvaltare har dragit in andra ändringspatchar innan de testar din första gren kan den inte sammanfogas automatiskt. I det här fallet kan du ombasera den grenen till toppen av origin/master, lösa eventuella konflikter och skicka din version igen:

Det här skriver om historiken enligt Incheckningshistorik efter avslutat arbete med featureA.

Eftersom du flyttade grenen behöver du ange -f så att du kan ersätta serverns featureA-gren med en annan incheckning. Ett alternativ är att skicka det nya arbetet till en annan gren på servern (till exempel featureAv2).

Vi tittar på ytterligare ett alternativ: förvaltarna har tittat på ändringarna i din andra gren och gillar dem mest, men vill att du gör en justering. Du använder då möjligheten att flytta avgreningens bas från featureA till huvudgrenen.

Du kan göra detta genom att skapa en ny gren från origin/master, sammanfoga featureB där, lösa konflikter, göra justeringen och skicka det som en ny gren:

Flaggan --squash komprimerar alla incheckningar på grenen som ska sammanfogas till en enda ändring, vilket ger samma status i kodförrådet som vid en sammanslagning. Det innebär att dina framtida incheckningar bara kommer att ha en förälder och ger dig möjlighet att dra in alla ändringar från en annan gren och göra fler ändringar innan den nya incheckningen skapas. Ibland kan det vara användbart att använda --no-commit för att fördröja incheckningen vid en sammanslagning. När detta är klart kan du meddela förvaltaren att ändringarna finns i featureBv2.

Många projekt har egna rutiner för att ta emot ändringspatchar – du behöver kontrollera de regler som gäller för varje projekt, eftersom de skiljer sig åt. Eftersom flera äldre och större projekt bara accepterar ändringspatchar via e-postlistor går vi igenom ett exempel på hur det går till.

Arbetsflödet liknar det i föregående exempel – du skapar funktionsgrenar och arbetar där. Den stora skillnaden är att du inte kan skicka dina incheckningar till ett fjärrkodförråd. I stället skickar du varje incheckning via e-post till en e-postlista för utvecklare.

Nu har du två incheckningar som du vill skicka till e-postlistan. För att generera mbox-formaterade filer som du kan skicka via e-post använder du git format-patch – det gör varje incheckning till ett e-postmeddelande med första raden i incheckningsmeddelandet som ämne och resten av meddelandet plus ändringspatchen som innehåll. Det fina är att när en ändringspatch från ett e-postmeddelande genererat med format-patch appliceras bevaras incheckningsinformationen korrekt.

format-patch skriver ut namnen på ändringspatchfilerna som skapas. Flaggan -M talar om för Git att leta efter omdöpta filer. Filerna kommer att se ut så här:

Du kan också redigera ändringspatchfilerna för att lägga till mer information till e-postlistan som du inte vill ska hamna i incheckningsmeddelandet. Om du lägger till text mellan raden --- och början av ändringspatchen (inleds med diff --git) kan utvecklarna läsa meddelandet, men det ignoreras när ändringspatchen appliceras. Det är en bra plats att förklara varför du gjort ändringarna eller ge testinstruktioner.

För att skicka ändringspatchfilen till e-postlistan kan du antingen klistra in innehållet i ditt e-postprogram eller skicka det via kommandoraden. Att klistra in texten orsakar ofta formateringsproblem, särskilt med "smartare" klienter som inte bevarar radbrytningar och mellanslag korrekt. Som tur är har Git ett verktyg som hjälper dig att skicka korrekt formaterade ändringspatchar via IMAP. Vi visar hur du skickar en ändringspatch via Gmail, som råkar vara den klient vi känner bäst. Du kan läsa detaljerade instruktioner för många e‑postklienter i slutet av filen Documentation/SubmittingPatches i Gits källkod.

Först behöver du sätta upp IMAP-delen i din ~/.gitconfig. Du kan sätta varje värde separat med git config, eller lägga till dem manuellt. I slutänden ska din konfiguration se ut ungefär så här:

Om din IMAP-server inte använder SSL är de två sista raderna troligen onödiga och värdet för host blir imap:// i stället för imaps://. När det är inställt kan du använda git imap-send för att lägga ändringspatchserien i utkastmappen på den angivna IMAP-servern:

Nu borde du kunna gå till din utkastmapp, ändra Till-fältet till e-postlistan du ska skicka ändringspatchen till, lägga till eventuella kopior och skicka iväg den.

Du kan också skicka ändringspatcharna via en SMTP-server. Precis som tidigare kan du sätta varje värde separat med git config eller lägga till dem manuellt i ~/.gitconfig:

När det är inställt kan du använda git send-email för att skicka ändringspatcharna:

Git kommer att ställa en rad frågor om hur du vill att e‑posten ska se ut för varje skickad ändringspatch. De kommer att se ut ungefär så här:

I den här delen har vi gått igenom en mängd olika arbetsflöden för olika slags Git‑projekt som du troligen kommer att stöta på, och introducerat verktyg som hjälper dig att hantera processerna. I nästa del får du lära dig hur du hanterar den andra sidan av myntet: att förvalta ett Git‑projekt. Du får lära dig att vara en välvillig diktator eller integrationsansvarig.