Git- ja GitHub-käyttöopas Python-kehitykseen

Tämä ohje on tarkoitettu tilanteeseen, jossa kehität samaa Python-ohjelmaa usealla tietokoneella käyttäen Linux Mintiä, PyCharmia ja GitHubia. Lisäksi ohjelmaa voidaan ajaa Ubuntu-palvelimella.

Tavoitteena on, että GitHubissa on aina projektin yhteinen versio, johon tallennat muutokset yhdeltä koneelta ja josta haet ne toiselle.

1. Miten Git ja GitHub toimivat?

Git toimii paikallisesti jokaisella koneella. GitHub on etäpalvelu, jonka kautta muutokset siirtyvät koneiden välillä.

2. Projektin oikea hakemistorakenne

Suosittelen Python-projektiisi esimerkiksi seuraavaa rakennetta:

logocontrol/
├── .git/
├── .gitignore
├── .venv/
├── .env
├── .env.example
├── requirements.txt
├── README.md
├── app.py
├── entsoe.py
├── price_statistics.py
├── settings.example.json
└── tests/
    └── test_price_statistics.py

Kaikkia tiedostoja ei pidä tallentaa GitHubiin.

Esimerkki .gitignore-tiedostosta:

# Virtual environments
.venv/
venv/

# Python
__pycache__/
*.pyc
.pytest_cache/
.coverage

# IDE
.idea/

# Secrets and local settings
.env
.env.*
!.env.example
settings.json

# Logs
*.log

# Operating system
.DS_Store

Jos jokin tiedosto on jo Gitin seurannassa, pelkkä .gitignore ei poista sitä seurannasta. Käytä esimerkiksi git rm --cached settings.json.

3. Päivittäinen työnkulku usealla koneella

Tämä on koko oppaan tärkein osa.

A. Kun aloitat työskentelyn

cd ~/PycharmProjects/logocontrol

git status
git pull --ff-only

git status kertoo, onko paikallisia muutoksia. git pull --ff-only hakee GitHubin muutokset, mutta ei tee automaattista merge-committia, jos kehityshistoriat ovat eriytyneet. Tämä on turvallinen oletustapa usealla koneella.

Jos paikallisia keskeneräisiä muutoksia on, ratkaise ne ennen pullia esimerkiksi commitilla tai stashilla.

B. Kehitä ja testaa

Muokkaa ohjelmaa PyCharmissa.

pytest

Kun muutokset toimivat, tarkista:

git status
git diff

C. Tallenna muutokset

git add .
git commit -m "Improve cheapest 3h calculation"

git add . lisää muutokset seuraavaan committiin. Tarkista ennen committia git status, ettei mukaan tullut vahingossa ylimääräisiä tiedostoja. Commit tallentuu tässä vaiheessa vain omalle koneelle.

D. Lähetä GitHubiin

git push

Nyt toinen tietokone voi hakea muutokset.

Tärkein sääntö: Tee git push ennen kuin lopetat työskentelyn yhdellä koneella, ja git pull --ff-only ennen kuin aloitat toisella.

4. Uuden kehityskoneen käyttöönotto

Oletetaan, että haluat asentaa saman projektin toiselle Linux Mint -koneelle.

Vaihe 1. Asenna tarvittavat ohjelmat

sudo apt update
sudo apt install git python3-venv python3-pip

Vaihe 2. Ota GitHubin SSH-yhteys käyttöön

Luo SSH-avain:

ssh-keygen -t ed25519 -C "oma-kone"

Näytä julkinen avain:

cat ~/.ssh/id_ed25519.pub

Lisää avain GitHubiin kohdassa Settings → SSH and GPG keys.

Testaa:

ssh -T git@github.com

Jokaiselle tietokoneelle kannattaa luoda oma SSH-avain. Näin yksittäisen koneen avaimen voi tarvittaessa poistaa GitHubista vaikuttamatta muihin koneisiin.

Vaihe 3. Kloonaa projekti

mkdir -p ~/PycharmProjects
cd ~/PycharmProjects

git clone git@github.com:jokinenkalle/logocontrol.git
cd logocontrol

Jos repositorion nimi tai omistaja on muuttunut, käytä GitHubin näyttämää SSH-osoitetta.

Vaihe 4. Luo virtuaaliympäristö

python3 -m venv .venv
source .venv/bin/activate

Asenna riippuvuudet:

pip install -r requirements.txt

Jos requirements.txt puuttuu, voit luoda sen alkuperäisellä koneella aktivoidusta virtuaaliympäristöstä:

