قابلیت نیمه‌کاره است؛ اصلاح فوری منتظر نمی‌ماندThe feature is unfinished; the hotfix cannot wait

روی feature/search در دو فایل کار کرده‌ای؛ یکی را هم ناحیه‌ آماده‌سازی کرده‌ای. هم‌تیمی می‌گوید باگ پرداخت در نسخهٔ انتشار باید همین حالا رفع شود. اگر شاخه عوض کنی چه می‌شود؟ اگر commit عجولانه بسازی، آیا واقعاً آمادهٔ تاریخچهٔ محصول است؟

You have edited two files on feature/search, staging one. A teammate reports that a payment bug in the release must be fixed now. What happens if you switch branches? If you make a hurried commit, is it ready for product history?

فصل‌های ۳ و ۵ سه ناحیه و شاخه را جدا کردند؛ فصل ۶ نشان داد merge چه‌طور دو خط تاریخچه را نگه می‌دارد؛ فصل ۱۰ هم ردّ اشاره‌گرها را دنبال کرد. اینجا سه نیاز جدا داریم: کار نیمه‌تمام را موقت نگه داریم، تغییر انتخابی را روی شاخهٔ دیگر بسازیم و نسخهٔ آزموده‌شده را نام‌گذاری کنیم.

Chapters 03 and 05 separated the three areas and branches; Chapter 06 showed how merge preserves history lines; Chapter 10 followed ref movements. Now we have three distinct needs: preserve unfinished work temporarily, apply one selected change on another branch, and name a tested release.

اول کار نیمه‌تمام را کنار بگذارFirst, set unfinished work aside

در مخزن تمرینی جدا، یک فایل ردیابی‌شده را تغییر بده و فایلی را ناحیه‌ آماده‌سازی کن. قبل از اجرا حدس بزن: بعد از stash پوشه و ناحیه‌ آماده‌سازی چه وضعی دارند؟

In a separate practice repository, edit a tracked file and stage another. Predict before running: what happens to the worktree and index?

git status --short
git stash push -m "pause search for payment hotfix"
git status --short
git stash list

فرمان اول تغییرها را نشان می‌دهد. پس از stash push معمولاً پوشه و ناحیه‌ آماده‌سازی به وضعیت HEAD برمی‌گردند؛ stash list پیام رد تازه را نشان می‌دهد. این ثبت محلی است، نه commit روی شاخه و نه چیزی که همکار خودکار دریافت کند.

The first command shows the edits. After stash push, the worktree and index normally return to HEAD; stash list shows the new entry. This is local storage, not a branch commit or something a teammate automatically receives.

قبل از برگرداندن، داخل stash را ببینInspect before restoring

پس از چند وقفه، stash@{0} لزوماً کار همین قابلیت نیست. فهرست و patch را بخوان؛ اسم رد محتوایش را ثابت نمی‌کند.

After several interruptions, stash@{0} may not belong to this feature. Read the list and patch; the entry name does not prove its contents.

git stash list
git stash show --stat "stash@{0}"
git stash show -p "stash@{0}"

list ترتیب و پیام‌ها را نشان می‌دهد؛ show --stat فایل‌های درگیر و -p خود diff را می‌دهد. خروجی را با کاری که یادت هست بسنج. دیدن patch ثابت نمی‌کند روی شاخهٔ تازه بی‌تعارض اعمال می‌شود.

list shows order and messages; show --stat summarizes paths, while -p displays the diff. Compare it with what you remember. Seeing the patch does not prove it will apply cleanly on a new branch.

ردیابی‌نشده را جداگانه انتخاب کنInclude untracked files explicitly

فایل تازه‌ای مثل draft-plan.md ساخته‌ای، اما add نکرده‌ای. stash معمولی آن را نمی‌گیرد؛ -u فایل‌های ردیابی‌نشده را هم می‌گیرد، اما ignoredها نه. -a ignored را هم شامل می‌کند و می‌تواند فایل‌های تولیدی یا محلی را از پوشه بردارد؛ بی‌دلیل سراغش نرو.

You created draft-plan.md but did not add it. A normal stash excludes it; -u includes untracked files but not ignored ones. -a also includes ignored files and may remove generated or local data from the worktree; do not use it casually.

