Git. Indicații folosire GitLab

Atunci când colaborăm cu alte persoane la un același proiect este necesară folosirea unui sistem de versionare a surselor. Acesta ajută pentru a putea colabora la distanță și rezolvă problemele de partajare ale acelorași surse. Chiar și în cazurile în care suntem singurul dezvoltator al unui proiect, versionarea este indicată pentru că:

  • ajută la identificarea mai ușoară a schimbării care a introdus un bug
  • permite salvarea surselor în diferite stagii ale dezvoltării
  • permite revenirea la o versiune anume a surselor

Câteva exemple de sisteme de versionare sunt:

  • SVN
  • Mercurial
  • Git
  • Perforce

O scurtă analiză a acestora găsiți Version control systems.

Pentru SO propunem folosirea git din varii motive:

  • funcționează foarte bine pentru proiecte ce conțin doar fișiere. (Atenție nu adăugați binare)
  • este un sistem distribuit
  • este light
  • este open-source
  • există instanța GitLab a facultății, unde fiecare student își poate crea până la maxim 10 proiecte.

Folosire GitLab

Așa cum am precizat anterior, Facultatea de Automatică și Calculatoare pune la dispoziție instanța GitLab, accesibilă tuturor studenților și membrilor facultății. Autentificarea se face pe baza contului de pe site-ul de cursuri.

Autentificare GitLab

  1. Accesați instanța GitLab.
  2. Autentificați-vă folosind contul de pe site-ul de cursuri.
  3. Ceea ce vedeți după autentificare este Dashboard-ul user-ului autentificat.

Setare profil și cheie SSH

  1. Accesați Profile settings (dreapta-sus)
  2. În stânga puteți vedea diferite categorii pentru setarea profilului:
    1. informații despre nume și e-mail se găsesc în tabul Profile. Lăsați-le pe cele de pe curs.cs (adresa de e-mail fiind cea de stud.acs.upb.ro)
    2. informații despre cont
    3. setarea felului în care veți vedea codul submis (tab-ul Design)
    4. puteți adăuga chiar și o adresă nouă de e-mail

În cadrul paginii Profile settings foarte important este adăugarea unei chei SSH.

Setare cheie SSH

  1. Generați-vă pe calculatorul vostru (pe Linux sau din Cygwin pe Windows) o cheie SSH:
$ ssh-keygen
  1. Dând enter după fiecare întrebare, veți obține o cheie SSH astfel:
    1. în /home/user/.ssh/id_rsa este cheia privată
    2. în /home/user/.ssh/id_rsa.pub este cheia publică
  2. În tab-ul Profile settings, pagina SSH keys de pe GitLab va trebui să adăugați această cheie astfel:
    1. Dați click pe Add key.
    2. Dați un nume acestei chei.
    3. Copiați conținutul cheii publice anterior generate în căsuța Key

Dacă aveți deja o cheie SSH o puteți folosi pe aceea, fără a mai fi nevoie să vă generați o nouă cheie. Va trebui în schimb să vă asigurați că pe mașina pe care lucrați (fie propriul Linux, fie mașina virtuală Linux de la SO) adăugați cheia privată în /home/user/.ssh/ .

ATENȚIE: Cheia privată SSH oferă acces total la repository și la conținutul acestuia. NU partajați cheia privată cu nimeni altcineva, întrucât acea persoană va avea drepturi depline(citire, modificare, ștergere) asupra repository-ului de pe GitLab, precum și la alte resurse ce folosesc cheia privată pentru autentificare. Recomandarea noastră este să protejați cheia privată cu o parolă(passphrase).

Creare proiect nou

Odată autentificați pe GitLab, din Dashboard în partea stângă apare următorul meniu:

  • Projects: aceasta este pagina de gestionare a proiectelor. Aici puteți vedea toate proiectele în care sunteți implicat: fie ca owner, fie ca viewer/guest, fie ca developer.
  • Activity: care arată activitatea voastră: dacă v-ați alăturat unui nou proiect, dacă ați creat un nou proiect etc.
  • Groups: gestionarea grupurilor și vizualizarea grupurilor existente.
  • Milestones: gestionarea pașilor importanți ce țin de proiectele în care sunteți implicat.
  • Issues: posibile probleme active într-unul din proiectele voastre.
  • Merge Requests: oferă posibilitatea combinării branch-ului default (master-ului) cu un altul (în cazul rezolvării unui bug sau adăugării unui feature).
  • Snippets: bucăți de text ce pot fi făcute private sau publice.
  • Help: documentație GitLab.

