Git verziókövető rendszer alkalmazása

Git verziókövető rendszer alkalmazása Dokumentum verzió: v2.0 Utolsó frissítés dátuma: 2017.02.20

1 Tartalomjegyzék 1 Tartalomjegyzék... 2 2 Bevezetés... 3 3 msysgit telepítése... 4 3.1 Beállítások... 7 4 Projekt elkezdése... 8 4.1 Új projekt létrehozása... 8 4.2 Projekt letöltése a helyi gépre... 8 4.3.gitignore... 9 5 Fejlesztési folyamat... 10 5.1 Commit... 10 5.2 Push... 11 5.3 Branch... 12 5.4 Merge request... 12 5.4.1 Meld... 15 6 Issue... 17 6.1 Kanban tábla... 18 7 Parancsgyűjtemény... 19 2/19. oldal

2 Bevezetés Ez a dokumentum az IB Controll Kft.-nél alkalmazott GIT verziókövető rendszer használatáról és alkalmazásának módjáról szól. A dokumentum egyes részei megismertetik a GIT VCS rendszert, annak alkalmazását, valamint bemutatja a cégnél alkalmazott konvenciókat a forráskódok változásának követésére. A dokumentum aktuális verziója elérhető az IB Controll Kft. wiki oldaláról (http://wiki.ibcontroll.hu/). A dokumentumból a mindenkori legfrissebb verzió a hatályos. 3/19. oldal

3 msysgit telepítése A helyi gépen található git repository kezeléséhez elsőként szükséges egy program telepítése. Erre a célra mi egy alapvetően konzolos alkalmazást használuk, mellyel minden szükséges művelet elvégezhető. A csomagban található még egy grafikus felület is (Git GUI), egyes funkciók eléréséhez használható. A telepítő a http://git-scm.com/ linken érhető el. A telepítés során az alábbi beállításokat szükséges elvégezni: 4/19. oldal

A git-es parancsok csak a git bash alkalmazásból lesznek elérhetőek, így nem ütközhetnek össze más telepített parancssori alkalmazásokkal parancsaival. A fájlok sorvég karakterén ne módosítson, ahogy feltöltésre kerül, úgy lesz letöltve is. 5/19. oldal

A git bash egy, a Windows parancssortól független terminal-t fog használni, mely támogatja a szövegek színezését, illetve az Unicode karakterek használatát is. 6/19. oldal

3.1 Beállítások Telepítés után a Start Git Git Bash útvonalon, vagy a jobbgomb menüben található a git bash parancssori alkalmazás. A következő parancsokkal beállíthatjuk, hogy milyen névvel és e-mail címmel lásson a rendszer, illetve, hogy SSL verifikálást ne végezzen. Ezen beállítások elvégzése kötelező! git config --global http.sslverify false git config --global user.name <név> git config --global user.email <email> A megadott név és e-mail cím egyezzen meg a gitlab webes felületen megadott névvel és e-mail címmel! 7/19. oldal

4 Projekt elkezdése 4.1 Új projekt létrehozása Ha teljesen új projektet kezdünk, akkor először a https://gitlab.ibcontroll.hu/ címen létre kell hozni egy új projektet a New Project gombbal. Itt ki kell tölteni a projekt nevét, a láthatóság módosítása nem szükséges, maradhat Private-on (a mentoraid amúgy is mindent látnak!). 4.2 Projekt letöltése a helyi gépre A projekt létrehozása után megnyitja annak oldalát, ahol kiírja a szükséges parancsokat, amivel a saját gépre le lehet tölteni az üres projektet, és annak meta-adatait. A parancsokat az előzőekben feltelepített git bash alkalmazásban kell kiadni, egy tetszőleges mappában. Első lépésként meg kell keresni a projekt HTTPS elérési útját, melyet a projekt fő lapján, a legördülő menüben lehet kiválasztani: Így a repository-t inicializáló parancs a következő: git clone https://gitlab.ibcontroll.hu/<csoport_nev>/git_howto_test.git A parancs kiadása után az alkalmazás be fogja kérni a felhasználónevet és a jelszót, amivel a https://gitlab.ibcontroll.hu/ is authentikálunk. Ha a repository letöltése sikeres volt, az alábbi üzenetnek kell megjelennie: 8/19. oldal

Ilyenkor a projekt nevével megegyező mappában létrejön egy.git mappa, amely a működéshez elengedhetetlen fájlokat tartalmazza. Rejtett mappaként a git ezt később nem próbálja meg feltölteni, és kézzel hozzáadni is tilos! Az alábbiakban létrehozunk egy fájlt, majd feltöltjük a távoli repository-ba. Ezt minden új projekt létrehozásakor szükséges végrehajtani! cd git_howto_test touch README.md git add README.md git commit -m "added README" git push origin master A README.MD fájl a gitlab-on egy speciálisan kezelt fájl, a projekt fő oldalán ennek tartalmát láthatjuk. Formázásra a Markdown language használható, melynek leírása itt található: https://gitlab.ibcontroll.hu/help/user/markdown Ez a fájl szolgál különböző, a projekttel kapcsolatos megjegyzés leírására. Rendszerint itt tüntetjük fel pl. a szükséges függőségek helyét, azok telepítési menetét. 4.3.gitignore A.gitignore szintén egy speciálisan kezelt, rejtett állomány, de feltöltése a repository-ba kötelező. Ebben soronként felsorolhatjuk azokat a fájlokat, melyeket nem szeretnénk, hogy a commit közben felajánlásra, vagy később push-olásra kerüljenek. Jellemzően ilyenek a bináris fájlok, képek, ikonok, fordított állományok, fordítás közben keletkező segédfájlok. Ilyen példa fájlok a https://github.com/github/gitignore oldalon fejlesztőkörnyezet és nyelv szerint szétbontva találhatóak. Ezek szabadon felhasználhatók, kibővíthetők. 9/19. oldal

5 Fejlesztési folyamat A fejlesztési folyamatra a Gitflow Workflow használata kötelező. A folyamat fő lényege az, hogy elválassza egymástól a stabil release kódot a fejlesztésben levő kódtól a branchek (5.3) használatával. A branch több commit-ot (5.1) tartalmaz, majd a branch-eket merge request-ek (5.4) segítségével lehet beolvasztani egy másik branch-be. (https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) 5.1 Commit A git-es verziókövetés legkisebb eleme a commit. Egy commit a legutóbbi commit óta történt fájlváltozásokat tartalmazza, lényegében egy snapshot a helyi repository-ról. Minden commit-hoz szükséges megadni egy üzenetet, ami egy rövid leírás arról, hogy milyen változások történtek. Egy commit készítésére a legegyszerűbb mód a git gui használata. A felület négy részre bontható: Unstaged changes: (bal felső) azok a fájlváltozások, melyek nem lesznek hozzáadva a commit-hoz. Innen a mellette levő ikonnal tudjuk átrakni a fájlt a staged changes részbe. Staged changes: (bal alsó) azok a fájlváltozások, melyek hozzá lesznek adva a commit-hoz 10/19. oldal

Fájltartalom: (jobb felső) az ablak tartalmazza a fájl tartalmát. Azok a kódrészek, melyek megszűntek, piros betűvel, az új kód pedig zöld betűvel van feltűntetve, így könnyen elkülöníthető, hogy mik változtak, illetve segít a commit üzenetének megfogalmazásában is. Commit üzenet: (jobb alsó) ebbe a szövegmezőbe kell írni a commit-hoz tartozó üzenetet. Az üzenetre vonatkozó konvenciókra ebben a fejezetben később térünk ki. Miután megírtuk az üzenetet és staged-re állítottuk a szükséges fájlokat, a Commit gomb használatával véglegesíthetjük a commit-ot. Ekkor a gui bezárható, és folytathatjuk a fejlesztést. Egy branch tetszőleges számú commit-ot tartalmazhat, a forráskódot nem befolyásolja. Ajánlott fejlesztés során sűrűn, de logikailag egybefüggő részeket commitolni. A commit üzenetek formájára a konvenció a következő: az első sor egy rövid tartalom, lényegében egy cím, legfeljebb 50 karakter hosszúságban. A cím után egy üres sor, utána pedig kötőjelekkel felsorolva változások. Amennyiben létezik issue az adott problémáról, feature-ről, akkor kötelező feltüntetni az issue számát (pl.: #33) is. Az issue-król bővebben a 6 fejezetben lesz szó. 5.2 Push A commit-ok ilyenkor még csak a helyi gépen találhatóak meg. Ahhoz, hogy ezek a gitlab felületén is megjelenjenek, illetve, hogy a projektben résztvevő többi fejlesztő is lássa, fel kell push-olni a git bash segítségével. Erre szolgál az alábbi parancs: git push origin <branch neve> Ekkor az eddig fel nem töltött commit-ok felkerülnek a gitlab rendszerén belül a megadott branch-be, mások is láthatják, véleményezhetik, illetve le is tölthetik. Push használatára nincs szükség minden commit után, elegendő egy nagyobb funkció, vagy a munka végén feltölteni a változásokat. Fontos, hogy a gui-t csak commit összeállítására használjuk! Igaz, hogy push-olni is lehet, de az nem mindig a várt eredményt hozza, könnyen el lehet rontani. 11/19. oldal

5.3 Branch A kiadott commit-ok és push-ok mindig branch-re vonatkoznak. A branch-ek egymástól független, párhuzamos fejlesztési ágak, melyek nincsenek kihatással egymásra. Új projekt nyitásakor csak a master branch létezik. Ez az ág szolgál a release-re szánt kódnak. Ide közvetlenül soha nem történik push, kizárólag a develop ág merge-elésével kerülhet kód. Másik kitüntetett szereppel rendelkező branch a develop. Ide lesznek merge-elve a különböző egyéb ágak kódjai. Ebben az ágban még lehetnek hiányos feature-k, bug-ok, de mindig csak olyan kód kerülhet fel, ami hiba nélkül lefordul! Egy repository tetszőleges mennyiségű branch-et tartalmazhat. Ezek elnevezésére az alábbi prefix-konvenciót alkalmazzuk: feature-: nagyobb funkciókat tartalmazó branch (pl. feature-dbconnector, feature-usermanagement) enh(ancement)-: funkciók bővítését tartalmazó branch (pl. enh-login, enhdataexport) fix-: kizárólag hibajavításokat tartalmazó branch Branch-ek létrehozására az alábbi paranccsal van lehetőség: git checkout -b <branch neve> Ebben az esetben kapunk egy új branch-et, melynek kódja megegyezik azzal amelyik branch-ből nyitottuk. A legtöbbször ez a develop lesz. A -b kapcsoló elhagyásával csak a már létező ágak közt tudunk lépkedni. Ekkor a helyi gépen levő kód átáll annak a branch-nek a kódjába, melybe beléptünk, az előtte megírt kód a régi ágon módosítás nélkül megmarad. 5.4 Merge request Branch-ek egymásba olvasztására merge request szolgál, melynek kiadására a gitlab felületen a Merge Requests lapon van lehetőség: 12/19. oldal

Új request létrehozásakor először meg kell adni, hogy mely branch-et (bal mező) szeretnénk melyik branch-be merge-elni. Ebben a példában a két branch a featuregoodbye illetve a develop lesz. 13/19. oldal

A következő lapon a szükséges megadni a request nevét, leírását, illetve, hogy kire szignáljuk a request-et. Ennek a felhasználónak lehetősége lesz átnézni és elfogadni a request-et, ezzel a fejlesztési ág (jelen esetben a feature-goodbye) be fog kerülni a develop ágba. Ekkor még átnézhetjük a merge-be kerülő commit-okat, illetve az egyes fájlokon történt változásokat. Véglegesítésre a Submit merge request gombbal van lehetőség, aminek hatására a felhasználó, akire szignálva lett a merge, e-mail értesítést kap a megadott címére. Fontos megjegyezni, hogy a request-ek branch-ekre vonatkoznak! Tehát ha már egyet kiküldtünk, de még nem került elfogadásra, bármilyen módosítás amit a source branchen végzünk, automatikusan a merge része lesz! A kiadott merge oldala a következőképp néz ki: A képernyő alján a Changes fülön fájlokra bontva mutatja a változásokat, bal oldal a cél ág (jelenleg a develop), a jobb oldal a forrás ág (jelenleg a feature-goodbye). Zöld háttéren azokat az új sorokat jelzi, amik a kódba kerültek, pirossal pedig a törölt kódrészeket. Egyes esetben a zöld Accept Merge Request gomb helyett egy felirat található, miszerint This merge request contains merge conflicts. Ekkor a gitlab automatikus merge funkciója nem tudja eldönteni, hogy hogyan olvassza össze a két branch kódjait. Ilyenkor 14/19. oldal

kézzel kel megoldani a conflict-ot. Mi a Meld (5.4.1) nevű alkalmazást használjuk erre a célra. 5.4.1 Meld A Meld (http://meldmerge.org/) segítségével két fájl tartalmát hasonlíthatjuk össze, melyekből igény szerint egy harmadik állítható össze. Jelen esetben ez a két fájl a távoli (jobb oldal) és a helyi (bal oldal) állapota ugyanannak a kódfájlnak. A középső oszlopban az a fájl található, melyet a gitlab magától megpróbált összeolvasztani. A fenti példában a bal oldali oszlop rendelkezik egy olyan üres sorral, ami a jobb oszlopban nem szerepel. Ezt zölddel jelöli, és a mellette található nyíllal lehet átmásolni a középső blokkba is. Ezzel együtt szükséges lesz az üres sor másolása a jobb oldalra is, így a kód azon része már megegyező lesz. A pirossal jelölt sor egy olyan részletet tartalmaz, mely mindkét branch-en megváltozott (a jobb oldalon Goodbye szerepel a Bye helyett). Ekkor el kell dönteni, hogy mely részletet szeretnénk megtartani, és a megfelelő nyíl ikonnal átmásolni a középső, illetve a harmadik oszlopba is. Sikeres merge esetén a három oszlop tetején megjelenik egy felirat, miszerint a fájlok megegyeznek. Ekkor már csak el kell mentenünk a kész fájlokat, bezárni a Meld-et, és így az adott fájl conflict-ja feloldásra került. Miután minden fájl javításával végeztünk, kötelező 15/19. oldal

lefordítani és letesztelni az eredményt, hogy valóban sikeres volt-e a merge, nem töröltünk-e valamilyen kódrészletet tévedésből. Az ütközések feloldásának ezen formája először bonyolultnak tűnhet, de némi gyakorlás után gyorsan el lehet őket végezni. Amire nagyon oda kell figyelni az az, hogy a conflictok feloldása közben ne töröljünk olyan kódot, melyet kollegánk már sikeresen beolvasztott az adott ágba! 16/19. oldal

6 Issue A gitlab felületén lehetőségünk van issue-k felvételére. Ezek olyan hibajegyekhez hasonlítható objektumok, melyet felhasználóhoz rendelhetünk, adhatunk neki címkéket, mérföldkövet. Issue-kban szokás felírni implementálásra váró feladatokat, talált bugokat, lényegében bármit, ami a projekthez kapcsolódik. Ezeket a többi fejlesztő is látja, módosíthatja, hozzászólást írhat hozzá. Új issue felvételekor kötelező megadni egy rövid, de beszédes nevet, és egy hosszabb leírást. Ez a leírás ugyanazt a Markdown-t használja, amit a 4.2 fejezet README.MD-je is. Az egy issue-hoz hozzáadott felhasználók e-mail értesítést is kapnak minden, az adott issue-hoz tartozó eseményről (úgy, mint merge request esetében is). Minden létrehozott issue-hoz tartozik egy azonosító. Ezek a számok projektenként egyedi, 1-től automatikusan növekvő számok. Az issue-kra ezekkel a számokkal tudunk hivatkozni a gitlab felületén belül, melynek formátuma #<issue szám> (pl.: #33). Ezek feltüntetésére legtöbbször a commit-ok és merge request-ek üzenetében van szükség. Ilyenkor a gitlab automatikusan linkké fordítja a szöveget, és rögtön meg is tudjuk nyitni az adott issue-t. 17/19. oldal

6.1 Kanban tábla A kanban módszer először az 1940-es években tűnt fel a Toyota gyáraiból egy újraértelmezett gyártási folyamat eredményeképp. Azóta népszerű eszköz lett más munkafolyamatoknál is, például az agilis szoftverfejlesztést alkalmazó csapatok körében. A csapat tagjainak munkája a kanban tábla köré összpontosul. Ez olyan eszköz, mellyel könnyen vizualizálható a munkafolyamat, a hátralévő feladatok mennyisége, illetve, hogy ki milyen feladatokat végez/végzett a projekt életciklusa alatt. A tábla lehet fizikai vagy elektronikus, funkcióját ugyanúgy betölti, minden esetben hasznos és látványos megoldás. A Gitlab-on belül az Issue menün belül a Board almenüben található. A táblán a feladatok (issue-k) kártyákként jelennek meg. Egy ilyen kártyán látható az issue neve, annak száma (kattintásra az issue adatlapjára navigál), és a feladatra kijelölt felhasználó profilképe. A feladatok alapvetően három oszlopba helyezhetők el, ezek a Backlog, a Development és a Done. Ezeket természetesen tetszőleges számú csoporttal egészíthetjük ki. Mi ezek mellett használjuk még a Testing és Ready oszlopokat is. A feladatok az oszlopok közt drag-and-drop megoldással mozgathatók, ekkor az issue címkéi is eszerint változnak. A Done oszlop emellett kitűntetett funkcióval bír, az ide mozgatott issue-k lezárt állapotba kerülnek. Az issue-k ezen felül mérföldkövek alá is beoszthatók. Ennek segítségével megoldható, hogy a táblán csak a következő mérföldkő végéig elvégzendő feladatok jelenjenek meg. A szűrők a tábla feletti legördülő menükkel állíthatók be. 18/19. oldal

7 Parancsgyűjtemény Az alábbiakban található lista nem teljes, de a leggyakrabban használt git parancsokat tartalmazza. git config --global user.name <felhasználónév> Felhasználónév, ami a commit-ok mellett megjelenik git config --global user.email <email> E-mail cím, ami a commit-ok mellett megjelenik git pull Fájlok letöltése a távoli repository-ból git status Változott és új fájlok listája git commit -m "<commit üzenet>" Commit-ra jelölt fájlok commit-olása git push Commit-ok feltöltése a távoli repository-ba git checkout <branch neve> Branch váltás git checkout -b <branch neve> Branch létrehozása és váltás 19/19. oldal