Git and GitHub for Builders

Version workflows, scripts and prompts with Git, change them through branches and pull requests, and handle a leaked key in the right order.

بعد از این درس می‌توانی

  • تفاوت پوشه کاری، ناحیه آماده‌سازی و commit را توضیح دهد و پیش از هر commit آنچه واقعاً ثبت می‌شود را ببیند.
  • برای پروژه خودکارسازی فایل .gitignore بنویسد که راز، داده محلی و خروجی ساخت را بیرون نگه دارد.
  • تغییر را در شاخه جدا بسازد و با Pull Request و قاعده محافظت شاخه به شاخه اصلی برساند.
  • اگر کلیدی وارد تاریخچه شد، اول آن را باطل و عوض کند و بعد درباره پاک‌کردن تاریخچه تصمیم بگیرد.

چرا این درس مهم است

ورک‌فلوی پاسخ سفارش برگ سبز یک ماه بی‌دردسر کار می‌کرد. یک روز کسی «فقط یک گره» را عوض کرد و از فردا نیمی از پیام‌ها بی‌پاسخ ماند. هیچ‌کس نمی‌دانست نسخه سالم دقیقاً چه بود، چه چیزی و کی عوض شد، و چطور برگردند. هفته بعد، همکار دیگری برای «پشتیبان‌گیری» پوشه پروژه را با فایل .env در یک مخزن عمومی گذاشت و کلید سامانه سفارش‌ها چند ساعت عمومی بود.

Git این دو مشکل را حل می‌کند، به شرطی که درست به کار برود: هر تغییر یک نقطه ثبت قابل‌برگشت با توضیح دارد، تغییر پیش از رسیدن به نسخه اصلی دیده و بررسی می‌شود، و راز هیچ‌وقت وارد تاریخچه نمی‌شود. این درس پایه همه درس‌های بعدی این دوره است: Docker، سرور و پیکربندی همه از یک مخزن تمیز شروع می‌شوند.

مفاهیم کلیدی

  • Repository (مخزن): پوشه پروژه به‌همراه کل تاریخچه تغییراتش.
  • Commit (ثبت): عکسی از فایل‌های آماده‌شده با پیام، نویسنده و زمان که می‌شود به آن برگشت.
  • Staging Area (ناحیه آماده‌سازی): جایی که مشخص می‌کنی دقیقاً چه چیزی در commit بعدی برود.
  • Branch (شاخه): خط تغییر جدا که شاخه اصلی را تا زمان ادغام دست نمی‌زند.
  • Pull Request (درخواست ادغام): پیشنهاد ادغام یک شاخه که پیش از ادغام دیده، بحث و بررسی می‌شود.
  • Ignore Rules (قاعده‌های نادیده‌گیری): الگوهای فایل .gitignore که Git هرگز پیشنهاد ثبتشان را نمی‌دهد.

مدل ذهنی

Git را مثل دفتر حسابداری با برگه‌های شماره‌دار ببین. روی میزت کاغذهای در حال نوشتن هست (پوشه کاری). آنچه می‌خواهی ثبت شود را در سینی «آماده ثبت» می‌گذاری (ناحیه آماده‌سازی). وقتی برگه را در دفتر می‌چسبانی (commit)، شماره و تاریخ و امضا می‌خورد و دیگر عوض نمی‌شود؛ اصلاح یعنی برگه تازه، نه پاک‌کردن برگه قبلی. شاخه یک دفتر پیش‌نویس جداست که حسابرس (Pull Request) پیش از انتقال به دفتر اصلی بررسی‌اش می‌کند.

مسیر یک تغییر در Git: فایل‌ها در پوشه کاری تغییر می‌کنند؛ با git add به ناحیه آماده‌سازی می‌روند؛ با git commit در مخزن محلی ثبت می‌شوند؛ با git push به مخزن راه دور در شاخه جدا می‌رسند؛ با Pull Request و بازبینی در شاخه اصلی ادغام می‌شوند.

مسیر یک تغییر در Git

