Git-versiohallinta Ohjelmointi 1 -kurssilla

Tässä dokumentissa kerrotaan miten harjoitustyön koodia ja muita tiedostoja, kuten suunnitelmakuvia, käsitellään versiohallinnan avulla.

Asenna kehitystyökalut ja Git-versiohallinta ennen tämän ohjeen käyttämistä.

Jotta saat suunnitelman onnistuneesti Gitlabiin, sinun on toimittava kappaleiden 3-8 ohjeiden mukaan.

Harjoitustyön suunnitelman viemisestä versiohallintaan on myös videotutoriaali: https://youtu.be/MQJ69rmd1sw.

1. Mikä Git on

Git on hajautettu versiohallintaohjelmisto. Versionhallintaohjelmiston ideana on tarjota säilytyspaikka yhteisesti käytettävälle tiedolle ja pitää kirjaa tietoon tehdyistä muutoksista. Ohjelmistotyössä versiohallinnan käyttäminen yhteistyöskentelyyn ja muutosten jäljittämiseen on normi.

Versiohallinta mahdollistaa myös saman koodin parissa työskentelyn eri tietokoneilta, mikä sopii hyvin tälle kurssille, koska usein tehdään töitä eri tietokoneilta (mikroluokka, kotikone, jne.).

Toisaalta versiohallinta toimii myös varmuuskopiona työllesi. Näin koodisi ei häviä, vaikka tietokoneesi hajoaisi.

Tällä kurssilla emme käytä Dropboxia, muistitikkuja, sähköpostia tai vastaavia palveluita kooditiedostojen jakamiseen, koska ne eivät sovellu todelliseen yhteistyöskentelyyn. Vaikka työskentelisitkin yksin, käytä versiohallintaa ohjaajien työn helpottamiseksi sekä harjoitustyön esittelyn mahdollistamiseksi.

GitLab (ja myös GitHub) ovat internetissä toimivia palveluita, joissa Git-muotoisia varastoja (engl. repository) voidaan säilyttää.

Tällä sivulla on kukin Git-komennon aluksi linkki myös ohjeeseen ja referenssiin. Niitä ei kannata ehkä klikkailla ensimmäisellä lukukerralla, vaan siten kun haluaa tietää asiasta lisää.

# muistilista

2. Muistilista

Alla on muistilista tyypillisimmistä tilanteista, ja kuinka näissä gitin kanssa toimitaan erityisesti tällä kurssilla. Lue kuitenkin myös tarkemmat kuvaukset tämän dokumentin seuraavista luvuista.

  • Aloitan harjoitustyön ➔ Teen fork-toiminnolla gitlab.jyu.fi-palvelussa uuden etävaraston.

  • Menen koneelle, jossa sisältöä ei vielä ole ➔ Kloonaan etävaraston omaan koneeseen.

    git clone https://gitlab.jyu.fi/Anonymous/ohj1ht.git .

  • Menen koneelle jossa sisältö jo on ➔ Päivitän etävaraston version koneelle.

    git pull

  • Muutan tai lisään tiedostoja (esimerkiksi suunnitelmakuva suunnitelma-kansioon) ➔ Lisään muuttuneet ja uudet tiedostot stage-tilaan,

    git add --all

    ➔ ja siirrän stage-tilan tiedon lokaaliin varastoon,

    git commit -m "Muutoksia kuvaava viesti."

    ➔ ja "pusken" tekemäni commitin etävarastoon.

    git push

Nämä samat ohjeet pätevät myös ryhmätyössä, mutta silloin kannattaa kiinnittää erityistä huomiota siihen, että tekee pull, commit- ja push-toimintoja riittävän usein konfliktien välttämiseksi.

git status-komentoa voi viljellä missä tahansa välissä. Se kertoo oman tietovaraston tilasta, muun muassa mitä tiedostoja on muutettu/poistettu/lisätty.

