GitHub-repositorion luominen – aloittelijan opas

GitHub-tili on luotu, mutta miten palveluun perustetaan oma projekti? Seuraava askel on repositorion luominen. Nimi saattaa kuulostaa tekniseltä, vaikka käytännössä kyse on projektin tiedostojen ja muutoshistorian yhteisestä paikasta.

Ensimmäisen repositorion tekemiseen et tarvitse ohjelmointitaitoa tai komentorivin tuntemusta. Kaikki tässä oppaassa esitetyt harjoitukset onnistuvat selaimessa. Voit aloittaa yksinkertaisesta muistiosta ja käyttää samaa toimintatapaa myöhemmin verkkosivujen, sovellusten tai muiden projektien ylläpitämiseen.

Tässä oppaassa luodaan uusi harjoitusprojekti alusta lähtien. Samalla käydään läpi tärkeimmät valinnat, ensimmäisten tiedostojen lisääminen ja muutosten tallentaminen.

Mikä repositorio tarkoittaa?

Repositorio eli repository sisältää projektin tiedostot ja niiden versionhallintahistorian. Siitä käytetään usein lyhyempää nimeä repo.

Tavallisesta tiedostokansiosta repositorio eroaa siinä, että tallennettuja muutoksia voidaan tarkastella jälkikäteen. Näet esimerkiksi, mitä tekstiä lisättiin, mitä poistettiin ja millaisella viestillä muutos tallennettiin.

Kuvitellaan, että kokoat retkeilyyn liittyvää varustelistaa. Ensimmäisessä versiossa luettelet välttämättömät tarvikkeet. Myöhemmin lisäät talviretkeilyn varusteet ja korjaat ruokamäärät. Versionhallinnan avulla nämä vaiheet jäävät näkyviin erillisinä muutoksina.

Repositorio voi sisältää esimerkiksi:

• Ohjelmakoodia.
• Verkkosivun tiedostoja.
• Käyttöohjeita.
• Harjoitustehtäviä.
• Projektin kuvia.
• Tekstimuotoisia muistiinpanoja.

Tiedostojen lisäksi GitHub tarjoaa projektin ympärille yhteistyötoimintoja. Versionhallinnan perusteita kuvataan GitHubin Git-oppaassa.

Suunnittele ensimmäiselle projektille pieni tarkoitus

Repositorion luominen helpottuu, kun tiedät suunnilleen, mitä aiot sinne tallentaa. Suurta suunnitelmaa ei tarvita, mutta selkeä tarkoitus auttaa nimeämään projektin ja kirjoittamaan sen esittelyn.

Tässä harjoituksessa voit käyttää aiheena omaa retkimuistiota. Sen ensimmäinen versio sisältää projektin kuvauksen ja lyhyen varustelistan.

Muita sopivia harjoitusaiheita ovat:

• Ohjelmoinnin oppimispäiväkirja.
• Oman verkkosivun suunnitelma.
• Harrastusprojektin käyttöohje.
• Kirjalista lyhyine muistiinpanoineen.
• Pienen sovelluksen ideakuvaus.

Valitse aihe, jonka sisältöä osaat arvioida itse. Silloin huomiosi ei kulu uuden aiheen opetteluun, vaan voit keskittyä GitHubin toimintaan.

Ensimmäisen repositorion tehtävä on tehdä työskentelystä ymmärrettävää. Muutama huolellisesti nimetty tiedosto riittää siihen hyvin.

Vaihe 1: Avaa uuden repositorion luominen

Kirjaudu GitHubiin ja varmista, että sähköpostiosoitteesi on vahvistettu. Avaa sitten sivun yläreunan luontivalikko ja valitse New repository.

Repositorion luomisnäkymässä määritellään esimerkiksi omistaja, nimi ja näkyvyys. Jos kuulut organisaatioihin, Owner-valinnassa voi näkyä useita vaihtoehtoja. Valitse henkilökohtaiseen harjoitukseen oma käyttäjätilisi.

Organisaation alle luominen edellyttää siihen riittäviä oikeuksia. Aloittelijan oma harjoitus on yleensä yksinkertaisinta pitää omalla tilillä.

Jos näkymässä tarjotaan projektipohjaa eli templatea, voit jättää sen valitsematta. Tässä harjoituksessa perustetaan uusi projekti ilman valmista pohjaa.