این تشبیه کجا غلط است؟ برگه چسبیده در دفتر کاغذی را می‌شود پاره کرد و تمام. ولی commit فقط در دفتر تو نیست: هر کسی که مخزن را clone کرده یک نسخه کامل از کل تاریخچه دارد. برای همین «پاک‌کردن» چیزی از تاریخچه، به‌خصوص راز، هرگز کامل نیست و ترتیب درست اقدام مهم است.

گام‌به‌گام

گام ۱: ببین چه چیزی واقعاً ثبت می‌شود

Git فایل‌ها را در چند حالت نگه می‌دارد: ردگیری‌نشده، تغییرکرده، آماده‌شده و ثبت‌شده. نکته‌ای که خیلی‌ها را غافلگیر می‌کند: git add نسخه فایل را همان لحظه آماده می‌کند؛ اگر بعد از آن فایل را تغییر دهی، باید دوباره add کنیsrc-git-book-recording. سه فرمان را پیش از هر commit عادت کن:

git status                 # چه چیزهایی تغییر کرده، آماده شده یا ردگیری نمی‌شوند
git diff                   # تغییرهای آماده‌نشده
git diff --staged          # دقیقاً همان چیزی که در commit بعدی می‌رود

git commit -a همه فایل‌های ردگیری‌شده تغییرکرده را خودش آماده می‌کند و ممکن است چیزی را که نمی‌خواستی وارد کندsrc-git-book-recording. در پروژه‌ای که فایل پیکربندی دارد، git add <فایل> مشخص و سپس git diff --staged امن‌تر است.

پیام commit را برای «خودت شش ماه بعد» بنویس: چه چیزی و چرا، نه «Update config». در مخزن تمرینی خواهی دید همین پیام مبهم چطور یک فایل راز را پنهان کرده است.

گام ۲: آنچه هرگز وارد مخزن نمی‌شود

.gitignore الگوها را می‌گیرد: / در ابتدا الگو را به همان پوشه محدود می‌کند، / در انتها فقط پوشه‌ها را می‌گیرد، ! الگو را برعکس می‌کند و ** پوشه‌های تودرتو راsrc-git-book-recording. یک نکته که در قالب پیوست هم آمده: توضیح باید در خط جدا با # شروع شود؛ متنی که پس از الگو در همان خط بیاید، جزو الگو حساب می‌شود.

در پروژه خودکارسازی این‌ها هرگز وارد مخزن نمی‌شوند:

چه چیزینمونهچرا
راز و پیکربندی محلی.env، کلید .pemدسترسی به سرویس‌ها
خروجی رمزگشایی‌شدهفایل export:credentials --decrypted در n8nخود n8n هشدار می‌دهد همه اطلاعات حساس در آن دیده می‌شودsrc-n8n-cli
داده و پایگاه داده محلی*.sqlite، پوشه .n8nداده مشتری و کلید رمزنگاری n8n
وابستگی و خروجی ساختnode_modules، distدوباره ساخته می‌شوند

به‌جای .env واقعی، فایل .env.example با نام متغیرها و مقدار ساختگی ثبت کن تا دیگران بدانند چه چیزی لازم است. این را در درس پیکربندی کامل می‌کنی.

گام ۳: شاخه و Pull Request

شاخه در Git فقط یک اشاره‌گر سبک به یک commit است و ساختنش تقریباً هزینه‌ای نداردsrc-git-book-branches؛ پس برای هر تغییر یک شاخه بساز:

git switch -c feature/timeout       # شاخه تازه و رفتن به آن
# ... تغییر، add، commit ...
git push -u origin feature/timeout

سپس Pull Request باز کن. Pull Request پیشنهاد ادغام است که پیش از ادغام دیده و بحث می‌شود؛ اگر کارت هنوز تمام نیست، آن را پیش‌نویس (draft) باز کن، چون پیش‌نویس قابل ادغام نیستsrc-github-pull-requests. قالب assets/pr-template.md سه پرسش را اجباری می‌کند: چطور آزمودی، راز یا داده واقعی هست یا نه، و اگر خراب شد چطور برمی‌گردی.