Alla on kuvio, jossa on havainnollistettu muutamia yleisimpiä git-komentoja.

Muutamia yleisimpiä git-versiohallinnan komentoja.
Muutamia yleisimpiä git-versiohallinnan komentoja.

Näitä komentoja voit kokeilla Ohjelmointi 2 -sivulla, jossa on luotu Timiin Git-"leikkikenttä" jossa komentojen kokeileminen on turvallista.

# fork

3. Oman etävaraston luominen gitlab-palveluun

Tässä vaiheessa luodaan henkilökohtainen etävarasto (engl. remote repository) gitlab.jyu.fi-palveluun. Tämä on jatkossa sinun työsi (tai ryhmäsi työn) origin. Kunkin opiskelijan etävarasto perustuu valmiiseen pohjaan, josta tehdään kopiohaara, eli GitLab-terminologiassa fork. Forkkauksen ansiosta saadaan uuteen projektiin kurssin alkuasetukset.

Tämä vaihe tehdään kurssilla yhden kerran.

    1. Jos sinulla on JY-tunnukset: Kirjaudu gitlab.jyu-palveluun (https://gitlab.jyu.fi/) JY-tunnuksilla.
    2. Jos sinulla ei ole JY-tunnuksia: Tee tunnukset GitHub-palveluun (https://github.com), ja kirjaudu palveluun.
    1. JY: Avaa Ohj1-kurssin pohjaprojekti selaimessa:
      https://gitlab.jyu.fi/tie/ohj1/2022s/ohj1ht
    2. GitHub: Avaa Ohj1-kurssin pohjaprojekti selaimessa:
      https://github.com/ITKP102-Ohjelmointi-1/ohj1ht.git
    1. JY: Valitse oikeasta ylänurkasta fork
    2. GitHub: Vastaavasti...

  1. Valitse omaa tunnustasi vastaava namespace (ryhmä).
  2. Valitse näkyvyydeksi public.
  3. Päivitä oman maun mukaan Settings --> General-kohdasta esimerkiksi projektisi nimi ja kuvaus. Näiden muuttaminen onnistuu toki myöhemminkin.

Projektisi etävaraston URL-osoite on nyt:

https://gitlab.jyu.fi/Anonymous/ohj1ht.git

Tallenna URL-osoite Omat tiedot -sivulle.

Näet etävarastosi URL-osoitteen gitlab.jyu-palvelussa kohdasta Clone -> Clone with HTTPS. Käytä tätä osoitetta tulevissa ohjeissa.

Jatka tästä tekemällä etävarastosta paikallinen klooni koneeseesi: clone

Milloin tämä pitäisi tehdä? Vasta silloin, kun aletaan tekemään harjoitustyötäkö?

Joo vasta silloin. -MR

VL: Harjoitustyön suunitelmaa varten tarvitaan tämä kuvan laittamista varten

— 23 Sep 20 (edited 23 Sep 20)

Lisätietoa kiinnostuneille: Mikä fork on?

Lisätietoa kiinnostuneille: fork-a-repo (GitHub)

4. Oikeuksien antaminen muille ryhmäläisille

Yksin tekevät voivat ohittaa tämän kohdan.

Forkin tekijä antaa oikeudet muille ryhmäläisille. Tämä tapahtuu projektin vasemman reunan kohdasta Members ja kohtaan GitLab member or Email address syötetään ryhmän jäseniä yksi kerrallaan.

Huom! Jäsenten tulee olla tätä ennen olla kirjautunut gitlabiin vähintään kerran.

Kaikki ryhmäläiset käyttävät samaa etävaraston osoitetta. Tämä on otettava huomioon alempana olevissa ohjeissa joissa tällöin on "väärän" henkilön tunnus.

5. Omien tietojen (nimi, sähköposti) asettaminen

Tämä vaihe tehdään yhden kerran jokaisella tietokoneella jolla harjoitustyötä työstetään.

Versiohallinta säilyttää tiedot muutoksen tekijän nimestä ja sähköpostiosoitteesta.

Aseta omat tietosi git-asiakasohjelmaan seuraavasti.

  • Mene komentoriville ja aseta tietosi antamalla alla olevat komennot:

    git config --global user.name "Anonymous user"
git config --global user.email "None"

  • Jos ei tulostu virheviestiä, niin komennot ovat onnistuneet.

  • Lisätietoa kiinnostuneille: git config

komentorivillähän ensin näkyy tämä C:> Users kauttaviiva nimeni eli olen c aseman käyttäjät kohdassa niin lisäänkö nuo komennot vain tuon rimpsun loppuun…? vai mitä täytyy näkyä komentorivillä ensin missä kansiossa pitäis olla?

git config -komentojen osalta ei ole väliä missä kansiossa olet. -AJL

— 03 Feb 21 (edited 03 Feb 21)
# clone

6. Etävaraston hakeminen omalle tietokoneelle (clone)

Tämä vaihe tehdään yhden kerran jokaisella tietokoneella jolla harjoitustyötä työstetään.

Seuraavaksi haetaan etävarasto omalle paikalliselle tietokoneelle. Tästä käytetään termiä kloonaaminen (engl. clone). Kloonattuun paikalliseen tietovarastoon tehdyt muutokset voi aikanaan lähettää takaisin etävarastoon; tästä kerrotaan lisää kohdassa 8.

Kloonaus tehdään tyhjään hakemistoon.

Entä jos hakemisto ei ole tyhjä?

Valitse alta tapa jota haluat käyttää. Suositeltava tapa on bash-pohjaiset ohjeet (GitBash, Mac, Linux)

TODO: tulevina vuosina voisimme keskittyä vain ja ainoastaan komentoriviin, jotta ohjeita saisi virtaviivaistettua. Muut työkalut sitten omaehtoisesti jos osaaminen riittää. -JuhoK

— 15 Feb 21

6.1 Komentorivi tai Git Bash (Windows)

6.2 Komentorivi (macOS, Linux)

6.3 Visual Studio 2019 (Windows)

6.4 TortoiseGit (Windows)

6.5 SmartGit (Windows, macOS, Linux)

# addcommit

7. Tiedostojen vieminen paikalliseen tietovarastoon (add, commit)

Kun tiedostoja lisätään, muokataan tai poistetaan, lisätään kaikki nämä muutokset lokaaliin tietovarastoon.

  • Git-ohje: add, reference: add

Tämä vaihe tehdään joka kerta kun olet tehnyt muutoksia koodiin tai muihin tiedostoihin.

7.1 Muista: Tallennathan suunnitelman oikeaan paikkaan

Tallenna harjoitustyösi suunnitelman sekä luonnoskuvan suunnitelma-kansioon. Sekä suunnitelmatekstiä varten että kuvaa varten on olemassa esimerkit suunnitelma-kansiossa.

Huomioitavaa:

  1. Kuvan pikselikoon tulee olla enintään 1920 x 1080 pikseliä.
  2. Kuvan tiedostokoon tulee olla enintään 500 kilotavua (500 kB).

voiko tän tehdö ihan resurssien hallinnan kautta eli siirtää sen kuvan vain kansioon?

Kyllä kuvan voi siirtää myös resurssienhallinnan kautta oikeaan kansioon. -AJL

— 03 Feb 21 (edited 03 Feb 21)

7.2 Komentorivi tai Git Bash (suositus, Windows, macOS, Linux)

Siirry cd-komentoja käyttämällä harkkatyökansioosi ja anna seuraavat kaksi komentoa:

git add --all 
git commit -m "kuvaava viesti miksi muutokset on tehty"

Ensimmäinen komento lisää kaikki muokatut tiedostot ns. index/stage-alueelle, ja seuraava komento tekee varsinaisen tietovarastoon tallentamisen.

On tärkeää, että aina add-komennon jälkeen tarkistat git status-komennolla mitä tiedostoja tietovarastoon on menossa. Älä lähetä tietovarastoihin suuria tiedostoja.

Mikäli et halua lähettää tietovarastoon kaikkia muutoksia, vaan esimerkiksi vain yhden tiedoston, laita --all-option tilalle haluamasi tiedoston nimi:

git add TIEDOSTONNIMI   (hakemistoineen, /-viiva hakemistomerkkinä)

Jotkut pitävät parempana luetella kukin lisättävä tiedosto erikseen ensinmainitulla komennolla. Kummassakin tavassa (all-vipu, tai kukin tiedosto erikseen) on puolensa.

Huomaa, että .gitignore-tiedosto sisältää tiedot sellaisista tiedostoista, joita ei lähtökohtaisesti viedä versiohallintaan. Jos kuitenkin ehdottomasti haluat lisätä tällaisen, esimerkiksi .jar-päätteisen tiedoston, niin silloin on käytettävä -f -optiota, jolla pakotetaan lisäys. Esimerkiksi:

git add -f kerho.jar

Toinen vaihtoehto on erikseen sallia vastava jar lisäämällä .gitignore-tiedostoon rivin .jar perään rivi:

!kerho.jar

Joissakin lähteissä index/stage-tilaan lisäämisestä käytetään verbiä stage tai staging.

# push

8. Tehtyjen muutosten lähettäminen etävarastoon (push)

Tässä vaiheessa paikalliseen tietovarastoon lähetetyt muutokset lähetetään etävarastoon.

Tämä vaihe tehdään joka kerta kun olet tehnyt muutoksia koodiin tai muihin tiedostoihin. Älä unohda tehdä tätä työskentelyn päätteeksi. Muutoin tiedot jäävät vain paikalliseen tietovarastoon.

8.1 Komentorivi tai Git Bash (Windows, macOS, Linux)

Siirry harjoitustyökansioosi ja anna komento

git push

Ensimmäisellä kerralla sinulta kysytään käyttäjätunnusta ja salasanaa. Anna käyttäjätunnus lyhyessä muodossa Anonymous ilman @-merkkiä ja loppuosaa. Salasana on sama jota käytät JYUNET-verkossa. Mikäli annat salasanan väärin, joudut muokkaamaan kirjautumistietojasi, ks. kohta 12.1.

Mac-käyttäjät huomatkaa, että salasana on KIRJOITETTAVA vaikka sen kohdalla näkyisi avaimen kuva. Kun salasanaa kirjoitetaan, ei näyttöön tule mitään. Lopuksi on painettava enter. Jos tässä tulee virhe, niin gitlab-salasana on poistettava avainnipusta.

“Mikäli annat salasanan väärin, joudut muokkaamaan kirjautumistietojasi, ks. kohta x.x.” #-Mitenkäs tämä onnistuu kun terminal antaa “remote: HTTP Basic: Access denied”

— 04 Feb 20

Kokeilepa tuolla Push ei onnistu (Access denied) -kohdassa olevaa ongelmanratkaisua. -AJL

— 09 Feb 20 (edited 09 Feb 21)
# pull

9. Muutosten hakeminen etävarastosta paikalliseen varastoon (pull)

Kun joku toinen (tai sinä jollain toisella tietokoneella) on muuttanut tiedostoja ja pushannut muutokset etävarastoon, niin muutokset tulee hakea omalle koneelle. Yhteistyöskentelyssä on syytä aina työskentelyä aloittaessa antaa pull-komento.

9.1 Komentorivi tai Git Bash (Windows, macOS, Linux)

Siirry hakemistoon, johon olet kloonannut projektin (ks. clone) ja anna komento:

git pull

Tässä kohti voi tulla kysymys siitä että miten pullin haluaa jatkossa toimiva. Ohj1 kurssin osalta toimiva vaihtoehto voisi olla

git config pull.rebase false

Lue tästä lisää esimerkiksi StackOverflowsta.

# huomioitavaa

10. Huomioitavaa

# tiedostonKoko

10.1 Tiedostojen koko

Versionhallintajärjestelmä ei sovi suurten tiedostojen tallennukseen. Älä lähetä versiohallintaan esimerkiksi suuria kuva-, musiikki- tai videotiedostoja. Myöskään käännetyt ohjelmat eivät kuulu versiohallintaan. Täydennä tarvittaessa .gitignore-tiedostoa.

10.2 Älä laita salaisuuksia versiohallintaan

Älä lisää projektisi commiteihin mitään salaista, kuten salasanoja tai henkilötietoja. Vaikka poistaisit tiedon seuraavassa commitissa, se jää Gitin projekti-historiaan, ja on löydettävissä julkaisun jälkeen.

11. Tapoja käyttää Git:iä

Aluksi ehdottomasti suositeltavin tapa on Git ja komentorivi.

Kaikkia alla mainittuja tapoja (työkaluja) voit kuitenkin käyttää ristiin. Kannattaa kokeilla eri tapoja. Mikroluokista löytyy ainakin komentorivityökalut, Eclipse sekä TortoiseGit.

Asenna näistä kohdista ainakin komentoriviin liittyvät asiat. Voit asentaa myös muita jos siltä tuntuu.

Gitin yksi oleellinen ero esimerkiksi SVN:ään on se, että varastoista (repository) voi olla useita kopioita lokaalisti ja etänä. Lokaalivarasto voidaan kopioida etävarastoon (remote repository) ja sieltä edelleen toiseen lokaaliin varastoon. Lisäksi etävarastojakin voi olla useita. Tämän takia komentoja on enemmän svn:ään verrattuna.

Gitissä on 4 tärkeää "tilaa", joiden välillä tietoa liikutetaan: working directory, index/stage, local repository ja remote repository. Alla olevassa kuvassa on esitetty tärkeimmät komennot tähän liikutteluun. Kaikista tärkeimmät niistä punaisilla nuolilla. Kuvassa keltaisella on merkitty omassa koneessa olevia tiloja ja sinisellä viitataan edellisen kuvan palvelimeen.

# umlGIT
HUOM! Tätä kuvaa ei pidä tulkita UML:än sekvenssikaavioksi!working directoryindex/stagelocal repositoryremote repositoryworking directoryindex/stagelocal repositoryremote repositoryclone <osoite>Annetaan kerran/koneadd --allKun tiedostot muuttuneetcommit -mpushpull or rebaseKun tasataan kaverin kanssafetchmergecheckout HEADcheckoutdiff HEADdiff
# terms

11.1 Git termejä:

  • repository = (tieto)varasto, paikka jossa versioitava tieto tallennetaan, voi olla lokaali (local) tai etä (remote), kumpiakin voi gitissä olla useita. local repository on käytännössä hakemistossa oleva .git-hakemisto. Repository koostuu loogisesti "commiteista", jotka muodostavat kokoelman projektin eri vaiheista, haaroista ja tageistä. Näin mihin tahansa commitoituun kohtaan voidaan viitata tai palata.
  • fork = projektista tehty "kopiohaara", joka elää omaa elämäänsä (tällä kurssilla). Fork ei ole Gitin toiminto, mutta useat ulkoiset Git- palvelimet (kuten GitHub ja GitLab) tarjoavat tämän toiminnon.
  • origin = lyhenne käytettävän etävaraston osoitteelle (remote repository)
  • project = jokin selkeä projekti, joka tähtää esimerkiksi jonkin yhden ohjelmatuotteen tekemiseen
  • working directory = työhakemisto (workspace joissakin dokumeteissa), lokaalin koneen työhakemisto (kaikki tiedostot ja versiot löytyvät tämän alla olevasta .git -hakemistosta, jos ne on koneelle haettu (fetch))
  • index = varastoon seuraavalla commitilla siirrettävien tiedostojen luettelo (versioitavien, staging area joissakin lähteissä, koska tiedosto laitetaan "näytille"). Käytännössä tiedosto .git/index.
  • master = projektin päähaara, joka pyritään pitämään toimivana koodina

Vaativampaan käyttöön ja viimeistään Ohjelmointi 2 -kurssilla tarvittavia termejä:

  • branch = kehityshaara jossa kehitetään uutta koodia. Kehityshaaroja voi olla useita. Kun koodi on hyväksi todettu, se voidaan yhdistää (merge) päähaaraan.
  • tag = jäädytetty haara (esimerkiksi ohjelman tietty versio), jota ei aktiivisesti kehitetä, mutta johon voi tulla esimerkiksi tietoturvapäivityksiä
  • HEAD = viite aktiivisen haaran "päähän" tietyssä lokaalissa

Kurssilla käytettäviä Git-komentoja:

git config --global user.name "Anonymous"
git config --global user.email "None"    
git clone https://gitlab.jyu.fi/Anonymous/ohj1ht.git .
git status  # tätä komentoa kannattaa käyttää ahkeraan vaikka joka välissä
git log     # samoin tätä, kunhan opit lukemaan sen sisältöä
# tee tarvittavia muutoksia
git add --all
git commit -m "Vaihe 1, kuvat"
git push    # kaverin pitää tämän jälkeen tehdä kotona tehdä git pull
git pull
# ongelmia

12. Ongelmia?

Ongelmia...

Kohta 6.1 git clone komennon jälkeen antaa tälläisen: fatal: destination path ‘.’ already exists and is not an empty directory.

VL: Sun pitää olla tyhjässä hakemistossa tekemässä tuo!

— 05 Oct 21 (edited 05 Oct 21)

12.1 Push ei onnistu (Access denied)

Kävin korjaamassa salasanaa User Accountsin puolella, muttei auttanut. Mitä teen seuraavaksi?

— 08 Feb 20

Kokeiles poistaa sieltä Accounts-listasta koko gitlab-kredentiaali. Silloin pitäs päästä syöttämään uudet kirjautumistiedot push vaiheessa. -AJL

— 08 Feb 20 (edited 09 Feb 21)

Annoit varmasti käyttäjätunnuksen muodossa tunnus@jyu.fi ? -AJL

— 09 Feb 20 (edited 09 Feb 21)

Jos tulee ilmoitus SSH:sta, niin olet ottanut Clone-vaiheessa Gitlabista SSH-linkin, kun piti ottaa HTTPS (“Clone with HTTPS”). Helpointa lienee clonettaa uudestaan oikean linkin kera. -AJL

— 10 Feb 20 (edited 09 Feb 21)

12.2 fatal: destination path ‘.’ already exists and is not an empty directory

12.3 error: '[ht]/' does not have a commit checked out, fatal: adding files failed

13. Lisätietoa kiinnostuneille

Mullakaan ei auta salasanan korjaaminen tai kredentiaalin poistaminen. Itselläni myös ilmoittaa, että “ou won’t be able to pull or push project code via SSH until you add an SSH key to your profile”.

Ohjeiden kohdassa 6 sinun olisi pitänyt kloonata HTTPS-osoitteella, eikä SSH-osoitteella. Helpointa on nyt ottaa muuttamasi tiedostot talteen kotikoneellasi, ja poistaa koneeltasi GitLabista kloonaamasi kansio. Sitten kloonaat sen uudestaan koneellesi ohjeiden mukaisesti HTTPS-osoitteella. -JuhoK

— 12 Feb 20 (edited 09 Feb 21)

These are the current permissions for this document; please modify if needed. You can always modify these permissions from the manage page.