ISRM Organization: https://github.com/ISRM-UPB

For those unfamiliar with git: https://gitimmersion.com/

Step 1. Create a github account or login on an existing one

Step 2. Use the invite link received from your Teaching Assistant during the live session

https://gitimmersion.com/lab_01.html

GitHub este o platformă online, pe care dezvoltatorii o pot folosi pentru a stoca și versiona codul lor sursă. Git este un sistem de management și versionare a codului sursă care permite lucrul eficient la un proiect software.

Astfel, Git este utilitarul folosit în terminal, iar GitHub este serverul și aplicația web pe care rulează acesta, locul în care păstrăm repository-ul remote.

Folosim Github pentru:

• Vor fi cazuri când vom strica o versiune a codului și vom avea nevoie să revenim la o versiune corectă, caz în care un istoric de versiuni ne-ar fi de folos. În caz contrar, va trebui să salvăm diferite versiuni a proiectului nostru că niște checkpoints pe PC-ul nostru, ocupând mult spațiu de depozitare.
• Vom putea să lucrăm la un proiect de pe un alt sistem, în afară de al nostru, sau vom vrea să cerem feedback pe codul scris de noi.

• Când vorbim despre un proiect software vrem să avem dezvoltatori, oameni care să lucreze împreună cu noi la proiect. Dezvoltatorii au nevoie de acces la codul sursă al proiectului software la care lucrăm. După ce le dăm acces, vrem ca fiecare dezvoltator să știe la ce a lucrat și la ce lucrează ceilalți; ca să nu se suprapună, ca să ajute și ca să ofere feedback.

• Pentru a putea rezolva problemele de sincronizare între doi sau mai mulți colegi de echipă care lucrează la același proiect, ne ajută să avem un sistem de versionare a codului, adică să avem un istoric de modificări. Fiecare modificare înseamnă o nouă versiune a proiectului; avem astfel o listă de versiuni gestionată de sistemul de versionare a codului. Pe lângă rezolvarea problemelor de sincronizare, versionarea codului aduce și alte avantaje cum ar fi revenirea la o versiune mai veche a proiectului, găsirea rapidă a autorului unei secvențe de cod sau, pur și simplu, organizarea unui proiect.

Înainte de toate, ne asigurăm că avem cont pe GitHub. Dacă aveți deja un cont pe GitHub, puteți trece la subsecțiunea următoare: Pregătirea inițială a mediului Git.

Dacă nu aveți cont, intrați pe GitHub. Pagina de pornire va arăta similar cu cea din imaginea de mai jos.

Introduceți un nume de utilizator (username), adresa voastră de e-mail și o parolă sigură pentru cont. Pentru validarea contului, accesați-vă căsuța de e-mail. Acolo veți găsi un e-mail în care vi se explică cum se poate valida noul cont creat. Verificați și căsuța spam în caz că nu ați primit nimic în inbox.

Înainte să treceți la urmatoarele secțiuni, urmați pașii de mai jos:

1. Autentificați-vă pe GitHub.
2. Mergeți pe această pagină. Vom genera un token de autentificare pentru GitHub.
3. Apăsați pe Generate new token și introduceți parola voastră de GitHub.
4. La câmpul Note scrieți un nume pentru token, ca să știți pentru ce îl puteți folosi ulterior. Spre exemplu, puteți scrie uso-lab.
5. La câmpul Expiration selectați No expiration.
6. La câmpul Select scopes bifați repo Full control of private repositories (se vor selecta automat și căsuțele din lista lui repo).
7. Apăsați pe Generate token.
8. Veți vedea o căsuță verde cu un șir de caractere, salvați-l. Acesta va fi folosit în loc de parolă atunci când vi se va cere parola în linia de comandă.

Ca să utilizăm Git, facem în primă fază niște pași de configurare. Adică vom configura numele și e-mail-ul nostru, ca mai jos:

student@uso:~$ git config --global user.name "Prenume Nume"
student@uso:~$ git config --global user.email "adresa_de_email@example.com"

În listingul de mai sus “Prenume Nume” și ”adresa_de_email@example.com” sunt placeholdere. Le înlocuiți cu datele voastre. De exemplu, pentru autorul acestei secțiuni, comenzile rulate sunt:

student@uso:~$ git config --global user.name "Liza Babu"
student@uso:~$ git config --global user.email "lizababu@example.com"

Această configurare trebuie făcută o singură dată pe PC / Virtual Machine. Pentru a verifica că setările s-au salvat, verificăm rulând acest lucru rulând git config --list.