برای شاخه اصلی قاعده محافظت بگذار: ادغام فقط با Pull Request و تأیید، و بررسی‌های خودکار پیش از ادغام. در GitHub، force push و حذف شاخه محافظت‌شده به‌طور پیش‌فرض بسته است؛ این قابلیت برای مخزن عمومی در طرح رایگان هست، ولی برای مخزن خصوصی طرح پولی لازم داردsrc-github-protected-branches. اگر تنها کار می‌کنی، باز هم Pull Request به خودت ارزش دارد: یک بار دیگر کل تغییر را می‌بینی.

گام ۴: اگر کلیدی وارد تاریخچه شد

ترتیب درست این است و جابه‌جا کردنش خطرناک است:

  1. اول کلید را باطل و عوض کن. مستندات GitHub صریح است: اگر داده‌ای که ثبت شده راز است، باید آن را باطل یا عوض کنی، و این کار ممکن است به‌تنهایی کافی باشدsrc-github-remove-sensitive-data.
  2. ببین کجاها رفته: کدام commit، کدام شاخه، آیا push شده، آیا مخزن عمومی است.
  3. جلوی تکرار را بگیر: .gitignore، و در GitHub قابلیت push protection که پیش از رسیدن راز به مخزن push را می‌بندد. برای حساب کاربری، این محافظت هنگام push به مخزن عمومی به‌طور پیش‌فرض روشن است، ولی محافظت در سطح مخزن پیش‌فرض خاموش استsrc-github-push-protection.
  4. فقط بعد، درباره بازنویسی تاریخچه تصمیم بگیر. ابزار git-filter-repo این کار را می‌کند، ولی شناسه commitها عوض می‌شود، هماهنگی با همکاران لازم است، و داده از clone دیگران و forkها پاک نمی‌شودsrc-github-remove-sensitive-data.

حذف فایل در commit بعدی (کاری که در مخزن تمرینی شده) هیچ چیزی را از تاریخچه پاک نمی‌کند. این را با یک فرمان می‌بینی:

git log --all -p -G 'TOKEN=' -- .env

مثال‌ها

پیاده‌سازی عملی

مخزن تمرینی، فایل `.gitignore`، شاخه و بررسی تاریخچه. حدود ۲۲ دقیقه.

  1. یکی از مسیرهای پایین را برو.
  2. در مخزن، قالب assets/gitignore-automation.txt را به نام .gitignore کپی کن و با git check-ignore -v .env ببین .env واقعاً نادیده گرفته می‌شود. سپس .gitignore را commit کن.
  3. در شاخه feature/timeout تغییر را با git diff main feature/timeout ببین و آن را با پیام روشن ادغام کن: git switch main و git merge feature/timeout.
  4. برای توکن ساختگی در تاریخچه، چهار گام بالا را به ترتیب برای این مخزن بنویس (کدام را انجام دادی، کدام لازم نیست و چرا).
اجرای محلی

با Git روی کامپیوتر خودت (در ویندوز در Git Bash): bash make-practice-repo.sh را اجرا کن (فایل assets/make-practice-repo.sh). اسکریپت پوشه barg-sabz-automation را با چهار commit، یک شاخه و یک .env ثبت‌شده در تاریخچه می‌سازد و هیچ چیزی به اینترنت نمی‌فرستد. اگر به یک سرویس میزبانی Git (GitHub، GitLab یا Gitea) دسترسی قانونی داری، یک مخزن خصوصی بساز، شاخه را push کن و Pull Request را با قالب پیوست باز کن؛ ولی پیش از push، گام ۴ را تمام کن.

بدون اجرا / شبیه‌ساز

بدون نصب Git: assets/git-session.txt را بخوان؛ خروجی واقعی همان اسکریپت و فرمان‌های درس است. از روی آن بنویس: (۱) کدام commit فایل .env را اضافه کرد؛ (۲) چرا commit «Remove env file» آن را از تاریخچه پاک نکرد؛ (۳) تغییر شاخه feature/timeout دقیقاً چه بود؛ (۴) چرا git check-ignore گفته «not ignored».

اشتباه‌های رایج

