Git ve proje yapısı

Derinleş: Git'i gerçekten kullanmak

Temel akışı (add, commit, dal, PR) ve proje ağacını gördün. İşte ilk haftanda ise şu sorular gelir: "Git'i nasıl kurarım, kimliğimi nasıl tanıtırım?", "Yanlış commit'i nasıl geri alırım?", "Birleştirmede çakışma çıktı, bu <<<<<<< işaretleri ne?", "Windows'ta çalışan arkadaşımın dosyalarında neden her satır değişmiş görünüyor?", "Hangi commit hatayı getirdi?". Bu bölüm bunları yanıtlar ve Git çıktılarını Python'la işleyen küçük araçlar yazdırır. Otomatik kalite kontrolleri (pre-commit, GitHub Actions) kalite-ci, paket sürümleme ve yayımlama paketleme-dagitim dersinde.

Kurulum ve ilk ayarlar

# Windows:  winget install --id Git.Git -e   (ya da git-scm.com; Git Bash da gelir)
# macOS:    xcode-select --install   ya da   brew install git
# Ubuntu:   sudo apt install git     | Fedora: sudo dnf install git
git --version

git config --global user.name "Ayşe Yılmaz"
git config --global user.email "ayse@ilgazbank.example"
git config --global init.defaultBranch main
git config --global pull.rebase true          # pull sırasında gereksiz merge commit'i olmasın
git config --global core.autocrlf true        # yalnız Windows: depoda LF, diskte CRLF
git config --global core.autocrlf input       # macOS/Linux
git config --list --show-origin               # hangi ayar nereden geliyor

# GitHub/GitLab için SSH anahtarı (parola yerine)
ssh-keygen -t ed25519 -C "ayse@ilgazbank.example"
cat ~/.ssh/id_ed25519.pub        # bu satırı GitHub > Settings > SSH keys'e yapıştır
ssh -T git@github.com            # "Hi ayse! You've successfully authenticated"

Satır sonu farkı (Windows CRLF \r\n, Linux/macOS LF \n) karışık ekiplerde "her satır değişti" görünen diff'lerin bir numaralı nedenidir. Ekip genelinde kalıcı çözüm depo köküne bir .gitattributes koymaktır: * text=auto eol=lf ve *.bat text eol=crlf.

dosyalar = {
    "src/rapor.py": b"import csv\nprint('ok')\n",
    "src/kargo.py": b"UCRET = 45\r\nKDV = 0.2\r\n",
    "scripts/kur.bat": b"@echo off\r\npy -m venv .venv\r\n",
    "README.md": b"# Rapor\r\nKurulum\n",
}
for yol, icerik in dosyalar.items():
    crlf = icerik.count(b"\r\n")
    lf = icerik.count(b"\n") - crlf
    tur = "KARIŞIK" if crlf and lf else "CRLF" if crlf else "LF"
    uyari = "" if tur == "LF" or yol.endswith(".bat") else "  <- .gitattributes ile LF'e çevrilmeli"
    print(f"{yol:18} {tur}{uyari}")

Geri alma: hangi komut ne zaman?

Birleştirme çakışması (merge conflict)

İki dal aynı satırı farklı değiştirdiyse Git karar veremez ve dosyaya işaretler koyar. <<<<<<< HEAD ile ======= arası senin dalın, ======= ile >>>>>>> arası gelen dal. Doğru sonucu elle yazar, işaretleri silersin, sonra git add dosya ve git commit (rebase sırasındaysan git rebase --continue). Vazgeçmek için git merge --abort. İşaretlerin yanlışlıkla commit'lenmemesi için CI'da basit bir kontrol çok işe yarar:

dosya = """VERGI_ORANI = 0.20
<<<<<<< HEAD
KARGO_UCRETI = 45
=======
KARGO_UCRETI = 49.90
>>>>>>> kargo-zammi
PARA_BIRIMI = "TL"
"""

