# فصل ۰۳ — نسخه‌بندی: `git` از داخلِ Colab

<div dir="rtl">

# فصل ۰۳ — نسخه‌بندی: `git` از داخلِ Colab

## در این فصل چه یاد می‌گیری

پروژه‌ات چند فایل شد. حالا اولین باری که چیزی را عوض کنی و خراب شود، سؤالِ ناگزیر می‌آید: **نسخهٔ دیروز کجاست؟** جوابِ حرفه‌ای `git` است — و در این فصل آن را نه به‌عنوانِ فهرستی از دستورها، بلکه به‌عنوانِ سه مفهوم یاد می‌گیری. و یک مشکلِ خاصِ خودمان را هم حل می‌کنیم: **نوت‌بوک در `git` بدرفتار است** و اگر ندانی چرا، مخزنت در یک ماه غیرقابلِ استفاده می‌شود.

![چند برگهٔ هم‌شکل که پشتِ سرِ هم روی یک ریلِ زمانی چیده شده‌اند و یکی از آن‌ها بیرون کشیده شده](/lesson-assets/t5-s03-git/prompt/01-image-versions-rail.png)

آخر این فصل می‌توانی:

- بگویی `commit` و `remote` چه هستند و چه فرقی دارند
- در Colab یک مخزن بسازی و تغییراتت را `push` کنی
- `.gitignore` بنویسی و بدانی چه چیزی هرگز نباید `commit` شود
- نوت‌بوک را طوری `commit` کنی که تاریخچه‌ات خوانا بماند

## قبل از شروع

**از فصل ۲:** پوشهٔ پروژه و فایل‌های `.py`.

**از ترمِ ۴ فصل ۳:** اینکه کلید هرگز داخلِ کد نمی‌رود — اینجا به شکلِ خطرناک‌تری برمی‌گردد.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-5-shipping/session-03-git.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

> 💡 **نکته:** بخشِ ۶ این فصل به حسابِ GitHub تو بستگی دارد، پس خروجی‌هایش اینجا تقریبی‌اند. بقیهٔ دستورها حساب نمی‌خواهند. دستورها را با حسابِ خودت اجرا کن، نه با کپیِ کورکورانه.

## ۱. سه مفهوم، نه سی دستور

</div>

| مفهوم | یعنی چه | کجا زندگی می‌کند |
|---|---|---|
| `repository` | پوشهٔ پروژه به‌همراه کلِ تاریخچه‌اش | روی دیسکِ خودت |
| `commit` | یک عکسِ لحظه‌ای از کلِ پروژه، با یک پیام | داخلِ همان تاریخچه |
| `remote` | نسخه‌ای از همان مخزن روی سروری دیگر | مثلاً GitHub |

<div dir="rtl">

هر چیزِ دیگری که دربارهٔ `git` می‌شنوی، ترکیبی از همین سه‌تاست. **و ترتیبشان مهم است:** اول مخزن، بعد `commit`، و `remote` فقط وقتی لازم است که بخواهی جای دیگری هم نسخه‌ای داشته باشی.

**چرا اصلاً لازمش داری؟** سه دلیلِ عملی: برمی‌گردی به هر نقطه‌ای از گذشته؛ می‌بینی دقیقاً چه چیزی بینِ دو نسخه عوض شده؛ و در فصلِ ۶ که کارت را منتشر می‌کنی، **راهِ انتشار خودش `git` است**.

## ۲. راه‌اندازی در Colab

</div>

```bash
git config --global user.name "نام تو"
git config --global user.email "you@example.com"
git --version
```

<div dir="rtl">

</div>

```text-approx
git version 2.43.0
```

<div dir="rtl">

Colab خودش `git` را دارد، ولی نمی‌داند تو کی هستی. **این دو خط را در هر جلسهٔ تازه دوباره باید بزنی**، چون دیسکِ Colab با پایانِ جلسه پاک می‌شود.

</div>

```bash
mkdir -p price_project && cd price_project && git init -b main && git status
```

<div dir="rtl">

</div>

```text-approx
Initialized empty Git repository in /content/price_project/.git/
On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)
```

<div dir="rtl">

آن `-b main` یعنی نامِ شاخهٔ اصلی `main` باشد. بدونِ آن، پیش‌فرضِ خودِ `git` هنوز `master` است و `git push -u origin main` در بخشِ ۶ با `src refspec main does not match any` می‌شکند. **شاخه** فعلاً یعنی همان خطِ تاریخچه‌ای که روی آن کار می‌کنی، و در این دوره فقط یکی داری.

## ۳. چرخهٔ روزانه: چهار دستور

</div>

