Tiedostojen lisääminen GitHubiin – helppo ohje

GitHub-repositorio on luotu, mutta projektin tiedostot odottavat vielä tietokoneella. Miten ne siirretään GitHubiin? Entä voiko uuden tiedoston kirjoittaa suoraan selaimessa?

Molemmat onnistuvat. Voit ladata repositorioon valmiita tiedostoja tai luoda sinne uutta tekstisisältöä GitHubin omalla editorilla. Ensimmäisiin harjoituksiin et tarvitse komentoriviä, erillistä ohjelmaa tai aiempaa kokemusta versionhallinnasta.

Tässä oppaassa lisäät tiedostoja omaan repositorioosi, kirjoitat tallennukselle kuvaavan viestin ja tarkistat lopputuloksen. Lisäksi opit järjestämään sisältöä kansioihin sekä tunnistamaan tavallisimmat tilanteet, joissa tiedoston lisääminen ei onnistu odotetusti.

Mitä tarvitset ennen tiedostojen lisäämistä?

Tarvitset GitHub-tilin ja repositorion, johon sinulla on kirjoitusoikeus. Omassa henkilökohtaisessa repositoriossasi voit yleensä lisätä tiedostoja heti, kun tilin käyttöönotto on valmis.

Valitse ensimmäiseen kokeiluun pieni ja helposti tarkistettava tiedosto. Esimerkiksi lyhyt käyttöohje tai muistiinpano sopii harjoitteluun paremmin kuin kokonainen ohjelmistopaketti.

Varmista ennen aloittamista:

• Olet kirjautunut oikealle GitHub-tilille.
• Olet avannut tarkoittamasi repositorion.
• Tiedät, onko repositorio julkinen vai yksityinen.
• Tiedoston sisältö kuuluu kyseiseen projektiin.
• Tiedoston nimi kertoo ymmärrettävästi sen tarkoituksen.

Tässä harjoituksessa voit käyttää tiedostoa nimeltä kayttoohje.txt. Kirjoita siihen tietokoneellasi muutama lause projektin käyttämisestä ja tallenna se helposti löydettävään kansioon.

Valitse sopiva tapa lisätä tiedosto

GitHubissa on kaksi suoraviivaista vaihtoehtoa selainkäyttöön.

Upload files tarkoittaa tietokoneella olevien tiedostojen lataamista repositorioon. Create new file puolestaan avaa editorin, jossa voit kirjoittaa uuden tiedoston sisällön.

Valitse toimintatapa tilanteen mukaan:

• Käytä Upload files -toimintoa, kun tiedosto on jo tietokoneellasi.
• Käytä Create new file -toimintoa, kun haluat kirjoittaa uuden tekstitiedoston.
• Käytä olemassa olevan tiedoston muokkausta, kun korjaat aiemmin lisättyä tekstiä.

Esimerkiksi kuva ladataan valmiina tiedostona. Lyhyen ohjeen voit kirjoittaa suoraan GitHubiin.

Selaimessa tehtävä työskentely sopii erityisesti pieniin muutoksiin. Laajemmissa projekteissa paikallinen Git-työskentely helpottaa useiden tiedostojen käsittelyä. Eri lisäämistavat esitellään GitHubin tiedostojen lisäämisohjeessa.

Vaihe 1: Avaa oikea repositorio ja kansio

Siirry repositorion Code-välilehdelle. Näet projektin tiedostoluettelon ja käytössä olevan haaran nimen.

Haara tarkoittaa projektin erillistä kehityslinjaa. Päähaaran nimi on usein main. Ensimmäisessä omassa harjoituksessa voit aloittaa siitä, jos repositorion säännöt sallivat suorat muutokset.

Jos haluat tiedoston olemassa olevaan alikansioon, avaa kansio ennen lataamista. Näin tiedosto päätyy haluamaasi paikkaan.

Tarkista sijainti rauhassa. Samannimisiä tiedostoja voi olla eri kansioissa, ja väärä sijoitus voi myöhemmin hankaloittaa esimerkiksi kuviin tai ohjeisiin viittaamista.

Ajattele kansiorakennetta projektin hyllyjärjestyksenä: kun jokaisella sisällöllä on luonteva paikka, sitä on helpompi löytää ja ylläpitää.

Vaihe 2: Valitse Upload files

