iCe Online - Legion

Postupy • Test ikon

2017-12-07T09:37:34+02:00

Téma k testování ilkon

Statistiky: Napsal od Kattnienika — 7. prosinec 2017 (8:37:34)

Postupy • [git] Místní a vzdálený repozitář

2017-11-29T20:06:16+02:00

Předchozí návody (Quickstart a Zásady commitování) předpokládaly, že existuje vzdálený repozitář a stahujete ho k sobě, abyste mohli provádět úpravy, které zase nahrajete do vzdáleného repozitáře. Princip gitu ale nikoho nenutí mít žádný počet vzdálených repozitářů - technicky vzato je možné nemít žádný a udržovat repozitář jen lokálně, nebo je možno mít jich několik (například z několika změny bereme, a do jednoho, našeho, změny nahráváme, apod.). Tento topic se bude zabývat vytvářením lokálního repozitáře a pozdějším přidáním vzdáleného, pokud to bude nutné.

Poznámka: místo "místní" lze použít označení "lokální", vzdálený repozitář se pak obecně v gitu označuje jako "remote"

Zakládání
Otevřete git bash a příkazy "cd" se navigujte do míst, kde chcete mít nový repozitář, případně pokud jste ve Windows zvolili integraci do průzkumníka, lze na adresář kliknout pravým tlačítkem myši a vybrat "Git bash here". Narozdíl od klonování repozitáře musíte již být přímo v kořenové složce vašeho budoucího repozitáře, tedy pokud chcete vytvářet repozitář pro svůj nový addon, rovnou si vytvořte složku "my-fancy-addon" a navigujte se do ní.

Pak lze repozitář inicializovat jedním příkazem:

CODE:

git init

Toto vytvoří základ pro repozitář, ve kterém zatím není v podstatě nic. Dále bývá dobrou praktikou vytvořit prázdný tzv. root commit. To je takový commit, který je první v celé historii repozitáře, a měl by být prázdný (bez souborů a beze změn). Hned po inicializaci proto proveďte příkaz:

CODE:

git commit --allow-empty -m "Initial empty commit"

Ten takový root commit vytvoří.

Nyní máte připravený lokální repozitář a lze se řídit postupy z jiných témat pro přidávání souborů a jejich commitování.

Přidávání vzdálených repozitářů
Pokud potřebujete do již existujícího lokálního repozitáře přidat odkaz na vzdálený, abyste mohli nahrávat změny, je nutné si nejdříve najít URL repozitáře (jak je popsáno v Quickstart) a provést tento příkaz:

CODE:

git remote add origin

Na stejném příkladu jako v quickstart guide by to bylo tedy:

CODE:

git remote add origin https://github.com/iCeOnlineWoW/G-Core.git

Slovo "origin" je v tomto případě název vzdáleného repozitáře. Ten lze mít pochopitelně jiný, ale výchozím názvem pro hlavní takový repozitář je právě "origin".

V případě, že jste se jakýmkoliv způsobem spletli lze vzdálený repozitář odebrat příkazem:

CODE:

git remote rm origin

Popř. s jiným jménem vzdáleného repozitáře.

Pro možnost pohodlně pushovat/pullovat bez specifikace odkud, lze zadat příkaz:

CODE:

git branch --set-upstream-to=origin/master master

To nastaví ve vašem lokálním repozitáři "propojení" mezi vaší master větví a vzdálenou master větví, aby při zadávání "git pull" / "git push" nebylo potřeba specifikovat, že chceme stahovat z/nahrávat do určité větve určitého vzdáleného repozitáře

Statistiky: Napsal od Gregory — 29. listopad 2017 (19:06:16)

Postupy • [git] Zásady commitování

2017-11-22T13:44:26+02:00

Každý příspěvek do git repozitáře je "zabalen" do takzvaného commitu. Ten obsahuje nejen změny v souborech ve formě rozdílu, ale i další informace. Jednou z důležitých informací je takzvaná "commit note", tedy poznámka k commitu, aby bylo jasné, k čemu se commit vztahoval, co opravoval nebo upravoval. Dále je obsažen hash, který jednoznačně commit identifikuje v celém repozitáři. Jedná se o 20B číslo, obvykle zapsáno v hexadecimálním tvaru (tedy 40 znaků, 0-9,A-F). Dále má commit autora, kterého lze buď explicitně určit při commitování, nebo lze použít výchozí hodnoty z globálního nebo lokálního nastavení. Poté je commit označen časovou značkou jeho vytvoření.