Pentru a lucra la un proiect software, creăm un repository software. Un repository reprezintă o metodă de împărțire a proiectelor: poate fi o temă la o materie, poate conține chiar toate temele la o materie, în directoare diferite sau poate conține doar un simplu README.md;

Vom crea unul pe GitHub (numit de acum remote), unul local (la noi pe PC), după care le vom interconecta.

Ne autentificăm pe GitHub. Urmărim pașii prezentați în imaginea de mai jos și explicați imediat după.

1. Apăsăm pe săgeata din meniul din dreapta sus și vedem ceva similar cu imaginea de mai sus.
2. Apăsăm pe Your profile pentru a merge pe profilul nostru. Aici este locul în care vom putea vedea contribuțiile noastre pe GitHub. În partea de sus a ecranului vom vedea un meniu orizontal care conține 4 opțiuni: Overview, Repositories, Projects și Packages.
3. Apăsăm pe Repositories. Acum vom vedea întreaga listă de repository-uri pe care le avem. Pentru a crea unul nou, apăsăm pe butonul verde din dreapta sus pe care scrie New.
4. Acum este momentul în care vom da un nume proiectului nostru, o descriere succintă a acestuia și vom putea decide dacă să fie public (vizibil tuturor utilizatorilor) sau privat (vizibil doar pentru noi și eventualii colaboratori ai proiectului). Ne va apărea un formular similar cu cel din imaginea de mai sus. Pentru acest tutorial vom crea un repository public). Este indicat ca numele repository-ului să descrie bine proiectul, în cazul nostru array-sorting-algorithms. Descrierea proiectului este opțională, dar e recomandat să o adăugăm pentru a fi ușor de înțeles pentru cei care vor ajunge la proiectul nostru.
5. Apăsăm pe Create repository. Vor apărea câteva instrucțiuni pentru crearea unui repository local nou și conectarea celui nou cu cel remote. Acest lucru este acoperit în secțiunile următoare.

Acum avem un repository creat remote, pe GitHub, numit array-sorting-algorithms.

Creăm un director din ierarhia de fișiere în care vom inițializa repository-ul Git.

În acest tutorial creăm directorul array-sorting-algorithms în directorul home (adică /home/student sau ~), folosind comenzile de mai jos:

student@uso:~$ pwd
/home/student
student@uso:~$ mkdir array-sorting-algorithms
student@uso:~$ cd array-sorting-algorithms
student@uso:~/array-sorting-algorithms$ git init
Initialized empty Git repository in /home/student/array-sorting-algorithms/.git/
student@uso:~/array-sorting-algorithms$ ls -a
./    ../   .git/

Mai sus am inițializat repository-ul local prin comanda git init, dată în directorul ales (array-sorting-algorithms) din directorul home al utilizatorului student (/home/student).

Acum avem un repository creat local, numit array-sorting-algorithms.

Am folosit opțiunea -a (ls -a) pentru a afișa și fișierele și directoarele ascunse. Directorul .git este un director ascuns.

Am creat până în acest moment un repository local (pe PC-ul nostru) și unul remote (platforma GitHub). Trebuie să le interconectăm pentru a lucra cu ele.

În cazul în care suntem mai mulți membri în echipă, fiecare membru va conecta repository-ul său local, la repository-ul remote. Pentru conectarea celor două repository-uri folosim comanda de mai jos, dată în directorul unde este repository-ul local Git (în cazul nostru /home/student/array-sorting-algorithms):

student@uso:~/array-sorting-algorithms$ git remote add origin https://github.com/{username}/array-sorting-algorithms.git

În comanda de mai sus {username} este numele utilizatorului nostru de pe GitHub. De exemplu, pentru autorul acestui capitol, {username} se înlocuiește cu lizababu.

Conectarea celor două repository-uri înseamnă setarea repository-ului origin, adică repository-ului remote la care se conectează cel local.

Imaginea de mai jos arată cum arată cum se contectează repository-urile remote și local. Sincronizarea lor se face prin intermediul operațiilor push și pull care sunt prezentate pe parcursul secțiunii Primele comitturi.

Odată creat repository-ul, putem să începem să lucrăm la proiect.

Lucrul la proiect înseamnă să adăugăm și să ștergem fișiere sau să modificăm fișiere existente. De obicei este vorba de fișiere text (human-readable), cel mai des fișiere cod sursă¹⁾. Vrem să salvăm aceste adăugări și modificări; apoi să salvăm din nou alte modificări; și tot așa.