Avaa tiedostoluettelon yhteydessä oleva Add file -valikko ja valitse Upload files.

Voit valita tiedostot tietokoneeltasi choose your files -linkillä tai vetää ne latausalueelle. Aloita yhdestä pienestä tiedostosta.

Odota, että tiedoston siirto valmistuu ja sen nimi näkyy sivulla. Tarkista tämän jälkeen, että valitsit oikean tiedoston.

Huomioi erityisesti:

• Onko tiedoston nimi oikein?
• Onko mukana vahingossa ylimääräisiä tiedostoja?
• Onko kyseessä uusin versio?
• Oletko lataamassa tiedoston oikeaan kansioon?

Pelkkä tiedoston vetäminen sivulle ei vielä viimeistele muutosta repositorioon. Lisääminen pitää vahvistaa tallennuksella. Latauksen vaiheet löytyvät GitHubin virallisesta ohjeesta.

Vaihe 3: Kirjoita kuvaava tallennusviesti

GitHub tallentaa muutokset commit-kokonaisuuksina. Commitiin liitetään viesti, jonka tarkoitus on kertoa, mitä projektissa muuttui.

Kirjoita viesti niin, että ymmärrät sen vielä myöhemmin ilman tiedoston avaamista.

Hyviä esimerkkejä ovat:

• Lisää projektin käyttöohje.
• Lisää etusivun kansikuva.
• Päivitä asennuksen valmisteluvaiheet.
• Lisää esimerkkitiedosto harjoitteluun.

Viestit kuten ”päivitys” tai ”uutta” jäävät helposti epäselviksi. Jos projektissa on kymmeniä samanlaisia tallennuksia, oikean muutoksen löytäminen vaikeutuu.

Pidä myös yhden tallennuksen sisältö yhtenäisenä. Käyttöohje ja siihen liittyvä esimerkkikuva sopivat samaan kokonaisuuteen. Toisistaan riippumattomat muutokset kannattaa usein tallentaa erikseen.

Commitien merkitystä projektin historiassa selittää GitHubin Git-opas.

Vaihe 4: Valitse tallennuksen haara

Tallennusnäkymässä voit tilanteesta riippuen valita nykyisen haaran tai uuden haaran.

Pienessä henkilökohtaisessa harjoituksessa suora tallennus nykyiseen haaraan on yksinkertainen vaihtoehto. Valitse tällöin sitä vastaava kohta ja vahvista tallennus Commit changes -painikkeella.

Yhteisessä projektissa uusi haara ja muutosehdotus antavat mahdollisuuden tarkistaa lisäyksen ennen sen yhdistämistä päähaaraan.

Tällöin etenet näin:

1. Valitse uuden haaran luominen.
2. Anna haaralle kuvaava nimi.
3. Tallenna ehdotettu muutos.
4. Avaa pull request eli muutosehdotus.
5. Tarkista sisältö ennen yhdistämistä.

Painikkeessa voi lukea Propose changes, kun olet ehdottamassa muutosta. GitHubin aloitusharjoitus opastaa haaran ja muutosehdotuksen käyttöön.

Vaihe 5: Tarkista lisätty tiedosto

Palaa tallennuksen jälkeen tiedostoluetteloon ja avaa lisäämäsi tiedosto.

Tekstitiedostosta voit tarkistaa sisällön. Kuvasta voit katsoa, että latasit oikean version. Kaikkia tiedostomuotoja GitHub ei esitä samalla tavalla, joten esikatselun puuttuminen ei yksin tarkoita epäonnistunutta latausta.

Tarkista ainakin:

• Tiedosto näkyy oikeassa kansiossa.
• Tiedoston nimi ja pääte ovat oikein.
• Sisältö vastaa tarkoitustasi.
• Tallennusviesti kuvaa tehtyä muutosta.

Jos käytit erillistä haaraa, tiedosto näkyy ensin siinä. Se tulee päähaaraan vasta muutosehdotuksen yhdistämisen jälkeen.

Tämä selittää tavallisen hämmennyksen: tiedosto voi olla onnistuneesti tallennettu, vaikka sitä ei vielä löydy päähaaran näkymästä.

Näin luot uuden tiedoston suoraan selaimessa

Jos tiedostoa ei vielä ole, voit kirjoittaa sen GitHubissa.