Pro nastavování a další záležitosti bude tento návod využívat pouze variantu git bash.

Autor
Autor commitu je dán buď explicitně při commitování přepínačem "--author" (zde vynecháme) nebo ho lze určit lokálně pro celý repozitář, případně globálně pro celý váš PC. Budeme se zabývat jen druhým způsobem, kdy nastavíme implicitního autora globálně pro váš počítač. Potřeba nastavovat autora lokálně vyvstává v momentě, kdy například pracujete na více projektech pro jiné subjekty a potřebujete mít všude jiný identifikátor a e-mail, a tak podobně.

Autor má dvě "složky" - jméno a email. E-mail nastavíme na ten, který jste si např. registrovali na GitHubu. Jméno taktéž použijeme buď vlastní, nebo přezdívku z GitHubu:

CODE:

git config --global user.name "MojeJmeno"git config --global user.email "mujemail@seznam.cz"

Pokud budete někdy z nějakého důvodu potřebovat nastavit autora zvlášť pro nějaký repozitář, lze vynechat parametr "--global"

Pokud se rozhodnete uvádět autora přímo při commitování, což se může hodit, pokud nahráváte něčí patch, jehož nejste autorem, lze použít přepínač při commitování:

CODE:

git commit ... -s --author="PravyAutor "

Nutno dodat, že v tomto případě musí být dodržen formát, tedy v uvozovkách bude jméno autora, mezera a v ostrých závorkách uveden email. Všimněte si také parametru "-s" - ten dá v záznamu commitu vědět, že jste to byli vy, kdo commit převzal a vložil do repozitáře. Není povinný, ale pro naše účely ho vyžadovat budeme - přecijen se jedná o určitý prvek, který dovoluje udržovat pořádek.

Správa a přidávání souborů

Jak jsem psal již v guide jinde, soubory se dají přidat příkazem "git add" buď hromadně (hvězdička), nebo po jednom. Ani jeden způsob není úplně ideální - "git add *" vám může přidat do repozitáře i věci, které nechcete, aby tam byly (dočasné soubory, konfigurace, ..), a přidávání po jednom zase bude trvat hrozně dlouho.

Pro začátek mějme přehled, co do repozitáře NEpatří:

konfigurační soubory (config.php, ..) (neplatí pro jejich předlohy, kde nejsou vyplněné položky)
dočasné soubory a cache
dynamicky generovaný obsah uživateli (avatary, obrázky v tématech, uploadované soubory, ..)

