Gource - Vizualizácia vývoja projektu

Používate pri vývoji svojho projektu softvér pre správu verzií (version control) a chceli by ste sa pozrieť, ako sa váš projekt s postupom času rozrastal a vyvíjal? Potom je pre vás Gource to pravé! Tento pekný kus softvéru vytvorený v jazyku C ++ generuje animáciu vývoja projektu podľa času vydávanie jednotlivých snapshotov (COMMIT). Ako taká animácie vyzerá sa môžete pozrieť napríklad na tomto videu:

Ako ste si pravdepodobne domysleli, každý bodka znázorňuje jeden súbor a jeho farba sa líši podľa prípony súboru. Čiary medzi skupinami súborov potom predstavujú adresárovú štruktúru projektu (rozdelenie súborov do priečinkov) a drobné postavičky autormi COMMIT. Kedykoľvek nejaká postavička "posvieti" na nejaký súbor, znamená to, že súbor upravuje, vytvára, alebo maže.

Animácia sa dá do pomerne veľkej miery prispôsobiť, či už zmenou farby pozadia, skrytím jednotlivých prvkov animácie alebo zmenou časového intervalu venovanému jednému dňu histórie vývoja. Ako tieto veci ovplyvniť si povieme ďalej v článku.

Inštalácia

Gource si stiahneme z oficiálnej stránky projektu https://gource.io/. Stiahneme si spustiteľný inštalátor, spustíme ho a preklikáte jednotlivé kroky. Druhou možnosťou je stiahnuť si inštalátor z GitHub repozitára, na ktorom je celý projekt hostovaný. Po inštalácii nám na ploche nepribudne zástupcu pre spustenie, ako ste možno zvyknutí u iných aplikácií. Gource sa totiž ovláda z príkazového riadku.

Prvá animácia

Teraz už na spustenie našej prvej animácie. Otvoríme okno "Spustiť" stlačením kombinácie klávesov Win + R a zadáme text cmd. Potom už len stlačíme Enter a príkazový riadok sa otvorí. Gource nevyžaduje, aby bol príkazový riadok spustený s administrátorskými právami.

Teraz sa potrebujeme dostať do zložky, v ktorej máme svoj verzovania projekt. Pokiaľ práve žiadny nemáte, naklonujte si ľubovoľný open-source projekt treba z GitHub. Adresár, v ktorom príkazový riadok operuje, môžeme zmeniť príkazom cd. Ak je napríklad váš projekt uložený v priečinku C:\Users\Jarda\source\SuperKalkulacka, vykonajte príkaz:

cd C:\Users\Jarda\source\SuperKalkulacka

Malá vychytávka: V prieskumníkovi súborov môžete kliknúť na adresný riadok a nahradiť cestu textom cmd. Po potvrdení Enter sa vám rovno otvorí príkazový riadok v danom adresári.

Konečne môžeme animáciu spustiť. Nie je to nič zložité, skrátka napíšeme do konzoly gource a stlačíme Enter. Gource si podľa informácií uložených v skrytej priečinku .git/ načíta log zmien a začne generovať animáciu so základnými nastaveniami:

Animáciu môžeme kedykoľvek pozastaviť alebo znovu spustiť medzerníkom. Stláčaním kurzorových šípok alebo ťahaním myši pri držaní ľavého tlačidla posúvame kameru, posúvaním myši pri držaní pravého tlačidla kameru natáčame.

Nastavenia animácie

Štýl animácie môžeme upraviť použitím argumentov v príkaze gource. Ich kompletný zoznam si môžeme v angličtine prečítať na wiki projektu na GitHub, alebo sa nám tiež zobrazia po zadaní príkazu gource --help do príkazového riadku. Tie najdôležitejšie si tu však uveďme, aby sme boli schopní po prečítaní tohto článku nastavovať základné animácie a nemuseli študovať ďalšej dokumentácie inde.

Rýchlosť animácie

Asi najviditeľnejšou úpravou je zmena rýchlosti animácie. Gource nám umožňuje nastaviť, koľko sekúnd bude venované animáciu jedného dňa histórie. Základné nastavenie je 10 sekúnd, čo môže byť pre väčší projekt príliš pomalé. Ak chceme, aby animácie jedného dňa trvala len dve sekundy, docielime to nasledujúcim príkazom:

gource -s 2

Rovnaký výsledok dosiahneme aj v prípade, ak miesto -s použijeme --seconds-per-day. Je len na nás, či budeme používať rýchlejšie, alebo deskriptivnější zápis.

Nespoliehajte na to, že ak bol projekt vyvíjaný od 1. apríla do 30. apríla a parameter -s je nastavený na 5, bude celá animácia trvať 300 sekúnd. Gource automaticky preskakuje animáciu časových periód, počas ktorých sa do projektu neprispievalo. Toto je možné obmedziť ďalšími nastaveniami, avšak základni sa Gource posunie v čase k ďalšiemu commit, ak sa na 3 sekundy nič nedeje.

Druhou možnosťou, ako ovplyvniť dobu trvania animácie, je nastavenie celkovej doby relatívne k základnému nastaveniu. To docielime parametrom -c (alebo --time-scale). Základni je toto nastavené na 1.0, čo znamená, že parameter nijako dobu trvania animácie neovplyvní. Ak namiesto 1.0 zadáme napríklad 2.5, bude celá animácia 2,5 × rýchlejší. Pri zadaní 0.1 zase 10 × pomalší. Toto nastavenie automaticky zvýši alebo zníži počet sekúnd, ktoré sú venované jednému dňu histórie. Spustením animácie nasledujúcom príkazom sa tak dostaneme opäť na predvolené rýchlosť:

gource -s 20 -c 2.0

Úprava skákanie v čase