Lomakkeen ulkoasu voi muuttua, mutta keskeiset valinnat kuvataan GitHubin repositorion luontiohjeessa.

Vaihe 2: Anna projektille kuvaava nimi

Kirjoita Repository name -kenttään projektin nimi. Esimerkiksi retkimuistio kertoo sisällöstä enemmän kuin testi123.

Suosi lyhyttä nimeä, jonka pystyt tunnistamaan myöhemmin muiden projektien joukosta. Useammasta sanasta muodostuvassa nimessä väliviiva tekee kokonaisuudesta helposti luettavan.

Toimivia esimerkkejä ovat:

• oma-retkimuistio
• verkkosivu-harjoitus
• python-muistiinpanot
• harrastusprojektin-ohjeet

Description-kenttään voit lisätä lyhyen kuvauksen. Retkimuistiossa se voisi olla: ”Omat varustelistat ja muistiinpanot päiväretkien suunnitteluun.”

Nimen ja kuvauksen kannattaa täydentää toisiaan. Nimi auttaa tunnistamaan projektin, ja kuvaus kertoo sen käyttötarkoituksen.

Vältä liian yleistä kuvausta, kuten ”kaikenlaista”. Kun palaat projektiin kuukausien päästä, täsmällinen esittely auttaa muistamaan, miksi loit sen.

Vaihe 3: Valitse julkinen tai yksityinen repositorio

Näkyvyysvalinta määrittää, ketkä pääsevät tarkastelemaan projektia.

Public tarkoittaa julkista repositoriota. Private tarkoittaa yksityistä repositoriota, jonka sisältöön pääsy on rajattu käyttöoikeuksilla.

Valintaa voi pohtia näin:

• Valitse Public, kun tarkoituksesi on jakaa projekti avoimesti.
• Valitse Private, kun haluat harjoitella omassa rauhassa.
• Tarkista sisältö ennen kuin julkaiset henkilökohtaisia tietoja.
• Muista, että julkisesta sisällöstä voidaan tehdä kopioita.

GitHub Free mahdollistaa molemmat näkyvyydet, mutta yksityisten repositorioiden ominaisuuksissa on rajoituksia verrattuna laajempiin paketteihin. Lisätietoa löytyy GitHubin palvelupakettien kuvauksesta.

Ensimmäiseen retkimuistioon Private on luonteva valinta, jos sisältö on tarkoitettu vain itsellesi. Julkinen harjoitus sopii puolestaan oman oppimisen esittelyyn.

Vaihe 4: Lisää README-tiedosto

Valitse README-tiedoston lisääminen repositorion luonnin yhteydessä. Näin projektissa on heti ensimmäinen tiedosto ja paikka esittelylle.

README näkyy tavallisesti repositorion etusivulla tiedostoluettelon alapuolella. Sen avulla vierailija ymmärtää, mitä projekti sisältää ja miten sitä käytetään.

Hyvä esittely vastaa muutamaan kysymykseen:

• Mikä tämä projekti on?
• Miksi se on tehty?
• Mitä tiedostoista löytyy?
• Onko sisältö valmis vai keskeneräinen?
• Miten projektia käytetään?

Retkimuistion esittelyssä voit kertoa, että listat on tarkoitettu lyhyille päiväretkille ja että täydennät niitä kokemusten perusteella.

README kannattaa kirjoittaa myös yksityiseen projektiin. Se auttaa omaa muistiasi, kun palaat sisältöön tauon jälkeen. Esittelytiedoston tarkoitusta käsitellään GitHubin README-ohjeessa.

Vaihe 5: Tarkista gitignore ja lisenssi

Luomisnäkymässä voidaan tarjota myös .gitignore-tiedostoa ja lisenssiä.

.gitignore määrittää, mitä tiedostoja Gitin ei lähtökohtaisesti pidä ottaa uutena mukaan versionhallintaan. Ohjelmistoprojekteissa tällaisia voivat olla esimerkiksi väliaikaiset tiedostot ja paikallisen kehitysympäristön tuottama sisältö.

Pelkästä tekstistä koostuvassa harjoituksessa voit jättää valinnan tyhjäksi. Ohjelmointiprojektissa sopiva pohja valitaan käytetyn tekniikan mukaan. Valinnan tarkoitusta selittää GitHubin repositorion luontiohje.