Pentru crearea unui nou proiect:

  1. Dați click pe New project (este un + în dreapta-sus, lângă butonul de Profile settings).
  2. Dați numele proiectului: l3-so-assignments (sugerând anul 3 din ciclul de licență, materia SO, repo pentru temele de SO).
  3. Dați o descriere adecvată acestui proiect.
  4. Nivelul de vizibilitate trebuie să fie privat.
  5. Adăugați URL-ul specific repo-ului de teme de SO ce va conține scheletele de cod pentru fiecare temă și testele:
    1. click pe Import existing repository by URL
  6. Click Create project.
  7. După ce proiectul a fost creat, selectați tab-ul Members din cadrul acestui proiect (left side)
    1. adăugați următorii useri: Mihai Bărbulescu (3172), Adrian Șendroiu (1701), Răzvan Tudor Crainea, George Muraru, Alex Morega, Liza-Elena BABU (78556), Petru GURIȚĂ (78543), Adrian-Mirel LUŢAN, Alexandru-Andrei ROTARU (25055)
    2. dați-le dreptul de access Reporter
    3. click pe Add users to project

Acum puteți naviga prin fișierele existente în proiect și prin commit-urile din proiect: Files și Commits.

Adăugare fișiere la un proiect existent

Pentru toate temele de la SO se va folosi proiectul l3-so-assignments. Astfel, în acest proiect se vor găsi în final:

  1. l3-so-assignments/1-multi
  2. l3-so-assignments/2-minishell
  3. l3-so-assignments/3-virtualmemory
  4. l3-so-assignments/4-scheduler
  5. l3-so-assignments/5-aws

Dacă aveți doar 1-multi în acest repo, pentru a adăuga 2-minishell puteți proceda astfel:

git clone ...
cd l3-so-assignments
mkdir -p 2-minishell/
cd 2-minishell/
wget http://ocw.cs.pub.ro/courses/_media/so/teme/2-skel-linux.zip
unzip 2-skel-linux.zip
rm -fr 2-skel-linux.zip
wget http://elf.cs.pub.ro/so/res/teme/tema2-checker-lin.zip
unzip tema2-checker-lin.zip # testele sunt dezarhivate în folderul tema2-checker-lin/
rm -fr tema2-checker-lin.zip
mkdir checker-lin
mv tema2-checker-lin/* checker-lin/
rmdir tema2-checker-lin
cd ../
git add 2-minishell/
git commit -m "add Linux skeleton and tests"
git push

Toată această ierarhie va exista în repo-ul de pe github, pus la dispoziție de echipa de SO. Această secvență de comenzi este utilă dacă vreți să vă creați singuri propria ierarhie. Fiecare temă va fi adăugată pe rând de către echipa de SO în repo-ul so-assignments.

Automatizarea creării unui repo pe GitLab

Echipa de SO pune la dispozție un script pentru automatizarea etapelor prezentate în secțiunea anterioară. Astfel, un student nu va trebui să-și creeze singur proiectul în GitLab și să realizeze toate acele operații pentru a-și clona repo-ul, ci doar va rula acest script.

Acest script este încă în perioada de testare și dezvoltare. Orice probleme întâlniți pe sistemele voastre vă rugăm să ni le raportați. De asemenea, puteți contribui la îmbunătățirea scriptului prin patch-uri sau prin semnalarea unor probleme pe github.

Scriptul este disponibil pe GitHub, în repo-ul public dedicat temelor de SO. Îl puteți descărca local folosind comanda:

wget https://raw.githubusercontent.com/systems-cs-pub-ro/so-assignments/master/so-create-repo.sh

Imaginea următoare prezintă pe scurt entitățile gestionate și acțiunile realizate de către script:

 Workflow-ul scriptului de automatizare

La prima rulare, scriptul va crea un repo privat pe GitLab și o clonă în directorul curent al mașinii unde a fost rulat. În acest moment repo-ul privat al studentului și clona de pe mașina sa vor fi copii fidele ale repo-ului public al temelor de SO.

Inițial scriptul va instala pachetele necesare pentru a rula și va realiza autentificarea cu serverul de GitLab, cerând utilizatorului credențialele de pe curs.cs.pub.ro. Următorul pas este să ofere posibilitatea de a încărca pe GitLab o cheie publică pentru SSH; în cazul în care nu există vreuna pe mașina locală, scriptul va genera o pereche de chei RSA. La final, va adăuga asistenții de SO responsabili de teme ca observatori ai proiectului de pe GitLab.

La următoarele rulări scriptul va încerca să sincronizeze clona locală cu repo-ul public. Astfel, dacă echipa de SO face unele modificări în repo-ul public voi vă puteți actualiza clona locală rulănd scriptul.

Mai departe, puteți interacționa cu repo-ul vostru privat prin git: o operație push va trimite modificările voastre în repo-ul de pe GitLab.

Pentru mai multe informații despre script, urmăriți README-ul asociat repo-ului public de pe GitHub.

Folosire Git

Acum vă puteți clona local (puteți clona pe mai multe mașini, însă trebuie să aveți cheia privată corespunzătoare cheii publice de pe GitLab) acest repo folosind link-ul pentru SSH. Exemplu:

$ git clone git@gitlab.cs.pub.ro:nume.prenume/l3-so-assignments.git
$ cd l3-so-assignments

Puteți adăuga fișiere noi:

$ vim test.c
$ git add test.c
$ git commit -m "my first C file"
$ git push

Câteva tutoriale pentru folosirea Git sunt:

Mic tutorial de folosire git

Pentru a înțelege mai ușor cum și mai ales de ce e bine să folosim git, e cel mai bine să urmărim un exemplu concret. Scenariul propus este de fapt flow-ul de lucru pe care îl urmați la orice temă (nu doar la SO): sunt singur, lucrez la temă, am nevoie de un singur branch și nu vreau să pierd o variantă, să zicem incompletă, dar corectă, de temă.

Pentru acest tutorial, vom lua exemplu o temă de la Structuri de date la care trebuie să se implementeze o listă înlănțuită în C cu toate operațiile necesare (inițializare listă, adăugare element, ștergere element, sortare listă).

Dacă vreți să faceți și ceva practic și să învățați “git by doing” cea mai bună resursă este http://gitimmersion.com/

Pentru ce vă trebuie la SO primele 26 de laboratoare sunt cele mai bune.

Config

Până a ajunge la discuția despre cum să folosim git-ul corect, este bine să aducem în discuție o modalitate prin care putem configura git-ul local. Git-ul vine cu o opțiune numită git config care ne permite să setăm câteva variabile care controlează modul în care git funcționează. Aceste variabile pot stocate în diverse fișiere pe sistemul nostru, însă ce ne interesează în acest moment este fișierul ~/.gitconfig deoarece aici sunt păstrate date pentru utilizatorul curent autentificat în sistem (~) care vor fi văzute de-a lungul tuturor repo-urilor ale acestuia. Mai multe detalii se pot afla aici.

Este important să setăm numele și email-ul nostru în git deoarece fiecare commit va conține aceste informații. Pentru a face acest lucru urmărim următorii pași:

student@vagrant:~$ git config --global user.name "Mr. Perfect"
student@vagrant:~$ git config --global user.email mr@perfect.com

Aceste date pot fi modificate ulterior folosind aceleași comenzi.

Simple tutorial

Acum că avem numele și email-ul setate, putem trece mai departe. Primul pas în lucrul cu git este să inițializăm un repository local în directorul în care vom păstra toate fișierele din temă.

student@vagrant:~$ git init

Vrem să asociem repository-ul nostru local cu unul pe server. Fie că folosim Gitlab, Github, Bitbucket sau orice altă variantă, pașii de urmat sunt neschimbați. Repository-ul precizat trebuie să existe de dinainte.

student@vagrant:~$ git remote add origin link_to_online_repo

Pe git se vor ține doar fișierele sursă, niciodată cele obiect sau executabile, deoarece acestea pot fi generate de fiecare dată când avem nevoie, pe ce mașină avem nevoie foarte simplu dacă avem un fișier Makefile cu reguli corespunzătoare.

Pentru a fi siguri că nu adăugăm din greșeală fișiere inutil în istoric, e necesar să avem în acest director un fisier .gitignore pe care îl adăugăm. În acest fișier se scriu reguli, una pe rând, sub formă de expresii regulate, în care precizăm ce fișiere nu vrem să fie adăugate în acest repo.

După ce am terminat de editat fișierul, îl adăugăm în repository folosind comanda add. E util ca fiecare schimbare pe care o comitem să fie asociată cu un mesaj scurt și la obiect pentru a ști ulterior exact ce schimbare a fost produsă cu acel commit.

student@vagrant:~$ touch .gitignore
# evităm adăugarea fișierelor obiect
student@vagrant:~$ echo "*.o" >> .gitignore
student@vagrant:~$ git add .gitignore
student@vagrant:~$ git commit -m "added .gitignore file to repo"

Pentru a publica schimbările locale și pe server, folosim comanda push.

student@vagrant:~$ git push origin master

De obicei, în cadrul unui proiect mai mare, e recomandat ca fiecare membru să lucreze pe un branch al lui până când e sigur că ceea ce va livra este și ceea ce se dorește să intre în producție, însă pentru scenariul descris în acest tutorial, este OK să folosiți branch-ul default numit master ca fiind al vostru.

În momentul în care ne apucăm de temă, ne vom gândi întotdeauna care sunt milestone-urile pe care le atingem pe parcursul ei. Spre exemplu, putem împărți o tema noastră în următoarele etape:

  • definirea structurilor necesare rezolvării temei (cel puțin în faza preliminară, putem face modificări asupra lor ulterior)
  • citirea și parsarea datelor de intrare (citirea operațiilor care trebuie efectuate asupra listei, pe rând)
  • rezolvarea primelor 5 teste (toate acoperă diverse cazuri legate de adăugarea unui element în listă: la început, la mijloc, la final)
  • rezolvarea următoarelor 5 teste (toate acoperă diverse cazuri în care se șterg elemente din listă: primul element, ultimul element, element după valoare)
  • rezolvarea următoarelor 5 teste (referitoare la sortarea unei liste simplu înlănțuite)
  • rezolvarea următoarelor 3 teste (mixte, adăugări, ștergeri, sortări, iar adăugări etc)
  • rezolvarea următoarelor 2 teste (referitoare la eliberarea corectă a memoriei în momentul ștergerii unuia sau mai multor elemente din listă)
  • eventuale modificări de coding-style (după nevoie)

Este bine ca după fiecare pas enumerat să salvăm versiunea de cod din mai multe motive:

  1. Putem, din neatenție, oboseală sau grabă, să stricăm ce avem până în momentul de față și să ne vină prea greu să revenim la varianta bună de cod
  2. Organizare mai bună
  3. În cazul lucrului în echipă: se poate vedea cine a făcut o anumită modificare a codului

Așadar, după fiecare pas trebuie să publicăm schimbările. Vom folosi următoarele comenzi:

# toate fișierele modificate
student@vagrant:~$ git add changed_file1 changed_file2
# să zicem că am trecut de primele 5 teste 
student@vagrant:~$ git commit -m "first 5 tests working"
student@vagrant:~$ git push origin master

Am greșit, ce fac?

Am continuat cu rezolvarea temei și mi-am dat seama că ceva nu e în regulă și aș vrea să revin la o versiunea în care mergeau doar primele 5 teste. Vom folosim mai întâi comanda git log

student@vagrant:~$ git log
commit ca82a6dff817ec66f44342007202690a93763949
Author: Mr. Perfect <mr@perfect.com>
Date:   Tue Feb 19 16:52:11 2019 -3000
 
    first 10 tests working
 
commit ca82a6dff817ec66f44342007202690a93763969
Author: Mr. Perfect <mr@perfect.com>
Date:   Mon Feb 18 23:52:11 2019 -3000
 
    first 5 tests working
 
commit ca82a6dff817ec66f44342007202690a93763959
Author: Mr. Perfect <mr@perfect.com>
Date:   Mon Feb 18 22:52:11 2019 -3000
 
    parsed input
 
commit ca82a6dff817ec66f44342007202690a93763949
Author: Mr. Perfect <mr@perfect.com>
Date:   Mon Feb 18 21:52:11 2019 -3000
 
    added .gitignore file

În acest caz, commitul căutat este ca82a6dff817ec66f44342007202690a93763969

Pentru a ne întoarce la această variantă folosim comanda:

student@vagrant:~$ git revert ca82a6dff817ec66f44342007202690a93763969

Git tags

Principalul motiv pentru care folosim git este să versionăm codul pe care îl scriem. Așa cum am precizat mai sus, atunci când lucrăm în echipă, este de preferat ca fiecare membru să lucreze pe un branch, iar ulterior codul să fie unificat prin operația de merge.

Până acum am vorbit de commit ca fiind modul prin care diferențiem o versiune de cod de alta. Acest lucru este de regulă folosit în contextul unui branch. Pentru un întreg repository folosim tags pentru a versiona codul. Pentru mai multe detalii în ceea ce privește tag-urile folosite în lumea git, tipuri de tag-uri și modul în care pot fi create și gestionate, consultați pagina de aici aici.

Resurse

so/teme/folosire-gitlab.txt · Last modified: 2019/03/12 08:33 by razvan.crainea
CC Attribution-Share Alike 3.0 Unported
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0