Pokiaľ má projekt vo vývoji diery, počas ktorých sa do neho neprispievalo, Gource je automaticky bude preskakovať, ak by sa nemalo v animácii zobraziť nič nové po dobu dlhšiu ako 3 sekundy. Tento časový údaj môžeme samozrejme tiež upraviť, a to parametrom -a (--auto-skip-seconds). Spustením animácie sa budú nasledovne preskakovať etapy vývoja, ktoré by boli v animácii nemenné po dobu dlhšiu ako 1 sekunda:

gource -a 1

Niekedy môže byť nežiaduce, aby čas v animácii neplynul konzistentne. V takom prípade môžeme túto funkciu vypnúť parametrom --disable-auto-skip:

gource --disable-auto-skip

Orezanie animácie

Môže sa stať, že budeme chcieť spustiť animáciu vývoja iba pre novšiu verziu, alebo naopak iba z doby začiatku projektu. Parametre --start-date a --stop-date môžeme tieto časové míľniky vymedziť. Ak nezadáme --start-date, bude sa animácia prehrávať od začiatku vývoja a v prípade nepridelení --stop-date pobeží animácie až do konca. Tento príkaz spustí animáciu vývoja projektu počas školského roka 2019/2020:

gource --start-date 2019-09-01 --stop-date 2020-06-30

Nastavenie veľkosti okna

Okno, v ktorom sa animácia spúšťa, má základni nastavenú nejakú veľkosť. Ak vám táto veľkosť nevyhovuje, môžeme jej zmeniť. To vykonáme zadaním požadovanej výšky a šírky okná za dve pomlčky a oddelíme je malým písmenom X. Šírka sa zadáva ako prvý:

gource --800x600

Animáciu môžeme spustiť aj v režime na celú obrazovku pomocou parametra -f (--fullscreen). Režim celej obrazovky môžeme kedykoľvek ukončiť klávesom Esc.

Nastavenie kamery

Kamera (pohľad na animáciu) sa základni automaticky natáča tak, aby bol zobrazený celý strom súborov a zároveň nebolo približovanie a odďaľovanie príliš prudké. Parametrom --camera-mode môžeme toto zmeniť tak, aby kamera sledovala vždy aktívny prispievateľa do projektu. Tento parameter môže byť nastavený na:

• overview (základné nastavenie), alebo na
• track (sledovanie prispievateľov).

Tieto módy zobrazenia môžeme prehodiť aj kedykoľvek počas prehrávania animácie stlačením klávesy V:

gource --camera-mode track

Skrytie prvkov animácie

Pokiaľ bude animácie obsahovať napríklad mnoho popiskov súborov, môže sa stať neprehľadnou. Preto umožňuje Gource skryť jednotlivé prvky animácie, ako sú napríklad prispievatelia, popisky zložiek, alebo samotné súbory. To môžeme vykonať parametrom --hide, za ktorý napíšeme zoznam prvkov, ktoré chceme skryť, oddelené čiarkou. Tieto prvky môžeme špecifikovať slovami:

• bloom,
• date,
• dirnames,
• files,
• filenames,
• mouse,
• progress,
• tree,
• users a
• usernames.

Čo každej z nich skryje je asi jasné, snáď len bloom si zaslúži objasniť. "Bloom", alebo po slovensky "kvet", je efekt žiara okolo skupín súborov:

gource --hide dirnames,filenames,usernames

Elasticita a žiara

Toto sú už skôr estetická nastavenia. Pomocou parametra -e (--elasticity) môžete nastaviť, ako veľmi sa budú "vlniť" jednotlivé vetvy štruktúry projektu, keď sú nútené sa posunúť. Pomocou --bloom-multiplier môžeme zmeniť polomer efektu žiara okolo zložiek (podobne ako u parametra -c zlomkovej) a pomocou --bloom-intensity zase silu žiara (základni je nastavené na 0.75).

Zobrazenie počtu súborov

Parameter --key nám zobrazí v ľavom hornom rohu počet a farby súborov, podľa ich prípony. Toto môžeme zapnúť aj vypnúť kedykoľvek počas animácie stlačením klávesu K.

Zmena farby súborov

Možno vás napadlo, že by ste chceli bodkám reprezentujúci používateľa alebo súbory s určitou príponou priradiť špecifickú farbu. Napríklad .html súbory by mohli byť oranžové, .css svetlo modré, .js žltej a .php fialovej. Bohužiaľ vás musím sklamať, aj cez početné návrhy na vylepšenie toto Gource stále neumožňuje. Môžete však stláčaním tlačidla S farby zmeniť náhodne. Farby sa generujú podľa "semienka", čo je číslo, ktoré generátor farieb spracuje a podľa neho rozdelí farby. Toto semienko (anglicky "seed") môžeme nastaviť manuálne pomocou parametra --hash-seed. Ak použijeme vždy rovnaké semienko, budú aj farby súborov a používateľov vždy rovnaké:

gource --hash-seed 73

Pokiaľ objavíte nejaké, u ktorého farby súborov zodpovedajú očakávania, môžete sa o neho v komentároch pod článkom podeliť:)

Odporúčaná animácie

Ak sa vám nechce zostavovať príkaz na spustenie animácie od začiatku a radšej by ste si skôr upravili nejaký už hotový, môžete použiť moju obľúbenú konfiguráciu. Používam jej vždy, keď si chcem zobraziť históriu vývoja akéhokoľvek projektu, o ktorom toho príliš neviem:

gource -c 4 -s 3 --seconds-per-day 3 --key --hide bloom,filenames,usernames

Pokiaľ tiež máte nejakú svoju obľúbenú konfiguráciu, podeľte sa o ňu s nami v komentároch pod článkom.