Avaa Add file ja valitse Create new file. Kirjoita nimikenttään esimerkiksi muistiinpanot.md.

Lisää editoriin lyhyt teksti siitä, mitä opit harjoituksessa. Voit luetella esimerkiksi lataamisen, tallennusviestin ja lopputuloksen tarkistamisen.

Etene seuraavasti:

1. Anna tiedostolle nimi päätteineen.
2. Kirjoita sisältö.
3. Tarkista mahdollinen Preview-esikatselu.
4. Valitse Commit changes.
5. Kirjoita kuvaava tallennusviesti.
6. Valitse haara ja vahvista muutos.

Pääte .md tarkoittaa Markdown-tiedostoa. Se sopii ohjeisiin ja muistiinpanoihin, joissa haluat käyttää otsikoita sekä listoja. Tavalliseen tekstiin voit käyttää .txt-päätettä. Luontivaiheet kuvataan GitHubin uuden tiedoston ohjeessa.

Järjestä sisältö kansioihin

Kun tiedostoja kertyy, jaa niitä käyttötarkoituksen mukaan. Pienessä projektissa muutama kansio riittää.

Voit käyttää esimerkiksi seuraavaa jakoa:

• ohjeet sisältää käyttö- ja asennusohjeet.
• kuvat sisältää projektin kuvat.
• esimerkit sisältää kokeiltavat mallisisällöt.

Uuden tiedoston nimikenttään voi kirjoittaa polun, kuten ohjeet/aloittaminen.md. Kauttaviiva erottaa kansion ja tiedoston. GitHub luo tarvittavan alikansion tiedoston yhteydessä. Tämä toimintatapa mainitaan tiedostojen luontiohjeessa.

Vältä tarpeettoman syvää kansiorakennetta. Jos yhden ohjeen löytämiseksi pitää avata monta lähes tyhjää kansiota, rakenne kaipaa yksinkertaistamista.

Päivitä olemassa olevaa tiedostoa

Pienen tekstikorjauksen voit tehdä avaamalla tiedoston ja valitsemalla muokkaustoiminnon, joka näkyy tavallisesti kynäkuvakkeena.

Korjaa sisältö, tarkista esikatselu ja tallenna muutos uudella commit-viestillä. Esimerkiksi ”Selvennä ensimmäistä asennusvaihetta” kertoo muutoksen tarkoituksen.

Ohje löytyy GitHubin tiedostojen muokkausoppaasta.

Vältä jatkuvaa uusien rinnakkaisversioiden lisäämistä nimillä ohje-uusi, ohje-uusin ja ohje-lopullinen. Versionhallinnan hyöty syntyy siitä, että saman tiedoston muutokset säilyvät historiassa.

Pidä tiedoston nimi vakaana silloin, kun sen käyttötarkoitus pysyy samana. Näin myös siihen johtavat viittaukset pysyvät helpommin kunnossa.

Mitä tehdä, jos lisääminen epäonnistuu?

Tarkista ensin tiedostokoko. Selaimessa yksittäisen tiedoston raja on 25 MiB, ja samalla kertaa voi ladata enintään 100 tiedostoa. Suurempien tiedostojen käsittelyyn tarvitaan toinen menetelmä. Rajat on kerrottu GitHubin latausohjeessa.

Jos muokkaus ei ole sallittu, tarkista käyttöoikeudet ja haaran suojaus. Projektin säännöt voivat edellyttää erillistä haaraa.

Älä lisää salasanoja tai salaisia avaimia tiedostoihin. Jos sellainen päätyy historiaan, pelkkä poistaminen uusimmasta versiosta ei riitä. Vuotanut tunnus pitää mitätöidä tai vaihtaa, ja historia käsitellä tarvittaessa erikseen. Toimintaohje löytyy GitHubin arkaluonteisten tietojen poistamisohjeesta.

Aloita pienellä ja toista sama toimintatapa

Tiedostojen lisäämisen perusketju on yksinkertainen: valitse sijainti, lisää sisältö, kirjoita tallennusviesti ja tarkista lopputulos.

Harjoittele ensin yhdellä tekstillä ja yhdellä kuvalla. Kun nämä onnistuvat, useamman tiedoston käsittely tuntuu jo tutulta. Huolelliset nimet ja pienet, selkeät tallennukset auttavat pitämään projektin ymmärrettävänä myös sen kasvaessa.