Salvarea acestor modificări înseamnă crearea unui commit în repository.

Același lucru îl fac și ceilalți colegi care lucrează la același proiect. Fiecare commit împachetează un set de adăugări și modificări realizate de un dezvoltator al proiectului. Având commiturile în repository putem să gestionăm mai ușor proiectul, adică:

• să revenim la un commit anterior (adesea chiar ultimul) dacă modificările cele mai recente “strică” proiectul
• să vedem cine este autorul anumitor modificări
• să creăm o ramură de dezvoltare separată pornind de la un commit anterior, pe care să încercăm o funcționalitate nouă, fără a afecta restul proiectului

Putem să ne gândim la un commit ca la un checkpoint. Când lucrăm pe repository-ul local, orice modificări aducem sunt doar la noi pe calculator. Asta înseamnă că un coleg cu care lucrezi la proiect nu va vedea ce ai lucrat tu. Astfel că, atunci când lucrăm la un proiect, periodic sau când terminăm un anumit task / o funcție importantă ce vrem să fim singuri că s-a salvat, vom face un commit. Mai exact, salvăm tot ce am lucrat într-un checkpoint cu nume sugestiv (un mesaj de commit) la care vom putea reveni mai târziu în cazul în care stricăm ceva în program.

Git se ocupă de păstrarea și gestiunea istoricului repository-ului nostru prin păstrarea listei de commituri făcute. Adică Git păstrează un istoric de versiuni al proiectului.

Vom vedea în următoarele secțiuni care sunt pașii pentru a crea un commit și pentru a-l publica.

În următoarele secțiuni vom lucra în repository-ul array-sorting-algorithms creat în secțiunea Introducere în Git și GitHub. Vom crea, pas cu pas, un proiect software scris în limbajul de programare C, care conține mai mulți algoritmi de sortare a unui vector de elemente întregi.

Punctual, în această secțiune, vom crea fișierul README al proiectului și scheletul de cod pentru algoritmii de sortare Bubble Sort, Merge Sort și Radix Sort. Vom crea commituri în repository-ul local pentru fiecare schimbare, după care vom publica commiturile astfel încât schimbările să fie vizibile și pe GitHub, în repository-ul remote.

O bună practică, prezentă în majoritatea proiectelor software, este să adăugăm un fișier README în care se află informații despre un proiect. Spre exemplu, în README se află informații despre ce funcționalități are proiectul nostru, cum se compilează un proiect, cum se rulează, pe ce tip de platforme poate fi rulat etc.

Un fișier README este un fișier text. Îl putem crea și îi putem adăuga titlul Sorting Algorithms for Beginners folosind un editor sau, mai simplu și mai direct, folosind comanda de mai jos:

student@uso:~/array-sorting-algorithms$ echo "# Sorting Algorithms for Beginners" > README.md
student@uso:~/array-sorting-algorithms$ ls -a
./         ../        .git/      README.md

Acum avem în repository un nou fișier: README.md. Vrem să reținem acest lucru în repository prin crearea unui commit, primul.

Pașii creării unui commit sunt următorii:

1. Verificăm repository-ului. Cu alte cuvinte, verificăm ce modificări au fost făcute în repository de la ultimul commit.
2. Adăugăm fișierele pe care vrem să le împachetăm într-un commit în staging area, adică în lista de fișiere pe care Git le organizează.
3. Alegem un mesaj de commit. Creăm commitul.
4. Publicăm commitul și pe repository-ul remote.

Detaliem acești pași în continuare.

Prin starea repository-ului înțelegem forma la care am adus proiectul prin modificările noastre. Aceasta include ce fișiere am creat, modificat sau șters de la ultimul commit. Ne interesează întotdeauna starea repository-ului pe care lucrăm.

Pentru a verifica starea repository-ului folosim comanda git status:

student@uso:~/array-sorting-algorithms$ git status
On branch master
 
No commits yet
 
Untracked files:
(use "git add <file>..." to include in what will be committed)
 
    README.md

A doua linie afișată No commits yet ne spune că nu am făcut până acum niciun commit, adică am pornit de la un repository gol.

În ultima parte a outputului se află o listă de fișiere untracked, adică lista fișierelor pe care Git le vede ca nou adăugate în repository-ul curent, dar pe care nu le monitorizează încă. Acest lucru înseamnă că, deocamdată, orice modificare vom face asupra acestor fișiere nu va fi urmărită (tracked) de Git. În cazul nostru, fișierul aflat în starea untracked este README.md.