def cakismalar(metin):
    bloklar, durum, bizim, onlarin = [], None, [], []
    for satir in metin.splitlines():
        if satir.startswith("<<<<<<<"):
            durum, bizim, onlarin = "bizim", [], []
        elif satir.startswith("=======") and durum == "bizim":
            durum = "onlarin"
        elif satir.startswith(">>>>>>>") and durum == "onlarin":
            bloklar.append({"bizim": bizim, "onlarin": onlarin, "dal": satir[8:].strip()})
            durum = None
        elif durum == "bizim":
            bizim.append(satir)
        elif durum == "onlarin":
            onlarin.append(satir)
    return bloklar

for b in cakismalar(dosya):
    print(f"main: {b['bizim']}  |  {b['dal']}: {b['onlarin']}")

Rebase, etiket ve geçmişte arama

git rebase main dalındaki commit'leri main'in en güncel hâlinin üstüne taşır; geçmiş düz kalır. Kural: yalnızca kendi, paylaşılmamış dalını rebase et. Sürüm yayımlarken git tag -a v1.4.0 -m "Kasım sürümü" ve git push origin v1.4.0. Hatanın hangi commit'le geldiğini bulmak için git bisect ikili arama yapar: iyi ve kötü commit'i söylersin, Git ortadakini açar, sen test edersin; birkaç adımda suçlu bulunur. git blame dosya her satırı son değiştireni, git log -S "KARGO_UCRETI" --oneline o metni ekleyen/silen commit'leri gösterir.

git log --oneline --graph --all -20       # dalları görsel izle
git log --since="2 weeks" --author="Ayşe" -- src/
git show v1.4.0 --stat
git bisect start; git bisect bad; git bisect good v1.3.0
git bisect run python -m pytest tests/test_kargo.py   # otomatik ikili arama
git bisect reset

Git'in "makine dostu" çıktılarını betiklerle işlemek CI ve sürüm otomasyonunun temelidir. git status --porcelain her satırda iki harfli durum kodu verir (M değişti, A eklendi, ?? izlenmiyor); Conventional Commits (feat:, fix:, feat!:) mesajlarından ise sürüm numarası ve değişiklik günlüğü (CHANGELOG) otomatik üretilir:

import re

log = """a1b2c3d feat(rapor): şehir kırılımı eklendi
9f8e7d6 fix: KDV yuvarlaması Decimal'e taşındı
5c4b3a2 docs: README kurulum adımları
1a2b3c4 feat!: CSV ayırıcısı ; oldu"""

gruplar = {"Yeni özellikler": [], "Hata düzeltmeleri": [], "Kırıcı değişiklikler": []}
for satir in log.splitlines():
    h, mesaj = satir.split(" ", 1)
    m = re.match(r"(\w+)(\([\w-]+\))?(!)?: (.+)", mesaj)
    if not m:
        continue
    tur, _, kirici, ozet = m.groups()
    if kirici:
        gruplar["Kırıcı değişiklikler"].append(f"{ozet} ({h})")
    elif tur == "feat":
        gruplar["Yeni özellikler"].append(f"{ozet} ({h})")
    elif tur == "fix":
        gruplar["Hata düzeltmeleri"].append(f"{ozet} ({h})")
for baslik, maddeler in gruplar.items():
    if maddeler:
        print("##", baslik)
        print("\n".join("- " + x for x in maddeler))

Ortak çalışma: issue, inceleme, birleştirme kararı

Git komutları işin yarısıdır; diğer yarısı insanlarla anlaşmaktır. Depo paylaşılınca değişiklik bir sohbetle başlar, bir kararla biter.

Çakışma (merge conflict) en çok iki kişi aynı satırı değiştirince çıkar. Sık git pull, küçük değişiklik ve işi önceden konuşmak çakışmayı azaltır. Çıktığında iki tarafın niyetini oku, gerekiyorsa arkadaşına sor, sonra testleri yeniden çalıştır.