| دستور | یعنی |
|---|---|
| `git status` | الان چه چیزی عوض شده؟ |
| `git add <file>` | این تغییر را برای عکسِ بعدی آماده کن |
| `git commit -m "پیام"` | عکس را بگیر و در تاریخچه ثبت کن |
| `git log --oneline` | تا حالا چه عکس‌هایی گرفته‌ام؟ |

<div dir="rtl">

پوشهٔ `price_project` هنوز خالی است. پس اول کارِ فصلِ ۲ را به آن می‌آوریم، فقط فایل‌های `.py`. پوشهٔ `__pycache__` را عمداً نمی‌آوریم، چون `.gitignore` را تازه در بخشِ بعد می‌نویسیم. اگر جلسهٔ Colab تازه است و `price_tool` را نداری، کدهای فصلِ ۲ را دوباره اجرا کن.


</div>

```bash
mkdir -p price_project/price_tool && cp price_tool/*.py price_project/price_tool/
```

<div dir="rtl">

</div>

```python
from pathlib import Path

Path("price_project/requirements.txt").write_text(
    "pandas==3.0.3\nscikit-learn==1.7.2\nnumpy==2.4.6\njoblib==1.5.2\n", encoding="utf-8"
)
```

<div dir="rtl">

حالا اولین `commit`:

</div>

```bash
cd price_project && git add price_tool/ requirements.txt && git commit -m "اولین نسخهٔ ابزار قیمت" && git log --oneline
```

<div dir="rtl">

</div>

```text-approx
[main (root-commit) 308c324] اولین نسخهٔ ابزار قیمت
 5 files changed, 87 insertions(+)
...
```

<div dir="rtl">

</div>

```text-approx
308c324 اولین نسخهٔ ابزار قیمت
```

<div dir="rtl">

آن هفت نویسه شناسهٔ این `commit` است و برای تو چیزِ دیگری درمی‌آید، چون به نام، تاریخ و محتوا بستگی دارد. پنج فایل همان چهار فایلِ پایتون به‌علاوهٔ `requirements.txt` است.


**پیامِ `commit` را جدی بگیر.** «تغییرات» و «update» و «fix» هیچ‌چیز نمی‌گویند. پیامِ خوب می‌گوید **چه چیزی و چرا**: «`alpha` را از ۱ به ۰٫۱ رساندم چون روی cross-validation بهتر بود». شش ماهِ دیگر، تنها کسی که این پیام را می‌خواند خودتی — و از خودت تشکر می‌کنی.

> ✅ **چک کن:** بعد از `commit`، دستورِ `git status` باید بگوید `nothing to commit, working tree clean`. اگر هنوز فایلی را «تغییریافته» نشان می‌دهد، یعنی `git add`ش نکرده بودی — **و `commit` بی‌صدا فقط چیزی را ثبت می‌کند که `add` شده باشد.**

## ۴. `.gitignore`: چه چیزی هرگز `commit` نمی‌شود

اینجا مهم‌ترین بخشِ ایمنیِ فصل است.

</div>

```text-file
# داده — بزرگ است و جایش git نیست
*.csv
*.parquet

# مدل‌های ذخیره‌شده — با هر آموزش دوباره ساخته می‌شوند
*.joblib
*.pkl

# راز — هرگز، تحت هیچ شرایطی
.env
*.key
secrets.json

# آشغال‌های پایتون
__pycache__/
*.pyc
.ipynb_checkpoints/
```

<div dir="rtl">

این متن را در فایلی به نامِ `.gitignore` در ریشهٔ `price_project` بگذار و `commit`ش کن. از همان لحظه `git status` چیزهایی را که با این الگوها می‌خوانند نشان نمی‌دهد. **ولی فایلی که قبلاً `commit` شده با این کار بیرون نمی‌رود**، و برای همین `.gitignore` را از روزِ اول می‌نویسند.

سه دلیلِ متفاوت، سه شدتِ متفاوت:

- **داده و مدل:** فنی. `git` برای فایلِ متنی ساخته شده؛ فایلِ دودوییِ بزرگ مخزن را برای همیشه سنگین می‌کند.
- **آشغال‌های ابزار:** بهداشتی. فقط شلوغی‌اند.
- **راز: امنیتی، و برگشت‌ناپذیر.**

> ⚠️ **مواظب باش:** اگر یک کلید را `commit` کنی و بعد پاکش کنی و دوباره `commit` کنی، **کلید هنوز در تاریخچه هست** — هر کسی که مخزن را داشته باشد می‌تواند بیرونش بکشد. و اگر مخزن عمومی باشد، ربات‌هایی که مدام GitHub را می‌گردند معمولاً در **چند دقیقه** پیدایش می‌کنند. **تنها کارِ درست، باطل کردنِ کلید و گرفتنِ کلیدِ تازه است** — نه پاک کردنش از کد. این همان درسِ ترمِ ۴ فصلِ ۳ است، فقط با پیامدِ سنگین‌تر.