git status --short
git stash push -u -m "include new draft"
git stash show -p -u "stash@{0}"

پس از اجرای فرمان، status و show -p -u را بخوان. یک فایل نبودنش دلیل نیست که حتماً در stash است؛ patch باید خود محتوای مورد انتظار را نشان دهد.

After running the command, inspect status and show -p -u. A missing file is not proof that it is in the stash; the patch must show the expected content.

apply نگه می‌دارد؛ pop بعد از موفقیت حذف می‌کندapply keeps it; successful pop removes it

هر دو تغییر را برمی‌گردانند؛ تفاوت در عمر رد است. apply آن را نگه می‌دارد تا بررسی کنی. pop فقط بعد از اعمال موفق حذفش می‌کند. اگر تعارض پیش بیاید، رد معمولاً می‌ماند.

Both restore the changes; the difference is the entry's lifetime. Apply keeps it for inspection. Pop removes it only after successful application. If a conflict occurs, the entry normally remains.

در تعارض، وضعیت را بخوان، فایل‌ها و ناحیه‌ آماده‌سازی را حل کن، ناحیه‌ آماده‌سازی و تست بگیر؛ بعد از اثبات نتیجه رد را drop کن. اگر می‌خواهی فایل‌هایی که قبل از stash ناحیه‌ آماده‌سازی بودند دوباره آماده‌شده شوند، apply --index را امتحان کن؛ بازسازی ناحیه‌ آماده‌سازی هم ممکن است با تعارض روبه‌رو شود. stash مدیریت وقفه است، نه پشتیبان بلندمدت. برای کاری که باید بماند commit یا شاخه بساز.

On conflict, inspect status, resolve files and index, stage and test; drop only after proving the result. If you want paths that were staged before stashing to become staged again, try apply --index; restoring the index can also conflict. A stash manages an interruption, not long-term backup. Create a commit or branch for work that must persist.

stash کلیپ‌بورد جادویی نیستA stash is not a magical clipboard

فصل ۲ نشان داد Git محتوا را در شیءهایی مثل blob، tree و commit نگه می‌دارد. stash هم با commitهای مخصوص وضعیت پوشه و ناحیه‌ آماده‌سازی را ثبت می‌کند و اشاره‌گر محلی refs/stash به تازه‌ترین رد می‌رسد؛ reflog همان اشاره‌گر ردهای قبلی را قابل‌نام‌بردن می‌کند.

Chapter 02 showed Git storing content in objects such as blobs, trees, and commits. A stash is represented by special commits recording worktree and index states; the local ref refs/stash points to the newest entry, and its reflog makes earlier entries addressable.

این ساختار توضیح می‌دهد چرا می‌توانی stash را diff کنی؛ اما نکتهٔ روزمره این است: محلی است، شاخه نیست، به مخزن راه دور نمی‌رود و بعد از حذف/پاک‌سازی ممکن است بازیابی نشود.

This structure explains why a stash can be diffed. The practical point is that it is local, not a branch, not sent to a remote, and may be unrecoverable after deletion and pruning.

اصلاح فوری آماده است؛ فقط همان تغییر را به نسخه‌ انتشار بیاورThe hotfix is ready; bring only that change to release

هم‌تیمی روی hotfix/payment-timeout تغییری ساخته و آزموده؛ شاخهٔ جست‌وجو هنوز نیمه‌کاره است. merge رابطهٔ دو شاخه را وصل می‌کند، اما امروز فقط یک commit مشخص باید روی release/2.4 هم باشد.

A teammate has made and tested a change on hotfix/payment-timeout, while search is unfinished. Merge connects branch histories, but today one known commit must also appear on release/2.4.

اگر commit هنوز در clone نیست، fetch کن؛ رهگیریِ مخزن راه دور شاخه فقط آخرین وضعیت fetchشده است. اینجا شناسه‌ شیء محلی داریم. قبل از اجرا، مقصد و patch را ثابت کن:

If the commit is not in your clone, fetch; a remote-tracking branch is only the last fetched state. Here the OID is local. Prove the target and patch first:

git status --short --branch
git show --stat --oneline HOTFIX_OID
git switch release/2.4
git status --short --branch
git cherry-pick HOTFIX_OID
git show --stat --oneline HEAD

HOTFIX_OID را با شناسهٔ واقعی عوض کن. show می‌گوید چه patchی را انتخاب کرده‌ای؛ cherry-pick آن را روی والد جاری بازمی‌سازد. معمولاً commit تازه شناسه‌ شیء تازه دارد چون والد یا فراداده فرق می‌کند؛ commit اصلی سر شاخهٔ اصلاح فوری می‌ماند.

Replace HOTFIX_OID with the real ID. show identifies the selected patch; cherry-pick reconstructs it on the current parent. The new commit normally has a new OID because its parent or metadata differs; the source remains on hotfix.

merge رابطه را می‌آورد؛ cherry-pick تغییر راmerge brings the relationship; cherry-pick brings the change

اگر کل خط کار و رابطهٔ والدها آن باید وارد نسخه‌ انتشار شود، merge را بررسی کن. اگر فقط patch مشخصی لازم است و شاخهٔ مبدا نباید یک‌جا ادغام شود، cherry-pick محدودتر است. انتخاب را بر اساس تاریخی بکن که تیم بعداً باید بخواند.

If the whole line of work and its ancestry should enter release, consider merge. If only one patch is needed and the source branch should not be integrated wholesale, cherry-pick is narrower. Choose based on the history your team needs to read.

تعارض آمد؟ اول وضعیت را بخوانConflict? Read the state first

اگر cherry-pick با تعارض متوقف شد، کورکورانه تکرارش نکن. وضعیت فایل‌های حل‌نشده را نشان می‌دهد؛ بعد انتخاب کن تغییر را نگه داری یا عملیات را لغو کنی.

If cherry-pick stops with a conflict, do not repeat it blindly. Status identifies unresolved files; then decide whether to keep the change or cancel.

git status
# resolve intentionally
git add path/to/resolved-file
git cherry-pick --continue

# alternatively, cancel the operation
git cherry-pick --abort

بعد از حل و ناحیه‌ آماده‌سازی، --continue commit را می‌سازد؛ --abort به قبل از عملیات جاری برمی‌گردد. با درخت تمیز شروع کن تا تغییرهای نامرتبط درگیر نشوند. اگر patch خالی یا تکراری شد، log و diff را بسنج؛ شاید تغییر پیش‌تر آمده یا مقصد اشتباه است. commit خالی را فقط برای خاموش‌کردن خطا نساز.

After resolving and staging, --continue creates the commit; --abort returns to the pre-operation state. Start with a clean worktree so unrelated edits are not involved. If the patch is empty or redundant, inspect log and diff; it may already exist or the target may be wrong. Do not create an empty commit just to silence an error.

نسخهٔ آزموده‌شده را با tag نام‌گذاری کنName the tested release with a tag

شاخه خط کاری‌ای است که حرکت می‌کند؛ tag نامی است که روی نقطه‌ای از تاریخچه می‌گذاری تا نسخه یا رویدادی را مشخص کنی. فصل ۲ ساختارش را معرفی کرد: tag سبک اشاره‌گر مستقیم به شیء است؛ tag نشانه‌دار شیء جدا با پیام، زمان و tagger می‌سازد. برای نسخه‌ انتشار معمولاً tag نشانه‌دار مناسب‌تر است.

A branch is a moving line of work; a tag names a point in history as a release or event. Chapter 02 introduced the structure: a lightweight tag is a ref directly to an object; an annotated tag creates a separate object with message, date, and tagger. Annotated tags are usually more useful for releases.

قبل از انتشار، مقصد tag را ثابت کنVerify the tag target before publishing

tag روی commit اشتباه نسخهٔ درست نمی‌سازد. شاخه، تست و commit جاری را بررسی کن؛ سپس tag بساز و با show مقصدش را بخوان.

A tag on the wrong commit does not make a correct release. Verify branch, tests, and current commit; create the tag, then inspect its target with show.

git status --short --branch
git log -1 --oneline
git tag -a v2.4.1 -m "Release 2.4.1: payment timeout fix"
git show --no-patch --decorate v2.4.1
git push origin release/2.4
git push origin v2.4.1
git ls-remote --tags origin