Lisenssi puolestaan kertoo, millaisin ehdoin muut saavat käyttää ja jakaa projektiasi. Älä valitse sitä sattumalta. Yksityisessä harjoitusmuistiossa asian voi jättää myöhemmäksi, mutta avoimesti jaettavan ohjelmiston yhteydessä valinta on olennainen. Lisätietoa on GitHubin lisensointiohjeessa.

Vaihe 6: Luo repositorio ja kirjoita esittely

Tarkista nimi, omistaja ja näkyvyys. Paina sitten Create repository.

Kun projektin sivu avautuu, etsi README.md ja avaa se. Valitse muokkaustoiminto ja kirjoita muutama lause projektistasi.

Voit aloittaa esimerkiksi näin:

”Tähän projektiin kokoan päiväretkien varustelistoja. Tavoitteena on helpottaa pakkaamista ja opetella samalla GitHubin käyttöä. Täydennän listoja jokaisen retken jälkeen.”

README käyttää Markdown-muotoilua, mutta ensimmäiseen harjoitukseen tavallinen teksti riittää.

Valitse Commit changes ja kirjoita tallennusviestiksi esimerkiksi ”Lisää retkimuistion esittely”. Vahvista tallennus. Pienen oman harjoituksen muutoksen voi tässä vaiheessa tallentaa suoraan päähaaraan.

Selaimessa tehtävä aloitus vastaa GitHubin aloittelijan harjoituksen perusajatusta.

Vaihe 7: Lisää ensimmäinen oma tiedosto

Lisää seuraavaksi varsinainen muistio. Avaa tiedostoluettelon yhteydessä oleva Add file -valikko ja valitse Create new file.

Anna tiedostolle nimeksi varustelista.md. Kirjoita siihen esimerkiksi:

• Juomapullo.
• Eväät.
• Säänmukainen takki.
• Ladattu puhelin.
• Pieni ensiapupakkaus.

Tallenna tiedosto Commit changes -toiminnolla. Kuvaava tallennusviesti on ”Lisää päiväretken varustelista”.

Jos tiedosto on jo tietokoneellasi, voit käyttää Upload files -toimintoa. Selaimella ladattavan yksittäisen tiedoston kokoraja on 25 MiB, joten suuret aineistot tarvitsevat toisenlaisen toimintatavan. Rajasta kerrotaan GitHubin tiedostokoko-ohjeessa.

Tarkista ladattavat tiedostot ennen tallennusta. Projektiin kannattaa ottaa mukaan vain sen tarkoitukseen kuuluva sisältö.

Vältä tavallisimmat aloitusvirheet

Ensimmäinen kompastuskivi on liian suuri aloitus. Jos tuot kerralla paljon tiedostoja, muutosten seuraaminen vaikeutuu. Lisää ensin pieni kokonaisuus ja tarkista lopputulos.

Toinen yleinen sekaannus liittyy olemassa olevaan Git-projektiin. Jos olet siirtämässä sellaista tietokoneeltasi GitHubiin, luo etärepositorio ilman valmiita README-, .gitignore- ja lisenssitiedostoja. Näin vältät erikseen syntyvien historioiden yhdistämiseen liittyviä ongelmia. Poikkeus mainitaan GitHubin luontiohjeessa.

Kolmanneksi muista tarkistaa tallennuksesi. Avaa tiedosto uudelleen ja varmista, että nimi sekä sisältö ovat oikein.

Selkeät nimet, pienet muutokset ja ymmärrettävät tallennusviestit tekevät harjoittelusta huomattavasti helpompaa.

Ensimmäinen repositorio on valmis

Sinulla on nyt oma repositorio, projektin esittely ja ensimmäinen sisältötiedosto. Olet samalla harjoitellut GitHubin tärkeintä perusketjua: luo, muokkaa, tallenna ja tarkista.

Seuraavaksi voit lisätä varustelistaan yhden asian ja tutkia tallennettua muutosta. Myöhemmin kannattaa kokeilla erillistä haaraa ja muutosehdotusta.

Repositorion ei tarvitse olla suuri ollakseen hyödyllinen. Hyvin rajattu harjoitus tekee versionhallinnan idean näkyväksi ja antaa toimivan pohjan seuraavalle projektille.