سرنخ — خودآموز پایتون و برنامه‌نویسی برای هوش مصنوعی (مقدماتی)

فصل ۳ از ۸

پیشرفت ترم
۰٪

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

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

چند برگهٔ هم‌شکل که پشتِ سرِ هم روی یک ریلِ زمانی چیده شده‌اند و یکی از آن‌ها بیرون کشیده شده

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

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

قبل از شروع#

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

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

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

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

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

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

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

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

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

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

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

mkdir -p price_project && cd price_project && git init -b main && git status
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)

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

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

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

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

mkdir -p price_project/price_tool && cp price_tool/*.py price_project/price_tool/
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"
)

حالا اولین commit:

cd price_project && git add price_tool/ requirements.txt && git commit -m "اولین نسخهٔ ابزار قیمت" && git log --oneline
[main (root-commit) 308c324] اولین نسخهٔ ابزار قیمت
 5 files changed, 87 insertions(+)
...
308c324 اولین نسخهٔ ابزار قیمت

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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))
آدرس ساخته شد، طولش: 118

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

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

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

# 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)
کد خروج: 0

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

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

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

پس این دستور را در نوت‌بوکی که خروجی‌اش را نگه می‌داری اجرا نکن، و پوشهٔ پروژه را با .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 بزن.

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

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

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

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

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

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

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

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

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.