Gource - Vizualizace vývoje projektu

Používáte při vývoji svého projektu software pro správu verzí (version control) a chtěli byste se podívat, jak se váš projekt s postupem času rozrůstal a vyvíjel? Poté je pro vás Gource to pravé! Tento hezký kus softwaru vytvořený v jazyce C++ generuje animaci vývoje projektu podle času vydávání jednotlivých snapshotů (commitů). Jak taková animace vypadá se můžete podívat například na tomto videu:

Jak jste si nejspíše domysleli, každý puntík znázorňuje jeden soubor a jeho barva se liší podle přípony souboru. Čáry mezi skupinami souborů poté představují adresářovou strukturu projektu (rozdělení souborů do složek) a drobné postavičky autory commitů. Kdykoliv nějaká postavička "posvítí" na nějaký soubor, znamená to, že soubor upravuje, vytváří, nebo maže.

Animace se dá do poměrně velké míry přizpůsobit, ať už změnou barvy pozadí, skrytím jednotlivých prvků animace nebo změnou časového intervalu věnovanému jednomu dni historie vývoje. Jak tyto věci ovlivnit si povíme dále v článku.

Instalace

Gource si stáhneme z oficiální stránky projektu https://gource.io/. Stáhneme si spustitelný instalátor, spustíme jej a proklikáme jednotlivé kroky. Druhou možností je stáhnout si instalátor z GitHub repozitáře, na kterém je celý projekt hostován. Po instalaci nám na ploše nepřibude zástupce pro spuštění, jak jste možná zvyklí u jiných aplikací. Gource se totiž ovládá z příkazového řádku.

První animace

Nyní již ke spuštění naší první animace. Otevřeme okno "Spustit" stisknutím kombinace kláves Win + R a zadáme text cmd. Poté již jen stiskneme Enter a příkazový řádek se otevře. Gource nevyžaduje, aby byl příkazový řádek spuštěn s administrátorskými právy.

Teď se potřebujeme dostat do složky, ve které máme svůj verzovaný projekt. Pokud zrovna žádný nemáte, naklonujte si libovolný open-source projekt třeba z GitHubu. Adresář, ve kterém příkazový řádek operuje, můžeme změnit příkazem cd. Pokud je například váš projekt uložen ve složce C:\Users\Jarda\source\SuperKalkulacka, proveďte příkaz:

cd C:\Users\Jarda\source\SuperKalkulacka

Malá vychytávka: V průzkumníkovi souborů můžete kliknout na adresový řádek a nahradit cestu textem cmd. Po potvrzení Enter se vám rovnou otevře příkazový řádek v daném adresáři.

Konečně můžeme animaci spustit. Není to nic složitého, zkrátka napíšeme do konzole gource a stiskneme Enter. Gource si podle informací uložených ve skryté složce .git/ načte log změn a začne generovat animaci se základními nastaveními:

Animaci můžeme kdykoliv pozastavit nebo znovu spustit mezerníkem. Mačkáním kurzorových šipek nebo potahováním myši při držení levého tlačítka posouváme kameru, posouváním myši při držení pravého tlačítka kameru natáčíme.

Nastavení animace

Styl animace můžeme upravit použitím argumentů v příkazu gource. Jejich kompletní seznam si můžeme v angličtině přečíst na wiki projektu na GitHub, nebo se nám také zobrazí po zadání příkazu gource --help do příkazové řádky. Ty nejdůležitější si zde však uveďme, abychom byli schopní po přečtení tohoto článku nastavovat základní animace a nemuseli studovat další dokumentace jinde.

Rychlost animace

Asi nejviditelnější úpravou je změna rychlosti animace. Gource nám umožňuje nastavit, kolik sekund bude věnováno animaci jednoho dne historie. Základní nastavení je 10 sekund, což může být pro větší projekt příliš pomalé. Pokud chceme, aby animace jednoho dne trvala pouze dvě sekundy, docílíme toho následujícím příkazem:

gource -s 2

Stejného výsledku dosáhneme i v případě, pokud místo -s použijeme --seconds-per-day. Je jenom na nás, zda budeme používat rychlejší, nebo deskriptivnější zápis.

Nespoléhejte na to, že pokud byl projekt vyvíjen od 1. dubna do 30. dubna a parametr -s je nastaven na 5, bude celá animace trvat 300 sekund. Gource automaticky přeskakuje animaci časových period, během kterých se do projektu nepřispívalo. Toto lze omezit dalšími nastaveními, avšak základně se Gource posune v čase k dalšímu commitu, pokud se po dobu 3 sekund nic neděje.

Druhou možností, jak ovlivnit dobu trvání animace, je nastavení celkové doby relativně k základnímu nastavení. Toho docílíme parametrem -c (nebo --time-scale). Základně je toto nastaveno na 1.0, což znamená, že parametr nijak dobu trvání animace neovlivní. Pokud místo 1.0 zadáme například 2.5, bude celá animace 2,5 × rychlejší. Při zadání 0.1 zase 10 × pomalejší. Toto nastavení automaticky zvýší nebo sníží počet sekund, které jsou věnovány jednomu dni historie. Spuštěním animace následujícím příkazem se tak dostaneme opět na výchozí rychlost:

gource -s 20 -c 2.0

Úprava skákání v čase

Pokud má projekt ve vývoji díry, během kterých se do něj nepřispívalo, Gource je automaticky bude přeskakovat, pokud by se nemělo v animaci zobrazit nic nového po dobu delší než 3 sekundy. Tento časový údaj můžeme samozřejmě také upravit, a to parametrem -a (--auto-skip-seconds). Spuštěním animace se budou následovně přeskakovat etapy vývoje, které by byly v animaci neměnné po dobu delší než 1 sekunda:

gource -a 1

Někdy může být nežádoucí, aby čas v animaci neplynul konzistentně. V takovém případě můžeme tuto funkci vypnout parametrem --disable-auto-skip:

gource --disable-auto-skip

Oříznutí animace

Může se stát, že budeme chtít spustit animaci vývoje pouze pro novější verzi, nebo naopak pouze z doby počátku projektu. Parametry --start-date a --stop-date můžeme tyto časové milníky vymezit. Pokud nezadáme --start-date, bude se animace přehrávat od počátku vývoje a v případě nezadání --stop-date poběží animace až do konce. Tento příkaz spustí animaci vývoje projektu během školního roku 2019/2020:

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

Nastavení velikosti okna

Okno, ve kterém se animace spouští, má základně nastavenou nějakou velikost. Pokud vám tato velikost nevyhovuje, můžeme jí změnit. To provedeme zadáním požadované výšky a šířky okna za dvě pomlčky a oddělíme je malým písmenem X. Šířka se zadává jako první:

gource --800x600

Animaci můžeme spustit i v režimu na celou obrazovku pomocí parametru -f (--fullscreen). Režim celé obrazovky můžeme kdykoliv ukončit klávesou Esc.

Nastavení kamery

Kamera (pohled na animaci) se základně automaticky natáčí tak, aby byl zobrazen celý strom souborů a zároveň nebylo přibližování a oddalování příliš prudké. Parametrem --camera-mode můžeme toto změnit tak, aby kamera sledovala vždy aktivní přispěvatele do projektu. Tento parametr může být nastaven na:

• overview (základní nastavení), nebo na
• track (sledování přispěvatelů).

Tyto módy zobrazení můžeme prohodit i kdykoliv během přehrávání animace stisknutím klávesy V:

gource --camera-mode track

Skrytí prvků animace

Pokud bude animace obsahovat například mnoho popisků souborů, může se stát nepřehlednou. Proto umožňuje Gource skrýt jednotlivé prvky animace, jako jsou například přispěvatelé, popisky složek, nebo samotné soubory. To můžeme provést parametrem --hide, za který napíšeme seznam prvků, které chceme skrýt, oddělené čárkou. Tyto prvky můžeme specifikovat slovy:

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

Co každé z nich skryje je asi jasné, snad jen bloom si zaslouží objasnit. "Bloom", neboli česky "květ", je efekt záře kolem skupin souborů:

gource --hide dirnames,filenames,usernames

Elasticita a záře

Toto jsou již spíše estetická nastavení. Pomocí parametru -e (--elasticity) můžete nastavit, jak moc se budou "vlnit" jednotlivé větve struktury projektu, když jsou nuceny se posunout. Pomocí --bloom-multiplier můžeme změnit poloměr efektu záře kolem složek (podobně jako u parametru -c zlomkově) a pomocí --bloom-intensity zase sílu záře (základně je nastaveno na 0.75).

Zobrazení počtu souborů

Parametr --key nám zobrazí v levém horním rohu počet a barvy souborů, podle jejich přípony. Toto můžeme zapnout i vypnout kdykoliv během animace stisknutím klávesy K.

Změna barvy souborů

Možná vás napadlo, že byste chtěli puntíkům reprezentující uživatele nebo soubory s určitou příponou přiřadit specifickou barvu. Například .html soubory by mohly být oranžové, .css světle modré, .js žluté a .php fialové. Bohužel vás musím zklamat, i přes četné návrhy na vylepšení toto Gource stále neumožňuje. Můžete však mačkáním klávesy S barvy změnit náhodně. Barvy se generují podle "semínka", což je číslo, které generátor barev zpracuje a podle něj rozdělí barvy. Toto semínko (anglicky "seed") můžeme nastavit manuálně pomocí parametru --hash-seed. Pokud použijeme vždy stejné semínko, budou i barvy souborů a uživatelů vždy stejné:

gource --hash-seed 73

Pokud objevíte nějaké, u kterého barvy souborů odpovídají očekávání, můžete se o něj v komentářích pod článkem podělit

Doporučená animace

Pokud se vám nechce sestavovat příkaz ke spuštění animace od začátku a raději byste si spíše upravili nějaký již hotový, můžete použít mou oblíbenou konfiguraci. Používám jí vždy, když si chci zobrazit historii vývoje jakéhokoliv projektu, o němž toho příliš nevím:

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

Pokud také máte nějakou svou oblíbenou konfiguraci, podělte se o ni s námi v komentářích pod článkem.