Un commit va conține o listă de modificări: fișiere adăugate, fișiere șterse, conținut modificat. Un pas intermediar în crearea unui commit este pregătirea modificărilor ce vor fi parte din commit. Acest pas de pregătire înseamnă să adăugăm (add) aceste modificări într-o zonă de lucru pentru Git, numită staging area.

În cazul nostru, vrem să adăugăm fișierul README.md în staging area. Facem acest lucru folosind comanda git add:

student@uso:~/array-sorting-algorithms$ git add README.md

Verificăm ce s-a schimbat în urma adăugării fișierului README.md în staging folosind comanda git status:

student@uso:~/array-sorting-algorithms$ git status
On branch master
 
No commits yet
 
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
 
    new file:   README.md

Primele 2 mesaje afișate au rămas neschimbate. Partea interesantă apare la ultima parte a outputului. Vedem că mesajul a devenit Changes to be commited. Acest lucru înseamnă că acum Git urmărește noile modificări și așteaptă ca modificările să fie adunate într-un commit.

Acum vrem ca modificările de mai sus să ajungă în repository. Pentru aceasta creăm un commit folosind comanda git commit:

student@uso:~/array-sorting-algorithms$ git commit -m "Add README file"
[master (root-commit) b2a590a] Add README.md
1 file changed, 1 insertion(+)
create mode 100644 README.md  
student@uso:~/array-sorting-algorithms$ git status
On branch master
nothing to commit, working tree clean  

Am folosit descrierea Add README file la comanda git commit drept mesaj de commit²⁾. Aceasta este o descriere succintă a modificărilor făcute prin acest commit.

În continuare vom adăuga scheletul de cod pentru algoritmul Bubble Sort în repository. Vom crea un nou fișier cod sursă C bubble-sort.c și vom scrie în el scheletul de cod pentru algoritm. Vom crea un nou commit care va conține fișierul bubble-sort.c. Pentru aceasta vom folosi un editor, precum nano, ca în imaginea de mai jos:

Mai sus am creat un commit cu fișierul bubble-sort.c urmând pași similari cu cei din secțiunea Crearea commitului local:

student@uso:~/array-sorting-algorithms$ git status
(...)
student@uso:~/array-sorting-algorithms$ git add bubble-sort.c
student@uso:~/array-sorting-algorithms$ git status
(...)
student@uso:~/array-sorting-algorithms$ git commit -m "Add Bubble Sort skeleton"
(...)

Conținutul fișierului bubble-sort.c este:

#include <stdio.h>
 
static void sort(void)
{
    // TODO: add bubble sort algorithm here
}
 
int main()
{
    return 0;
}

1. Creați un nou fișier numit radix-sort.c cu următorul conținut:

#include <stdio.h>
 
static void sort(void)
{
    // TODO: add radix sort algorithm here
}
 
int main()
{
    return 0;
}

1. Creați un commit care să conțină fișierul radix-sort.c. Folosiți următorul mesaj de commit: Add Radix Sort algorithm skeleton.
2. Dați comanda de verificare git log. Detaliem outputul comenzii git log în subsecțiunea Verificarea istoricului de commituri.
3. Creați un nou fișier numit merge-sort.c cu următorul conținut:

#include <stdio.h>
 
static void sort(void)
{
    // TODO: add merge sort algorithm here
}
 
int main()
{
    return 0;
}

1. Creați un commit care să conțină fișierul merge-sort.c. Folosiți următorul mesaj de commit: Add Merge Sort algorithm skeleton.
2. Dați comanda de verificare git log.

Până acum am creat commituri care conțineau un fișier nou creat. În această secțiune vom modifica conțintului fișierului README.md și vom crea un nou commit, așa cum apare în comenzile de mai jos:

student@uso:~/array-sorting-algorithms$ echo "We implement 3 sorting algorithms for integer arrays." >> README.md
student@uso:~/array-sorting-algorithms$ git status
On branch master
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

    modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")
student@uso:~/array-sorting-algorithms$ git add README.md
student@uso:~/array-sorting-algorithms$ git status
On branch master
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)

    modified:   README.md

student@uso:~/array-sorting-algorithms$ git commit -m "Update README with project explanation"
t explanation"
[master 247b87f] Update README with project explanation
1 file changed, 1 insertion(+)