Bir işe alımcı portföy deponu ortalama bir-iki dakika inceler ve çoğu zaman yalnız README'yi okur. Bu bölüm, bir analiz ya da yazılım projesini GitHub'da "okunur" bir portföy parçasına çevirmeyi anlatıyor: README şablonu, bulgu özeti, ekran görüntüleri ve depoyu yayına alma adımları.

Portföy deposunun yapısı

anadolu-market-analizi/
├── README.md              ← vitrin: 1 dakikada okunur
├── notebooks/             ← keşif (çıktıları temizlenmiş, nbstripout)
├── src/analiz/            ← tekrar kullanılan kod
├── raporlar/rapor.html    ← nbconvert/Quarto çıktısı
├── gorseller/             ← README'de kullanılan PNG'ler (küçük, sıkıştırılmış)
├── data/README.md         ← veri nereden, nasıl indirilir (ham veri depoda değil)
├── tests/
├── pyproject.toml / requirements.txt
└── LICENSE

README şablonu

İyi bir portföy README'si bir hikâye anlatır: sorun neydi, ne yaptın, ne buldun, nasıl tekrar üretilir. Aşağıdaki başlıklar hem analiz hem yazılım projelerinde işe yarar:

# Anadolu Market: Şehir bazlı satış ve iade analizi

> 910 siparişlik e-ticaret verisinde ciro ve iadeyi şehir, kanal ve zamana göre inceledim.
> En önemli bulgu: ... (tek cümle, rakamla)

![Şehir bazlı ciro](gorseller/sehir_ciro.png)

## Sorun
Yönetim hangi şehirlerde büyümeye yatırım yapılacağını soruyor.

## Veri
- Kaynak: Kesit Python "anadolu_market" kurgusal veri seti (10 tablo, 6.236 satır)
- Dönem: 2022-06 – 2024-12

## Yöntem
SQL (sqlite3) ile birleştirme → pandas ile temizlik → kohort ve RFM → görselleştirme

## Bulgular
| Şehir | Teslim edilen sipariş | Ciro (TL) |
|---|---|---|
| İstanbul | 162 | 199.387,25 |
| ...

1. ...
2. ...

## Öneriler ve sınırlamalar

## Nasıl çalıştırılır
    git clone https://github.com/kullanici/anadolu-market-analizi
    cd anadolu-market-analizi && pip install -r requirements.txt
    python -m analiz.rapor        # raporlar/rapor.html üretir

## Teknolojiler
Python 3.12 · pandas · SQLite · matplotlib · pytest

Bulgu tablosunu elle yazmak yerine koddan üret; README sayıları ile rapor sayıları hiç ayrışmaz:

import veri
conn = veri.baglan("anadolu_market", tablolar=["orders", "order_items", "customers"])
satirlar = conn.execute("""
    SELECT c.city, COUNT(DISTINCT o.order_id),
           ROUND(SUM(oi.quantity * oi.unit_price * (1 - oi.discount)), 2) AS ciro
    FROM orders o JOIN customers c USING (customer_id) JOIN order_items oi USING (order_id)
    WHERE o.status = 'delivered' AND c.city IS NOT NULL
    GROUP BY c.city ORDER BY ciro DESC LIMIT 3""").fetchall()

tl = lambda x: f"{x:,.2f}".replace(",", "X").replace(".", ",").replace("X", ".")
print("| Şehir | Teslim edilen sipariş | Ciro (TL) |")
print("|---|---|---|")
for sehir, n, ciro in satirlar:
    print(f"| {sehir} | {n} | {tl(ciro)} |")

Ekran görüntüleri ve görseller

README'nin en üstündeki tek bir grafik ya da uygulama ekran görüntüsü, okuyucunun kalmasını sağlar. Görselleri gorseller/ klasörüne koy, göreli yolla bağla (![açıklama](gorseller/x.png)), alternatif metni anlamlı yaz, boyutu küçük tut (genişlik 1200 px civarı, birkaç yüz KB). Etkileşimli bir uygulama ise kısa bir GIF ya da canlı demo bağlantısı (Streamlit Community Cloud, Render, GitHub Pages) çok etkilidir.

GitHub'da yayın