## ۵. چرا نوت‌بوک در `git` بدرفتار است

فایلِ `.ipynb` در ظاهر یک نوت‌بوک است، ولی در واقع یک `JSON` بزرگ که **خروجی‌ها را هم داخلِ خودش دارد**. سه پیامد:

- **یک اجرای بی‌تغییر هم فایل را عوض می‌کند** — چون `execution_count` هر سلول بالا می‌رود. `git` می‌گوید «تغییر کرده» ولی هیچ کدی عوض نشده.
- **`diff` غیرقابلِ خواندن است.** به‌جای «این خط عوض شد»، صدها خط `JSON` می‌بینی.
- **خروجی‌ها بزرگ‌اند.** یک نمودار به‌صورتِ تصویرِ کدشده داخلِ فایل ذخیره می‌شود؛ ده نمودار یعنی چند مگابایت **در هر `commit`**.

راهِ حلِ ساده و مؤثر: **قبل از `commit`، خروجی‌ها را پاک کن.**

</div>

```bash
pip install -q nbstripout && cd price_project && nbstripout --install
```

<div dir="rtl">

`nbstripout` یک `filter` روی مخزن نصب می‌کند، یعنی برنامه‌ای که `git` هر بار قبل از ثبتِ فایل از آن رد می‌کند. از این به بعد هر `commit` نسخهٔ **بدونِ خروجیِ** نوت‌بوک را ثبت می‌کند، در حالی که نسخهٔ روی صفحهٔ خودت دست‌نخورده می‌ماند. این نصب فقط در همان پوشهٔ `.git` می‌ماند، پس در هر `clone` تازه دوباره لازمش داری.

**ایده همین است:** خروجی چیزی است که **تو** با اجرا می‌سازی، نه چیزی که در فایل نگه داری. هر کسی که نوت‌بوکت را بگیرد، با اجرای آن از بالا تا پایین همان خروجی‌ها را می‌سازد.

## ۶. `remote`: بردنش روی GitHub

</div>

```python
# build-notebooks: no-run
from google.colab import userdata

GITHUB_TOKEN = userdata.get("GITHUB_TOKEN")
GITHUB_USER = "your-username"
REPO = "price-tool"

remote_url = f"https://{GITHUB_USER}:{GITHUB_TOKEN}@github.com/{GITHUB_USER}/{REPO}.git"
print("آدرس ساخته شد، طولش:", len(remote_url))
```

<div dir="rtl">

</div>

```text-approx
آدرس ساخته شد، طولش: 118
```

<div dir="rtl">

در سلولِ بعد از **`subprocess`** استفاده می‌کنیم: کتابخانه‌ای که از داخلِ پایتون یک برنامهٔ بیرونی را اجرا می‌کند. `subprocess.run([...])` دستور را به‌صورتِ **فهرستی از رشته‌ها** می‌گیرد (نه یک متنِ یکپارچه — این‌طور فاصله و نویسهٔ خاص دردسر نمی‌سازد)، `cwd=` می‌گوید در کدام پوشه اجرایش کند، `text=True` خروجی را متن می‌دهد نه بایت، و `.returncode` همان کدِ خروجِ برنامه است: صفر یعنی موفق.

**توجه کن `GITHUB_TOKEN` از Colab Secrets آمد، نه از داخلِ کد** — همان قاعدهٔ ترمِ ۴ فصلِ ۳، و اینجا هم دقیقاً به همان دلیل: اگر نوت‌بوک را با کسی به اشتراک بگذاری، هر چیزی که در سلولی نوشته شده با آن می‌رود.

و **طولش را چاپ کردیم، نه خودش را.** این عادتِ کوچک بارها جلوی فاجعه را می‌گیرد: می‌خواهی مطمئن شوی متغیر پر شده، ولی نمی‌خواهی محتوایش روی صفحه بیاید و در خروجیِ نوت‌بوک ذخیره شود.

</div>

```python
# build-notebooks: no-run
import subprocess

subprocess.run(["git", "remote", "add", "origin", remote_url], cwd="price_project")
result = subprocess.run(
    ["git", "push", "-u", "origin", "main"],
    cwd="price_project", capture_output=True, text=True,
)
print("کد خروج:", result.returncode)
```

<div dir="rtl">

</div>

```text-approx
کد خروج: 0
```

<div dir="rtl">

`capture_output=True` عمدی است: **خروجیِ `git push` ممکن است بخشی از آدرس را چاپ کند، و آدرس توکن دارد.** با گرفتنِ خروجی و چاپِ فقط کدِ خروج، هیچ رازی روی صفحه نمی‌آید.