Spre deosebire de secțiunea Crearea unui nou commit, unde comanda git status arăta că fișierul modificat (în acel caz, bubble-sort.c) este nou (new file), acum comanda git status arată că fișierul modificat (în acest caz, README.md) a fost modificat (modified). Deși apare această diferență în outputul comenzii git status, pașii pentru crearea unui commit care conține un fișier nou sau unul deja existent (dar modificat) sunt aceiași.

1. Modificați titlul fișierului README.md în # Sorting Algorithm for Integer Arrays.
2. Creați un commit care să conțină modificările la fișierul README.md. Folosiți următorul mesaj de commit: Update README title.

La orice pas al dezvoltării proiectului vrem să știm în ce stadiu ne aflăm ca să ne dăm seama ce am făcut deja și ce trebuie să mai facem în continuare. De aceea folosim un sistem de versionare a codului, în cazul nostru Git. Verificăm istoricul commiturilor folosind comanda git log:

student@uso:~/array-sorting-algorithms$ git log
commit 66b7c5fabb93b521326e6cd9ff219a06a3aec064 (HEAD -> master)
Author: Liza Babu <lizababu@example.com>
Date:   Thu Sep 24 10:40:06 2020 -0700

    Update README title

commit 247b87f3f317816a204c4512f6fd9914527a03ad
Author: Liza Babu <lizababu@example.com>
Date:   Thu Sep 24 09:50:30 2020 -0700

    Update README with project explanation

commit 3c835b0d8e7fc88ef45dfd3681867c21b75ed588
Author: Liza Babu <lizababu@example.com>
Date:   Thu Sep 24 09:45:13 2020 -0700

    Add Merge Sort algotihm skeleton

commit b92a52c0fc5d66dce4b2562114cc84ea326b2763
Author: Liza Babu <lizababu@example.com>
Date:   Thu Sep 24 09:44:36 2020 -0700

    Add Radix Sort algotihm skeleton

commit f65a7fbe8bbe1b36ba5c8e16607456a879bfb6fa
Author: Liza Babu <lizababu@example.com>
Date:   Thu Sep 24 09:21:49 2020 -0700

    Add Bubble Sort algorithm skeleton

commit b2a590a8637f1eab96e557334dbd4be14bf95833
Author: Liza Babu <lizababu@example.com>
Date:   Thu Sep 24 09:09:51 2020 -0700

    Add README file

Fiecare commit este identificat unic printr-un cod, numit cod hash³⁾. Discutăm în continuare despre ultimul commit din listă. Acesta are codul hash 66b7c5fabb93b521326e6cd9ff219a06a3aec064 și mesajul de commit Update README title.

Acum vedem că repository-ul indică spre acest nou commit. Ne dăm seama de acest lucru pentru că HEAD se află în dreptul commitului tocmai făcut. HEAD ne indică starea repository-ului, adică ne arată care este ultimul commit pe care l-am făcut în repository.

Vrem să publicăm pe GitHub toate schimbările făcute, pentru a fi vizibile și altor colaboratori ai proiectului. Publicăm commitul folosind comanda git push:

student@uso:~/array-sorting-algorithms$ git push origin master
Counting objects: 18, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (16/16), done.
Writing objects: 100% (18/18), 1.95 KiB | 222.00 KiB/s, done.
Total 18 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), done.
To https://github.com/lizababu/array-sorting-algorithms.git
* [new branch]      master -> master

În felul acesta commiturile locale au fost publicate (“împinse”, push) din repository-ul local în repository-ul remote identificat de origin. Commiturile locale se aflau pe branch-ul master din repository-ul local și au fost publicate tot în branch-ul master al repository-ului origin.

Ca să verificăm publicarea commiturilor, folosim interfața GitHub:

În lucrul cu Git / GitHub, există bune practici pe care recomandăm să le urmăm.

Atunci când ne apucăm de lucru vrem să sincronizăm repository-ul local cu cel remote. Pot apărea diferențe în momentul în care altcineva a publicat schimbări remote după ce am făcut noi ultima sincronizare. În momentul în care cineva a publicat modificări asupra unei secvențe de cod pe care și noi o modificăm, apar conflicte. Conflictele trebuie rezolvate.

Facem acest lucru prin operația pull, care aduce local toate modificările și încearcă să rezolve conflicetele în mod automat⁴⁾. Dacă rezolvarea conflictelor nu se poate face automat, trebuie să ne ocupăm de acest pas.