اشتباهنتیجهکار درست
git add . بدون دیدنفایل راز یا داده وارد commit می‌شودgit status و git diff --staged پیش از commit
حذف راز در commit بعدیراز در تاریخچه می‌مانداول باطل و عوض کردن کلید
کار مستقیم روی شاخه اصلیتغییر بررسی‌نشده به نسخه سالم می‌رسدشاخه و Pull Request
پیام‌های «Update» و «fix»تاریخچه بی‌فایده هنگام خرابیچه چیزی و چرا در پیام
توضیح در همان خط الگوی .gitignoreالگو کار نمی‌کندتوضیح در خط جدا
ثبت پوشه .n8n یا فایل SQLiteداده و کلید رمزنگاری در مخزن.gitignore و نسخه‌بندی فقط فایل‌های ورک‌فلو

اشکال‌زدایی

با اینکه .env را به .gitignore اضافه کرده‌ای، git status آن را «modified» نشان می‌دهد.

فایل پیش‌تر ثبت شده و ردگیری می‌شود؛ .gitignore فقط روی فایل‌های ردگیری‌نشده اثر دارد.

git ls-files .env اگر نام فایل را برگرداند، ردگیری می‌شود.

git rm --cached .env و commit؛ و چون پیش‌تر ثبت شده، کلیدهای داخلش را باطل و عوض کن.

push با پیامی درباره شناسایی راز رد می‌شود.

push protection سرویس، یک الگوی راز را در commitها پیدا کرده استsrc-github-push-protection.

پیام خطا نام فایل و commit را می‌گوید؛ با git log -p آن را ببین.

راز را از commit بیرون بیاور (پیش از push، ساده است)، کلید را اگر واقعی بوده عوض کن، و فقط اگر واقعاً مثبت کاذب است، دور زدن را با دلیل ثبت کن.

پس از merge، ورک‌فلوی سالم دیروز خراب است و نمی‌دانی کدام تغییر.

چند تغییر در یک commit با پیام مبهم ادغام شده‌اند.

git log --oneline و git diff <commit-سالم> HEAD -- workflows/

برگرداندن با git revert <commit> (تاریخچه را بازنویسی نمی‌کند) و از این به بعد یک تغییر در هر commit.

نکته‌های امنیتی

تمرین کوتاه

تمرین · 12 دقیقه

هدف: تصمیم درست برای چهار موقعیت.

گام‌ها: برای هرکدام فرمان یا اقدام بعدی را بنویس: (۱) git status نشان می‌دهد credentials-backup.json ردگیری‌نشده است؛ (۲) کلید مدل را دیروز commit کرده‌ای ولی push نکرده‌ای؛ (۳) همان کلید یک ساعت در مخزن عمومی بوده؛ (۴) همکار می‌خواهد مستقیم روی main کار کند «چون تغییر کوچک است».

معیار پذیرش: ۱ با .gitignore؛ ۲ و ۳ با عوض کردن کلید اول؛ ۳ با پذیرش اینکه پاک‌کردن تاریخچه کامل نیست؛ ۴ با شاخه و Pull Request.

راه‌حل نمونه

(۱) آن را commit نکن؛ الگو را به .gitignore اضافه کن و فایل را از پوشه مخزن بیرون ببر. (۲) کلید را عوض کن (احتیاط کم‌هزینه)، سپس چون push نشده، commit را اصلاح کن (git reset --soft HEAD~1 یا git commit --amend پس از حذف) تا اصلاً منتشر نشود. (۳) فوراً کلید را باطل و عوض کن؛ مصرف آن ساعت را در داشبورد سرویس بررسی کن؛ بعد درباره بازنویسی تاریخچه تصمیم بگیر و بدان clone و fork دیگران آن را دارند. (۴) شاخه و Pull Request؛ تغییر کوچک هم می‌تواند ورک‌فلو را بشکند و Pull Request کوچک زود بررسی می‌شود.

چالش

تمرین · 30 دقیقه

موقعیت: یکی از پروژه‌های خودکارسازی خودت (ورک‌فلو، اسکریپت یا مجموعه پرامپت) را زیر Git ببر. اگر فایل‌ها داده واقعی دارند، نسخه ساختگی یا ناشناس‌شده بساز.

  1. .gitignore مخصوص پروژه‌ات را از قالب بساز و با git check-ignore -v آزمون کن.
  2. .env.example با نام متغیرها و مقدار ساختگی بساز.
  3. پیش از اولین commit، تاریخچه یا پوشه را برای الگوهای راز (TOKEN=، KEY=، password) بگرد و نتیجه را بنویس.
  4. یک تغییر را در شاخه بساز و با قالب Pull Request توضیحش را بنویس (اگر سرویس میزبانی نداری، توضیح را در فایل بنویس و git diff را پیوست کن).