یک چیز را هم بدان: `git remote add` آن آدرس را با همان توکن در `.git/config` می‌نویسد. این فایل `commit` نمی‌شود، ولی `git remote -v` آن را چاپ می‌کند. با یک توکنِ جعلی ببین:

</div>

```text
origin	https://me:FAKE-TOKEN@example.com/me/price-tool.git (fetch)
origin	https://me:FAKE-TOKEN@example.com/me/price-tool.git (push)
```

<div dir="rtl">

پس این دستور را در نوت‌بوکی که خروجی‌اش را نگه می‌داری اجرا نکن، و پوشهٔ پروژه را با `.git`ش برای کسی نفرست.

> 🔧 **اگر کار نکرد:** چهار خطای رایج و علتشان. **`Authentication failed`**: توکن منقضی یا اشتباه است، یا دسترسیِ `repo` را ندارد. **`remote origin already exists`**: قبلاً اضافه‌اش کرده‌ای — با `git remote set-url origin ...` عوضش کن. **`src refspec main does not match any`**: هنوز هیچ `commit`ی نداری؛ اول `commit` کن. **`failed to push some refs`**: روی GitHub تغییری هست که نزدِ تو نیست — اول `git pull --rebase` بزن.

## ۷. چرخهٔ کامل

</div>

| کِی | چه کار |
|---|---|
| شروعِ هر جلسهٔ Colab | `git clone` و `git config` |
| بعد از هر تغییرِ معنادار | `git add` + `git commit -m "..."` |
| پایانِ کار | `git push` |
| قبل از شروعِ کارِ تازه | `git pull` |

<div dir="rtl">

**آن ردیفِ دوم را کوچک نگه دار.** یک `commit` که «کلِ کارِ امروز» است، وقتی خراب شد به هیچ دردت نمی‌خورد — چون نمی‌توانی بگویی کدام بخشش مقصر بوده. **`commit` کوچک، پیامِ روشن، و بعد از هر تغییری که تنهایی معنا دارد.**

> 🤖 **از دستیارت بپرس:** «فرق `git pull` با `git fetch` چیست و کِی کدام را باید زد؟» و بعد این: «اگر یک فایلِ حساس را اشتباهی `commit` کردم، دقیقاً چه باید بکنم؟» **جوابِ دومی را با بخشِ ۴ همین فصل بسنج** — اگر دستیارت فقط راهِ پاک کردن از تاریخچه را گفت و **باطل کردنِ کلید** را نگفت، جوابش ناقص است و همین ناقص بودن می‌تواند گران تمام شود.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| repository | ریپازیتوری | پوشهٔ پروژه + تاریخچه‌اش |
| commit | کامیت | یک عکسِ ثبت‌شده از پروژه، با پیام |
| remote | ریموت | نسخهٔ همان مخزن روی سرورِ دیگر |
| push / pull | پوش / پول | فرستادن به / گرفتن از `remote` |
| .gitignore | گیت‌ایگنور | فهرستِ چیزهایی که `git` نباید ردیابی کند |
| token | توکن | رمزِ دسترسی به‌جای گذرواژه |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا پاک کردنِ یک کلید از کد و `commit` دوباره، مشکل را حل نمی‌کند؟

**تمرینِ اجباری:** یک مخزن برای پروژهٔ فصلِ ۲ بساز، `.gitignore` بنویس، و سه `commit` جدا بزن — هر کدام برای یک تغییرِ مستقل. بعد `git log --oneline` بگیر و **پیام‌هایت را با معیارِ بخشِ ۳ نقد کن**: کدامشان به تو می‌گویند چه کاری شد و چرا؟

**تمرینِ ستاره‌دار ⭐:** یک نوت‌بوک با یک نمودار بساز، یک بار **با** خروجی و یک بار **بدونِ** خروجی `commit`ش کن، و اندازهٔ هر دو `commit` را مقایسه کن. بعد فکر کن: اگر تیمی روی یک نوت‌بوک کار کند و همه خروجی‌ها را `commit` کنند، بعد از صد `commit` چه اتفاقی می‌افتد؟ **این تمرین را واقعاً انجام بده** — عددی که می‌بینی از هر توضیحی قانع‌کننده‌تر است.

## در فصل بعد

کدت حالا نسخه‌بندی شده، ولی هیچ‌چیز نمی‌گوید که **درست** کار می‌کند. فصلِ بعد این را حل می‌کند: تست — و می‌بینی که در پروژهٔ داده، علاوه بر کد، **خودِ داده هم باید تست شود**.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t5/s03-git (یادستان, Yaadestan)