python -m pip freeze > requirements.txt

Tarkista lista ja committoi tiedosto. pip freeze tallentaa kaikki ympäristön asennetut paketit, myös mahdolliset tarpeettomat kehityspaketit.

Vaihe 5. Avaa PyCharmissa

Avaa kloonattu projektihakemisto ja määritä Python Interpreteriksi:

~/PycharmProjects/logocontrol/.venv/bin/python

Luo lisäksi konekohtaiset .env ja settings.json esimerkkitiedostojen perusteella.

5. Mitä jos unohdat pushin toisella koneella?

Esimerkki:

• Kone A: teet muutoksia ja commitin, mutta unohdat pushin.
• Kone B: teet muita muutoksia ja pushaat GitHubiin.
• Kone A: yrität tehdä pushin.

Git voi ilmoittaa:

! [rejected] main -> main (fetch first)

Tämä tarkoittaa, että GitHubissa on committeja, joita koneella A ei vielä ole.

Ratkaisu, kun työpuu on puhdas:

git fetch origin
git rebase origin/main
git push

rebase siirtää omat paikalliset commitit GitHubista haettujen muutosten päälle. Jos samoja rivejä on muokattu, voi tulla konflikti, joka pitää ratkaista käsin.

Älä käytä git push --force tähän ongelmaan. Se voi ylikirjoittaa muiden koneiden commit-historiaa.

6. Git-branchit – turvallinen tapa kehittää uusia ominaisuuksia

Kun teet isompaa muutosta, kuten uutta ENTSO-E-hintojen optimointia, voit käyttää omaa kehityshaaraa.

Luo uusi haara:

git switch main
git pull --ff-only
git switch -c feature/price-optimization

Tee muutoksia ja committoi:

git add .
git commit -m "Add price optimization algorithm"
git push -u origin feature/price-optimization

Nyt haara on myös GitHubissa, joten voit jatkaa sen kehitystä toisella koneella.

Toisella koneella:

git fetch origin
git switch --track origin/feature/price-optimization

Kun ominaisuus on valmis, voit yhdistää sen main-haaraan esimerkiksi GitHubin Pull Requestilla.

Tällä tavalla keskeneräinen ominaisuus ei sotke toimivaa pääversiota.

7. Ubuntu-palvelin ja GitHub

Jos ohjelma pyörii Ubuntu-palvelimellasi, suosittelen erottamaan kehityksen ja tuotantokäytön.

Kehityskoneilla: muokataan, testataan ja pusketaan muutoksia.

Ubuntu-palvelimella: haetaan vain testattu versio. Palvelimella ei normaalisti tehdä koodimuutoksia.

Palvelimen päivitys voisi olla esimerkiksi:

cd ~/logocontrol

git pull --ff-only
source .venv/bin/activate
pip install -r requirements.txt

Sen jälkeen käynnistetään ohjelman systemd-palvelu uudelleen tarvittaessa.

Tuotantokäytössä kannattaa ottaa käyttöön versiotagit, jolloin palvelin voidaan päivittää nimenomaan tiettyyn testattuun julkaisuun, eikä aina uusimpaan main-committiin.

8. Yleisimmät Git-komennot

9. Harjoittele Git-komentoja

10. Suosittelemani toimintatapa sinulle

Koska kehität samaa Python-projektia usealla koneella ja käytät lisäksi Ubuntu-palvelinta, suosittelen seuraavaa:

1. main sisältää aina toimivan version.
2. feature/... -haaroissa kehitetään isommat muutokset ja kokeillaan uusia ominaisuuksia.
3. Jokaisella koneella on oma .venv, .env ja settings.json.
4. requirements.txt pidetään versionhallinnassa, jotta riippuvuudet ovat toistettavissa.
5. Aina ennen kehitystyötä tehdään git status ja git pull --ff-only.
6. Työskentelyn lopuksi tehdään git add, git commit ja git push.
7. Ubuntu-palvelimelle viedään vain testattu versio.

Yksi erityisen hyödyllinen lisä olisi automaattinen testaus GitHub Actionsilla: jokainen GitHubiin lähetetty muutos käynnistäisi esimerkiksi pytest-testisi. Näkisit heti, jos ENTSO-E-hintalaskennan tai LOGO-ohjauksen muutokset rikkovat aiemmin toimineita funktioita.

Lisätietoja löytyy myös Pro Git -kirjasta ja GitHubin virallisesta dokumentaatiosta.