show پیام و مقصد commit را نشان می‌دهد. اگر نام از قبل هست، توقف کن و مقصد محلی و مخزن راه دور را بررسی کن؛ tag منتشرشده ممکن است مبنای ساخت دیگران باشد. push شاخه تضمین نمی‌کند tag هم رفته؛ tag مشخص را جدا push کن. push --tags همهٔ tagهای محلی، حتی آزمایشی/خصوصی را می‌فرستد؛ فرمان پیش‌فرض انتشارش نکن.

show displays message and target. If the name exists, stop and inspect local and remote targets; a published tag may anchor other builds. Pushing a branch does not guarantee its tag was sent; push the exact tag separately. push --tags sends all local tags, including experimental or private ones; do not make it the default.

Git اجازهٔ جابه‌جایی tag محلی یا حذف مخزن راه دور را می‌دهد، اما نسخه‌گذاری قرارداد تیمی است. برای tag منتشرشدهٔ اشتباه با مصرف‌کنندگان هماهنگ کن؛ نام تازه معمولاً از عوض‌کردن معنای نام عمومی کم‌خطرتر است. امضای کوتاه: tag -s با کلید تنظیم‌شده امضا می‌کند و tag -v آن را می‌سنجد؛ اعتماد به هویت امضاکننده هم لازم است.

Git permits moving a local tag or deleting one remotely, but release naming is a team contract. Coordinate if a published tag is wrong; a new name is often safer than changing a public name's meaning. Briefly: tag -s signs with a configured key, and tag -v verifies it; trust in the signer's identity still matters.

پروژهٔ کوچک: وقفه، اصلاح فوری، انتشارMini-project: interruption, hotfix, release

mkdir interrupt-release-lab && cd interrupt-release-lab
git init -q
git config user.name "Git Learner"
git config user.email learner@example.test
printf 'timeout=30\nsearch=off\n' > app.conf
git add app.conf && git commit -m "Create release baseline"
git branch -M main
git switch -c release/2.4
git switch -c hotfix/payment-timeout
printf 'timeout=10\nsearch=off\n' > app.conf
git commit -am "Reduce payment timeout"
git switch release/2.4
git switch -c feature/search
printf 'timeout=30\nsearch=partial\n' > app.conf
git add app.conf
printf 'unfinished parser\n' > search-draft.txt

تمرین‌ها: انتخاب درست، نه حفظ فرمانExercises: choose well, do not memorise

برای هر سؤال فقط بپرس «چه چیزی را می‌خواهم جابه‌جا کنم؟» کار ثبت‌نشده، تغییر داخل یک commit و نام یک نسخه سه جنس متفاوت‌اند. stash، cherry-pick و tag هم به همین دلیل سه ابزار جدا هستند؛ اگر مسئله را درست نام ببری، انتخاب ابزار ساده می‌شود.

Start with the model, then move to team incidents. Rely on what was actually recorded, not branch names or wishful thinking.

وقتی می‌دانی چه می‌خواهی، این ابزارها کمک می‌کنندThese tools help when you know what you need

این سه ابزار وقتی به درد می‌خورند که دقیقاً می‌دانی چه چیزی می‌خواهی. فصل بعد برعکس است: فقط می‌دانیم جایی در چند ده commit گذشته یک باگ وارد شده و باید با کمترین آزمون، مرزش را پیدا کنیم.

You can preserve unfinished work, apply a known patch, and name a tested version. But if a bug appeared weeks ago and you do not know which commit introduced it, neither stash nor cherry-pick answers that question. Chapter 12 turns it into a systematic search with git bisect.

مرور کوتاهQuick reference

stash برای توقف کوتاه، cherry-pick برای آوردن یک تغییر مشخص و tag برای نام‌گذاری یک نقطهٔ تاریخ است. اگر یکی از این سه را برای مسئلهٔ دیگری استفاده می‌کنی، یک بار دیگر سؤال اصلی را بخوان.

For behavior in your Git version, see the official manuals for git stash, git cherry-pick, git tag, and git push. Configuration may affect pushes; inspect the remote result.