خروجی مورد انتظار: فهرست فایل‌های ثبت‌شده، .gitignore، .env.example، نتیجه جست‌وجوی راز و توضیح Pull Request.

معیار پذیرش:

  • هیچ راز، داده واقعی یا فایل پایگاه داده در commitها نیست.
  • .gitignore آزموده شده است.
  • تغییر از شاخه جدا با توضیح «چطور آزمودم» و «چطور برمی‌گردیم» آمده است.

پرسش‌های سنجش

جمع‌بندی

  • پیش از هر commit: git status و git diff --staged؛ add نسخه همان لحظه را آماده می‌کند.
  • راز، داده محلی، پوشه .n8n و خروجی رمزگشایی‌شده هرگز وارد مخزن نمی‌شوند؛ .env.example جایش.
  • هر تغییر در شاخه جدا و با Pull Request؛ شاخه اصلی محافظت‌شده.
  • حذف فایل در commit بعدی، تاریخچه را پاک نمی‌کند.
  • کلید لورفته: اول باطل و عوض، بعد جلوگیری از تکرار، و فقط بعد بازنویسی تاریخچه.
  • ورک‌فلوهای n8n را صادر کن و مثل کد نسخه‌بندی کن.

پرسش‌های سنجش

فایل workflow.json را ویرایش کردی، git add زدی، سپس یک خط دیگر هم در همان فایل عوض کردی و git commit -m زدی. کدام نسخه فایل ثبت شده است و پیش از commit با کدام فرمان می‌توانستی دقیقاً همین را ببینی؟

پاسخ نمونه و معیار ارزیابی

نسخه‌ای که در لحظه git add بود؛ ویرایش دوم آماده نشده و ثبت نشده است (git status آن را modified نشان می‌دهد). git diff --staged دقیقاً همان چیزی را نشان می‌دهد که در commit بعدی می‌رود و git diff تغییر آماده‌نشده را.

  • نسخه لحظه add ثبت شده (1 امتیاز)
  • git diff --staged برای دیدن آنچه ثبت می‌شود (1 امتیاز)
  • آخرین نسخه فایل ← commit فقط ناحیه آماده‌سازی را ثبت می‌کند؛ ویرایش پس از add باید دوباره add شود.

همکار می‌گوید «مشکلی نیست، .env را در commit بعدی حذف کرده‌ام». چه چیزی اشتباه است و چهار اقدام را به ترتیب بنویس.

خروجی یک همکار:

$ git log --oneline -- .env
4c1e2aa Remove .env
91b07fd Add config
$ git push origin main
... pushed to public repository 3 hours ago
پاسخ نمونه و معیار ارزیابی

فایل و محتوایش در commit 91b07fd در تاریخچه مانده و سه ساعت در مخزن عمومی بوده است؛ حذف در commit بعدی چیزی را پاک نمی‌کند. ترتیب: (۱) همه کلیدهای داخل .env را فوراً باطل و عوض کن و مصرف آن بازه را بررسی کن؛ (۲) ببین کجا رفته (شاخه‌ها، forkها)؛ (۳) .env را به .gitignore اضافه کن و push protection را روشن کن؛ (۴) سپس درباره بازنویسی تاریخچه با git-filter-repo و هماهنگی با همکاران تصمیم بگیر، با دانستن اینکه clone و fork دیگران را پاک نمی‌کند.

  • راز در تاریخچه و عمومی بوده (1 امتیاز)
  • عوض‌کردن کلید اول (1 امتیاز)
  • جلوگیری از تکرار (1 امتیاز)
  • بازنویسی تاریخچه در آخر و محدودیتش (1 امتیاز)
  • اول تاریخچه را پاک کن ← تا وقتی کلید معتبر است، هر نسخه‌ای که کسی برداشته قابل استفاده است.

