اولین مخزن شما، قدم به قدم

در این راهنما یک پروژهٔ کوچک را از صفر می‌سازیم. در طول راه، چهار مفهومی را یاد می‌گیرید که همهٔ zev بر آن‌ها بنا شده است: **پوشهٔ کاری**، **ناحیهٔ مرحله‌بندی**، **کامیت** و **تاریخچه**. اگر هنوز zev را نصب نکرده‌اید، از [نصب](/docs/fa/installation) شروع کنید. ## ساختن مخزن ```bash mkdir notes cd notes zev init ``` ```text Initialized empty Zev repository in ./.zev/ ``` *مخزن* (repository) پوشه‌ای است که zev تاریخچه‌اش را نگه می‌دارد. همهٔ این تاریخچه در پوشهٔ پنهان `.zev` است. آن را دستی ویرایش نکنید؛ اگر پاکش کنید، پوشه دوباره پوشه‌ای معمولی می‌شود و تاریخچه از بین می‌رود. نام و ایمیل‌تان را برای هر پروژه یک بار تنظیم کنید. این‌ها روی همهٔ کامیت‌هایتان می‌نشینند: ```bash zev config set user.name "سارا احمدی" zev config set user.email "sara@example.com" ``` ## سه جایی که کارتان در آن است خوب است این سه جا را در ذهن داشته باشید: | جا | چیست | چطور چیزی به آن می‌رسد | |---|---|---| | **پوشهٔ کاری** | فایل‌هایتان، همان‌طور که در ویرایشگر می‌بینید | خودتان ویرایششان می‌کنید | | **ناحیهٔ مرحله‌بندی** | تغییراتی که برای کامیت بعدی انتخاب کرده‌اید | `zev add` | | **تاریخچه** | همهٔ کامیت‌هایی که ساخته‌اید، برای همیشه ذخیره‌شده | `zev commit` | هیچ چیزی تصادفی به تاریخچه نمی‌رسد. خودتان انتخاب می‌کنید چه چیزی مرحله‌بندی شود و بعد آن را کامیت می‌کنید. ## اولین کامیت دو فایل بسازید: ```bash echo "خرید شیر" > todo.txt echo "ایده‌های پروژه" > ideas.txt ``` از zev بپرسید چه می‌بیند: ```bash zev status ``` ```text On branch main Untracked files: (zev add <file> to start tracking; list in .zevignore to hide) ideas.txt todo.txt ``` *Untracked* یعنی zev فایل‌ها را می‌بیند اما هنوز تاریخچه‌شان را نگه نمی‌دارد. هر دو را مرحله‌بندی و کامیت کنید: ```bash zev add . zev commit -m "شروع یادداشت‌ها" ``` ```text added ideas.txt added todo.txt Staged 2 change(s). Next: zev commit -m "what you changed" Created commit: 5f7f5e226bb19014179575681efba0f8be95eb6a8e64c1fc7dbc6f4d68224d01 Committed 2 file(s) ``` آن رشتهٔ طولانی **شناسهٔ** کامیت است: اثر انگشتی (هش) از همه‌چیزِ آن کامیت، که هرگز با کامیت دیگری اشتباه گرفته نمی‌شود. همیشه کافی است چند نویسهٔ اولش را بنویسید، مثلاً `5f7f5e22`. **پیام خوب کامیت** در چند کلمه می‌گوید چه چیزی و چرا تغییر کرد. «رفع ورود وقتی رمز فاصله دارد» بعدها خیلی مفیدتر از «رفع» است. ## دیدن تغییرات یک فایل را تغییر دهید و یکی تازه بسازید: ```bash echo "خرید نان" >> todo.txt echo "تماس با علی" > calls.txt zev status ``` ```text On branch main Changes not staged for commit: (zev add <file> to include them; zev restore <file> to throw them away) modified: todo.txt Untracked files: (zev add <file> to start tracking; list in .zevignore to hide) calls.txt ``` خط‌های تغییرکرده را ببینید: ```bash zev diff ``` ```text modified: todo.txt @@ -1,1 +1,2 @@ خرید شیر +خرید نان ``` `+` خطی است که اضافه شده و `-` خطی که حذف شده. خط `@@ -1,1 +1,2 @@` جای تغییر در فایل را نشان می‌دهد؛ اول کار می‌توانید نادیده‌اش بگیرید. حالا فقط `todo.txt` را کامیت کنید و `calls.txt` را برای بعد بگذارید: ```bash zev add todo.txt zev diff --staged zev commit -m "نان به فهرست اضافه شد" ``` `zev diff --staged` دقیقاً نشان می‌دهد کامیت بعدی چه چیزی خواهد داشت. عادت خوبی است که پیش از کامیت آن را ببینید. ## خواندن تاریخچه ```bash zev log ``` ```text commit 8a41c2d0… Author: سارا احمدی <sara@example.com> Date: 2026-10-04 09:25 UTC نان به فهرست اضافه شد commit 5f7f5e22… Author: سارا احمدی <sara@example.com> Date: 2026-10-04 09:20 UTC شروع یادداشت‌ها ``` تازه‌ترین کامیت بالاست. نمای کوتاه‌تر، هر کامیت در یک خط: ```bash zev log --oneline ``` برای دیدن یک کامیت و همهٔ تغییراتش: ```bash zev show 5f7f5e22 # با اول شناسه‌اش zev show HEAD # تازه‌ترین کامیت zev show HEAD~1 # کامیتِ پیش از آن ``` `HEAD` یعنی «کامیتی که الان روی آن هستید». `HEAD~1` یکی پیش از آن است، `HEAD~2` دو تا پیش‌تر، و همین‌طور. ## برگرداندن کارها همه اشتباه می‌کنند. راه خروج از اشتباه‌های رایج این‌هاست. **دور ریختن تغییراتی که مرحله‌بندی نکرده‌اید** (برگشت به نسخهٔ آخرین کامیت): ```bash zev restore todo.txt ``` مراقب باشید: تغییراتی که دور می‌ریزید برای همیشه می‌روند، چون هرگز کامیت نشده بودند. **خارج کردن فایل از مرحله‌بندی** (ویرایش‌ها می‌مانند، اما فایل در کامیت بعدی نمی‌رود): ```bash zev restore --staged todo.txt ``` **کنار گذاشتن موقت تغییرات** (مثلاً برای اینکه با پوشه‌ای تمیز چیز دیگری را ببینید): ```bash zev stash zev stash pop # برگرداندنشان ``` **برگرداندن فایلی که اشتباهی پاک کرده‌اید** (اگر قبلاً کامیت شده بود): ```bash zev restore calls.txt ``` موقعیت‌های بیشتر، مثل حذف و تغییر نام فایل، در [چطور…؟](/docs/fa/how-do-i) آمده‌اند. ## حذف یا تغییر نام فایل برای حذف یک فایل و ثبت آن در کامیت بعدی: ```bash zev rm ideas.txt zev commit -m "حذف ایده‌ها" ``` حذف فایل از هر راه دیگری هم درست است؛ بعد `zev add ideas.txt` (یا `zev add .`) حذف را مرحله‌بندی می‌کند. برای تغییر نام، فایل را عادی تغییر نام دهید و هر دو نام را مرحله‌بندی کنید: ```bash mv calls.txt phone.txt zev add calls.txt phone.txt zev commit -m "تغییر نام calls به phone" ``` ## بیرون نگه داشتن بعضی فایل‌ها خروجی ساخت، لاگ‌ها و رازها جایشان در تاریخچه نیست. آن‌ها را در فایلی به نام `.zevignore` در پوشهٔ اصلی پروژه فهرست کنید: ```text # .zevignore node_modules/ build/ *.log .env ``` فایل‌های نادیده‌گرفته‌شده در `zev status` نمی‌آیند و `zev add .` از آن‌ها می‌گذرد. خود `.zevignore` را کامیت کنید تا همهٔ کسانی که روی پروژه کار می‌کنند همان فایل‌ها را نادیده بگیرند. ## قدم بعدی - [شاخه‌ها و ادغام](/docs/fa/branches): ایده‌ها را امتحان کنید بی‌آنکه به کار اصلی دست بزنید. - [اشتراک کارتان روی Zaryn](/docs/fa/pushing-and-pulling): push، pull و clone. - [همهٔ دستورات](/docs/fa/commands): مرجع کامل.