Někde na hraně jsou pak soubory projektů různých vývojových prostředí. Pokud používáte IDE jako NetBeans, není nutné jeho soubory do repozitáře vkládat. U MS Visual Studio je to již často diskutabilní. Projekty pro .NET (C#, VB, ..) tam své soubory mít mají, ovšem pro C++ se budeme snažit všude použít CMake (u emulátoru používaný je), takže projektové soubory MSVS pro C++ připojovat nebudeme.

Jak tedy přidávat správně soubory? Vyčleňme si cesty, které obsahují výše zmíněné soubory a ty přidávat nebudeme. Abychom si byli jisti, že do repozitáře budeme přidávat jen to, co tam chceme, postupujme po jednotlivých podsložkách (a podpodsložkách, ...) a přidávejme hromadně jejich obsah. Pokud se v nějaké složce vyskytuje více souborů a jeden z nich je config, nezbývá, než přidat buď všechny po jednom, nebo přidat hromadně všechny a pak jeden konkrétní soubor opět "vyndat" (k tomu níže), nebo použít .gitignore (také níže). Také je možné přidávat po příponách. Například téměř vždy u C++ projektů chceme přidat všechny zdrojové soubory s příponou .cpp.

Můžeme proto přidávat soubory a složky tímto stylem:

CODE:

git add assets/*git add app/models/* app/controllers/*git add *.cppgit add app/bootstrap.php

Pokud se vám náhodou povede zahrnout do výběru i soubor, který tam nemá co dělat, lze ho "vyjmout" příkazem:

CODE:

git reset -- config.php

Nutno dodat, že tento příkaz nic nezmění fyzicky v tom souboru, ani ho nikam nepřesune/nevymaže. Jen ho vyjme ze současného stavu repozitáře.

Pro kontrolu je silně doporučeno zkontrolovat, zda jsme přidali všechny soubory co chceme, zda jsme nepřidali něco ze souborů, co v repozitáři nemají co dělat, a zda je vše v pořádku. Toho lze docílit příkazem:

CODE:

git status

Výpis obsahuje několik sekcí. Soubory konfigurací a další co nemají v repozitáři co dělat by měly být v sekci "Untracked files" (po nastavení gitignore níže nebudou ani tam). Ostatní soubory budou v sekci "New files", "Changes staged for commit" nebo "Changes not staged for commit". Příkaz "git add" neslouží pouze k přidávání nových souborů do repozitáře, ale k "přípravě" souborů k commitování obecně. Stejným způsobem lze "přidat" (v git terminologii "stage") soubory k commitování a pak není třeba provádět výčet souborů v commit příkazu, případně používat "-a" přepínač. Z tohoto důvodu existují dvě sekce - "staged for commit" a "not staged for commit". Pokud použijete bezparametrický commit, budou se commitovat pouze soubory ze sekce "staged for commit". Pokud použijete přepínač "-a", budou se commitovat všechny sekce kromě "Untracked files".

.gitignore a složky pro dynamický obsah

V git repozitářích existují speciální soubory, který mají určitý význam pro správu repozitáře. Pro teď je důležitý soubor s názvem ".gitignore". Na začátku má tečku, a to z důvodu, že soubory začínající tečkou jsou na unixových systémech považovány za "skryté" (analogie ke skrytým souborům z Windows a jeho souborových systémů). Ve Windows se bude tento soubor pravděpodobně chovat jako soubor beze jména s příponou "gitignore", ale instalační program gitu vám pravděpodobně tyto "přípony" asocioval s textovým editorem.

Soubor .gitignore se může nacházet kdekoliv v projektu i na několika místech. Obsahuje po řádcích oddělený seznam souborů a cest, které se mají úplně ignorovat při správě repozitáře (git add, git status, ...). Můžeme proto v kořenovém adresáři repozitáře například vytvořit jeden takový gitignore a naplnit ho ignorováním konfiguračních souborů, a například všech souborů s příponou .env:

CODE:

app/config.phpapp/config.db.php*.env

Nezapomeňme soubor .gitignore přidat do repozitáře, pokud není (git add), a provést commit, kromě speciálního významu jde o naprosto normální soubor.

Pro složky s dynamicky generovaným obsahem (cache, uploads, ..) lze vkládat přímo do nich soubor .gitignore s následujícím obsahem:

CODE:

*!.gitignore

Tento soubor říká, že se má ignorovat vše v této složce (hvězdička na prvním řádku), ale NEMÁ (vykřičník) se ignorovat soubor .gitignore. Toto způsobí, že složka zůstane v repozitáři prázdná, ačkoliv se do ní u vás generuje dynamický obsah. Není zde tedy riziko, že do vzdáleného repozitáře pošlete data, která tam být nemají.

Commit note

Commit note je další velmi důležitou částí commitu a všude mohou být jiné požadavky, co tam vlastně psát. Vždy je ale nutné napsat, co jste vlastně v tomto commitu upravili. Dále v rámci iCe Online budeme používat angličtinu.

Zásady lze shrnout bodově:

jednoznačná stručná poznámka o tom, co se v commitu změnilo
jednojazyčně (u nás angličtina)
obsahuje pouze základní ASCII znaky (tedy vynechme háčky a čárky, UTF-8 speciality, emoji, ..)
neobsahuje smajlíky ani jiné prvky typicky chatové konverzace
vše by se mělo vejít do 80 znaků (pokud ne, svět se nezboří, ale snažme se dodržet)
není zase zbytečně stručná (např. oblíbená commit note "fix", "repair", "files" nebo "small change")
pokud to repozitář vyžaduje, uvádějme i modul, ve kterém ke změně došlo (bude popsáno v samostatném příspěvku)

Statistiky: Napsal od Gregory — 22. listopad 2017 (12:44:26)

Postupy • [git] Quickstart

2017-11-21T08:49:57+02:00

Pro správu repozitářů budeme používat systém zvaný "git". Jedná se o distribuovaný systém správy verzí, jehož primární využití je pro správu a verzování zdrojových kódů. V kontextu tohoto postu budu předpokládat, že je použit právě pro správu zdrojového kódu.

Tento quickstart není nikterak podrobný, nebudou popisovány žádné větší složitosti, tedy například konkrétní uložení a fungování systému git, zabezpečení, nic. Části toho, co zde vynechám, budou popsány v jiném topicu.

Nejprve krátký slovník pojmů:

repozitář - jedno oddělené úložiště určené např. právě jednomu projektu
branch - "větev" vývoje v rámci jednoho repozitáře (oddělení vývoje projektu do vlastního odděleného "prostoru")
commit - "příspěvek" do repozitáře v podobě změn oproti stavu před ním
commit note - poznámka k příspěvku do repozitáře, povinná
pull - stažení změn ze vzdáleného repozitáře do místního, např. na vašem PC
push - nahrání změn z místního repozitáře do vzdáleného
merge - spojení větví do sebe
patch / diff - soubor změn, který lze např. odeslat mailem nebo zde na fórum (fakticky je rozdíl mezi pojmy patch a diff, nebudeme se jím zabývat)
master - zde nějaká hlavní branch, která je přítomna vždy a tvoří stabilní vývojovou větev

Stažení, instalace

Linux
Pro uživatele operačních systémů založených na GNU/Linux (dále jen "na Linuxu") je postup snadný - stačí otevřít terminál a prostřednictvím balíčkového systému ve vaší distribuci přítomným stáhnout nástroje gitu:

CODE:

# Debian-based systemy (Ubuntu, Mint, ..)apt install git-all

CODE:

# Fedora/CentOS/...dnf install git-all

Windows
Na OS Windows je nutné sahnout po instalátoru, který vám nastaví vše potřebné. Nástroj se jmenuje msysgit a je dostupný ke stažení na této adrese: https://git-for-windows.github.io/

Stahněte instalátor, nainstalujte.

Stažení repozitáře, orientace

Příkladem bude repozitář emulátoru. Pro jeho stažení se navigujte do terminálu - v případě Linuxu stačí otevřít terminál, v případě Windows by mělo stačit pravým tlačítkem myši stisknout kamkoliv do volného prostoru nějaké složky (popř. na plochu) a vybrat "Git Bash here". Pak si najdeme repozitář na webových stránkách githubu, kde se naše repozitáře nacházejí - https://github.com/iCeOnlineWoW - vybereme repozitář "G-Core" a vpravo najdeme zelené tlačítko "Clone or download" a uvedenou adresu si zkopírujeme do schránky (ctrl-C) - naznačeno zde: https://i.imgur.com/XMiGirS.png

Poté se přesuneme do terminálu a zadáním příkazu s touto adresou stahneme repozitář:

CODE:

git clone https://github.com/iCeOnlineWoW/G-Core.git

V terminálu budou chvíli běhat procenta, repozitář je poměrně velký, jeho stahování bude nějakou dobu trvat. Operace bude dokončena, když se vám znovu objeví "prompt" terminálu s vyčkáváním na další příkaz.

Nyní máte stažený repozitář a můžete si prohlédnout složku, která se vám tímto vytvořila. Pokud máte zobrazené skryté soubory a složky, můžete vidět složku ".git" - ta není součástí přímo repozitáře (kódu, který spravujete, atd.), ale jedná se o složku sdružující informace o repozitáři (řekněme takové "meta informace") - ukládá se tam vše možné od nastavení specifického pro repozitář, až po historii commitů ve všech branchích tohoto repozitáře. Ostatní soubory a složky jsou již standardním obsahem tzv. "working tree" - pracovního stromu repozitáře.

V momentě stažení repozitáře máte uloženou nějakou lokální kopii toho, co bylo platné v momentě stahování. V této lokální kopii můžete provádět změny, jak se vám zlíbí, ale žádná z nich se neprojeví v původním vzdáleném repozitáři, dokud neprovedete "push" (s příslušnými právy; k tomu dále)

Vývoj, commity

Každý vývoj by měl probíhat alespoň trochu systematicky, tedy v případě emulátoru si vytyčíte cíl, co chcete opravit - řekněme nějaký spell, nebo naskriptovat AI potvory. To znamená, že v jeden moment byste měli pracovat na jedné této úpravě. Pochopitelně jsou cesty, jak docílit možnosti pracovat na vícero opravách zároveň se zachováním čistoty repozitáře, ale to pro tento návod vynechme, budeme se soustředit na jednoduché postupy.

Důvodem, proč je nutné dodržet systematický postup při vývoji je ten, že vše co změníte budete chtít "zabalit" do nějakého commitu, který bude mít nějakou svou poznámku, která typicky obsahuje (a v našich repozitářích vždy bude obsahovat) titulek změny. V případě opravy spellu to bude název spellu, co jste opravovali, v případě AI bosse v dungeonu to bude například lokace a jméno.

Pro teď tedy předpokládejme, že jste v kódu změnili, co jste potřebovali a dodrželi jste vše vypsané. Budeme tedy chtít obalit změny do commitu. To uděláme příkazem, který obecně vypadá takto:

CODE:

git commit  -m ""

Prakticky lze místo výčtu souborů buď provést přidání pomocí příkazu "git add" (později) nebo použít přepínač "-a". Příkladem tedy může být oprava vizuálního efektu spellu Summon Imp u warlocka:

CODE:

git commit -a -m "Spells/Warlock: fixed Summon Imp visual effect"

Tímto jste vytvořili commit, který je součástí vašeho lokálního repozitáře (lokální kopie).

Pokud chcete přidat nový soubor do repozitáře a zahrnout ho v commitu, je nutné ho před commitem nejdříve přidat příkazem, který obecně vypadá takto:

CODE:

git add

Soubory lze zadávat pouhým výčtem (relativní/absolutní cesta) nebo i s použitím hvězdičky pro hromadný výběr. Můžeme chtít vybrat například všechny soubory s příponou .cpp a přidat je do projektu:

CODE:

git add *.cpp

Případně konkrétní soubor:

CODE:

git add main.cpp

Tento příkaz je nutné udělat pouze jednou.

Nahrávání změn na vzdálený repozitář

Pokud jste vytvořili commit a chcete ho přenést do vzdáleného repozitáře (a máte na to příslušná práva), lze to provést příkazem "push". Ještě předtím ale budeme muset ověřit, že máme lokální kopii aktuální (tedy že žádný náš kolega nestihnul nahrát svoje změny dříve), a pokud ne, aktualizovat ji. To lze provést příkazem:

CODE:

git pull

Tento příkaz předpokládá, že všechny změny jsou commitnuté, popř. že žádné nejsou. Pokud tomu tak není, bude vám oznámeno, že "Working directory is not clean" a je nutné buď změny commitnout (pokud jste na to třeba jen zapomněli), nebo vymazat příkazem:

CODE:

git reset --hard

Pokud se vše povede a konzole nebude hlásit žádný například konflikt nebo chybu, je náš repozitář aktuální - buď se nic nezměnilo ani ve vzdáleném repozitáři, nebo byly změny úspěšně nahrány. Pokud je nahlášena chyba, typicky jde o nějakou chybu ve spojování vašich změn a změn ze vzdáleného repozitáře. Git vám v tomto případě nahlásí, v jakých souborech došlo k chybám spojování a vy musíte chyby ručně opravit. Po jejich opravě stačí pouze příkazem "git add " potvrdit, že jste daný soubor opravili, a po opravě všech souborů provést jednoduchý "git commit" bez parametrů.

Takovou aktualizaci je doporučené provádět před tím, než začnete provádět změny. Vyhnete se tím zbytečným konfliktům, kterým šlo předejít včasnou aktualizací.

Pokud je vše v pořádku, lze provést příkaz

CODE:

git push

který nahraje změny do vzdáleného repozitáře. Pokud by se vám náhodou povedlo zapomenout na aktualizaci, nebo vás někdo předběhnul v posílání změn do repozitáře, objeví se hláška obsahující "rejected" - to znamená, že je nutné aktualizovat repozitář, případně vyřešit jiný konflikt. Pokud se vám zdá, že je repozitář aktuální a stejně nejde push, napište mi, jelikož se vám mohlo povést nějakým způsobem pochroumat integritu commitů a z toho se nejde vymotat snadnou cestou (která nezahrnuje smazání vašich změn).

Poznámka:
Od určité verze gitu a tuším asi jen na Windows je potřeba specifikovat, do jaké branche budete přispívat. To zajistíte příkazem:

CODE:

git push --set-upstream origin master

Tím gitu řeknete, že chcete svázat váš lokální repozitář pro push s určitým vzdáleným. V gitu totiž není pravidlem, že jsou oba směry "symetrické" - můžete mít více vzdálených zdrojů, z většiny jen číst, do jednoho jen zapisovat, a tak podobně.

Alternativy

Pochopitelně existují i alternativní přístupy, například nějaké grafické rozhraní. Používáním těchto nástrojů se ale vystavujete riziku, že bude provádět dodatečné operace "za vašimi zády", a že vám například nebudu schopen v případě potíží pomoci jinak, než zase použitím konzolové verze. Sám GitHub nabízí svého desktopového klienta, kterého pochopitelně je možné použít. Nezkoušel jsem ho, nicméně přístup přes konzoli je univerzální a dostupný všude a vždy.

------- Zatím to berte s velkou rezervou, zítra si to po sobě přečtu a hrozí, že toho půlku stejně přepíšu

Statistiky: Napsal od Gregory — 20. listopad 2017 (23:52:50)