برای پروژه‌ای با n8n محلی (پوشه .n8n)، یک اسکریپت Python با .venv، فایل .env، پوشه backups و فایل‌های ورک‌فلوی صادرشده در workflows/، یک .gitignore کوتاه بنویس. کدام پوشه باید حتماً در مخزن بماند؟

پاسخ نمونه و معیار ارزیابی

نمونه: سطرهای .env، .env.* و !.env.example؛ .n8n/؛ backups/؛ .venv/؛ __pycache__/؛ *.sqlite. پوشه workflows/ (فایل‌های ورک‌فلوی صادرشده که فقط نام Credential دارند) باید در مخزن بماند، و همین‌طور .env.example. توضیح‌ها در خط جدا.

  • .env و .n8n و backups بیرون (1 امتیاز)
  • .env.example و workflows داخل (1 امتیاز)
  • workflows را هم نادیده بگیر ← فایل ورک‌فلو راز ندارد و همان چیزی است که می‌خواهی نسخه‌اش را داشته باشی.

می‌خواهی هیچ تغییری بدون بررسی به شاخه main مخزن تیم نرسد. کدام کار این را تضمین می‌کند؟

  • به همه بگویی همیشه شاخه بسازند.
  • قاعده محافظت شاخه برای main با الزام Pull Request و تأیید.
  • قالب Pull Request در مخزن.
  • حذف دسترسی push همه به جز خودت.
پاسخ نمونه و معیار ارزیابی
  • a ← قرارداد شفاهی را یک روز شلوغ کسی فراموش می‌کند.
  • c ← قالب، توضیح را بهتر می‌کند ولی جلوی push مستقیم را نمی‌گیرد.
  • d ← خودت هم بی‌بررسی می‌مانی و کار تیمی گلوگاه می‌شود.

تنها کار می‌کنی و ورک‌فلوهای n8n برگ سبز را نگه می‌داری. موازنه «commit مستقیم روی main» با «شاخه و Pull Request به خودت» را بنویس و تصمیم بگیر.

پاسخ نمونه و معیار ارزیابی

commit مستقیم سریع‌تر است و سربار ندارد؛ ولی هیچ لحظه‌ای برای دیدن کل تغییر پیش از رسیدن به نسخه سالم نیست و برگرداندن یک تغییر از میان چند تغییر سخت‌تر است. Pull Request به خودت چند دقیقه هزینه دارد، ولی diff کامل را یک بار دیگر می‌بینی، توضیح آزمون و برگشت ثبت می‌شود و بررسی خودکار پیش از ادغام اجرا می‌شود. تصمیم: برای ورک‌فلوی در حال کار، شاخه و Pull Request؛ برای یادداشت و مستند کم‌ریسک، commit مستقیم قابل قبول است.

  • هزینه و فایده هر دو (1 امتیاز)
  • تصمیم بر اساس ریسک تغییر (1 امتیاز)
  • تنها که هستم، لازم نیست ← بازبینی برای خودت هم ارزش دارد: خطا را پیش از رسیدن به نسخه سالم می‌بینی.

فایل‌های درس

ساخت مخزن تمرینی برگ سبز با یک .env ثبت‌شده در تاریخچه

make-practice-repo.sh

خروجی واقعی اجرای اسکریپت و فرمان‌های درس

git-session.txt

قالب .gitignore برای پروژه‌های خودکارسازی، n8n و ایجنت

gitignore-automation.txt

قالب توضیح Pull Request با بررسی راز و برگشت

pr-template.md

ابزارها و جایگزین‌ها

  • Git 2.30 یا بالاتر — نسخه‌بندی محلی — مسیر بدون نصب با خروجی نمونه

منابع

Pro Git: Recording Changes to the Repository Git (git-scm.com) Pro Git 2nd ed., online 2026-10

Use the command line (CLI commands) n8n n8n docs, 2026-10

Pro Git: Branches in a Nutshell Git (git-scm.com) Pro Git 2nd ed., online 2026-10

About pull requests GitHub Docs GitHub Docs, 2026-10

About protected branches GitHub Docs GitHub Docs, 2026-10

Removing sensitive data from a repository GitHub Docs GitHub Docs, 2026-10

About push protection GitHub Docs GitHub Docs, 2026-10

Course

Infrastructure Basics for Builders