یک فایل، سه نسخهٔ هم‌زمانOne file, three versions at once

در حال اصلاح پیام خطا هستی. نسخه‌ای که آخرین بار commit کردی می‌گوید «درخواست نامعتبر». نسخهٔ تازه‌تری را add کرده‌ای که می‌گوید «شناسه نامعتبر». بعد هم متن فایل را دوباره تغییر داده‌ای تا بگوید «شناسهٔ کاربر نامعتبر».

You are refining an error message. The last committed version says “Invalid request.” You staged a newer version saying “Invalid ID,” then edited the file again to say “Invalid user ID.”

حالا git status یک نام فایل را هم در «آمادهٔ ثبت» نشان می‌دهد و هم در «تغییرهای آماده‌نشده». سؤال اینجاست: «چطور یک نام فایل می‌تواند هر دو وضعیت را داشته باشد؟» تناقض نیست؛ وضعیت اختلاف دو جفت از سه نسخه را جداگانه گزارش می‌کند.

git status now lists one filename under both “to be committed” and “not staged.” The question is: “How can one filename have both statuses?” It is not a contradiction; status reports two different comparisons involving three versions.

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

To keep this model from being just a drawing, we will test it in a separate folder. Do not run the following sequence in a real work repository: the experiment deliberately changes files and creates several states.

mkdir three-area-lab && cd three-area-lab
git init -q
git config user.name 'Ada Example'
git config user.email 'ada@example.test'
printf 'Invalid request\n' > message.txt
git add message.txt && git commit -m 'Add initial message'

حدس بزن: حالا هر سه ناحیه چه محتوایی دارند؟ چون همین الان commit کرده‌ایم و فایل را بعدش دست نزده‌ایم، هر سه برابرند. وضعیت باید تمیز باشد و هر دو diff خالی.

Predict first: what does each area contain now? We just committed and have not edited the file since, so all three match. Status should be clean and both diffs empty.

هر diff فقط یک جفت را مقایسه می‌کندEach diff compares one pair

اگر سه نسخه داریم، برای پیدا کردن اختلاف باید بپرسیم «کدام دو نسخه؟» اسم دستورها همین جواب را می‌دهند: git diff پوشه‌ کاری را با ناحیه‌ آماده‌سازی می‌سنجد؛ git diff --staged یا --cached، ناحیه‌ آماده‌سازی را با HEAD.

With three versions, every comparison must answer “which two?” The commands encode that answer: git diff compares the working tree with the index; git diff --staged (or --cached) compares the index with HEAD.

حالا وضعیت پایه را ثبت کن. خروجی نمونه ثابت نیست؛ نام شاخه و پیام commit با مخزن تو فرق می‌کند. نکتهٔ مهم این است که وضعیت تمیز است، و هیچ‌یک از دو مقایسه تغییری برای نشان دادن ندارد.

Record the baseline. The sample output is illustrative: your branch name and commit message may differ. What matters is the clean status and the absence of changes in either comparison.

git status --short
git diff
git diff --staged
(no output from status or either diff)

حالا فقط فایل را ویرایش می‌کنیم؛ هنوز add نه. حدس بزن کدام diff متن جدید را نشان می‌دهد.

Now edit only the file; do not add it yet. Predict which diff will show the new text.

printf 'Invalid ID\n' > message.txt
git status --short
git diff
git diff --staged
 M message.txt
diff shows: -Invalid request / +Invalid ID
git diff --staged is empty

فاصلهٔ قبل از M یعنی ستون اول، یعنی ناحیه‌ آماده‌سازی، تغییر نکرده؛ ستون دوم یعنی پوشه‌ کاری تغییر کرده. در این لحظه فایل روی دیسک «Invalid شناسه» است، اما ناحیه‌ آماده‌سازی و HEAD هنوز «Invalid request» را دارند.

The leading blank before M means column one—the index—did not change; column two—the working tree—did. The file says “Invalid ID,” while the index and HEAD still say “Invalid request.”

بعد از git add همان فایل، اول حدس بزن: آیا این دستور نسخهٔ بعدی را در commit می‌گذارد یا فقط وضعیت فایل را ثبت می‌کند؟

After git add on this file, predict: does it put the new version in the next commit, or merely mark the file's state?

git add message.txt
git status --short
git diff
git diff --staged
M  message.txt
git diff is empty
staged diff shows: -Invalid request / +Invalid ID

این بار ستون اول M است و ستون دوم خالی. اختلاف در جفت HEAD ↔ ناحیه‌ آماده‌سازی است؛ پس diff --staged آن را می‌بیند. پوشه‌ کاری و ناحیه‌ آماده‌سازی فعلاً یکسان‌اند، برای همین git diff خالی است.

Now the first column is M and the second is blank. The difference is between HEAD and the index, so diff --staged shows it. The working tree and index currently match, so git diff is empty.

حالا متن را یک‌بار دیگر تغییر بده. از وضعیت MM نترس؛ دو حرف یعنی دو اختلاف مستقل، نه دو فایل.

Edit the text once more. Do not be alarmed by MM; the two letters mean two separate differences, not two files.

printf 'Invalid user ID\n' > message.txt
git status --short
git diff --staged
git diff
MM message.txt
staged:   Invalid request → Invalid ID
unstaged: Invalid ID → Invalid user ID

حالا هر دو نسخه را می‌بینی: diff ناحیه‌ آماده‌سازیشده از HEAD تا ناحیه‌ آماده‌سازی است و diff معمولی از ناحیه‌ آماده‌سازی تا پوشه‌ کاری. نام فایل یکی است چون هر دو تغییر در همان مسیرند.

You can now see both versions: the staged diff runs from HEAD to the index, and plain diff runs from the index to the working tree. The filename is the same because both changes affect that path.

ناحیه‌ آماده‌سازی اتاق انتظار نیست؛ پیش‌نویس tree بعدی استThe index is not a waiting room; it is the next tree draft

واژهٔ «آماده‌سازی» گاهی این تصور را می‌سازد که فایل کامل آنجا می‌نشیند تا commit شود. دقیق‌تر این است: ناحیه‌ آماده‌سازی جدولی از مسیرها و نسخهٔ محتوایی است که برای هر مسیر در عکس فوری بعدی پیشنهاد می‌کنی. همان‌طور که فصل دوم دیدیم، هر مدخل به blob و مجوز اشاره می‌کند؛ موقع commit از این فهرست، tree ساخته می‌شود.

“Staging area” can sound like a shelf where whole files wait for commit. More precisely, the index is a table of paths and the content version proposed for each path in the next snapshot. As Chapter 02 showed, entries point to blobs and modes; a commit turns this list into trees.

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

This is what makes an atomic commit possible: record the bug fix separately and leave the debug print for a later decision. “Atomic” means one commit has a clear purpose and related changes; it does not mean Git physically stores the file in pieces.

برای دیدن ناحیه‌ آماده‌سازی، git ls-files --stage مدخل‌هایش را نشان می‌دهد. شناسه ستون دوم شناسهٔ blob است و ناحیه‌ آماده‌سازی number در حالت عادی صفر است. در تعارض merge ممکن است چند مدخل ناحیه‌ آماده‌سازی برای یک مسیر ببینی؛ آن موضوع را فصل merge باز می‌کند.

git ls-files --stage displays index entries. The second column is the blob ID; the stage number is normally zero. During a merge conflict, one path can have multiple stage entries—a topic the merge chapter will cover.

git ls-files --stage
100644 8a7b6c5... 0	message.txt
git diff --staged --stat
 message.txt | 2 +-

این شاهد می‌گوید ناحیه‌ آماده‌سازی برای message.txt یک مدخل دارد و diff --staged اندازهٔ تغییرِ پیشنهادی را نشان می‌دهد. اما یک blob شناسه ثابت نمی‌کند متن از نظر محصول درست است؛ باز هم خود diff را بخوان.

This evidence says the index has an entry for message.txt and diff --staged summarizes the proposed change. A blob ID does not prove the wording is correct for the product; still read the diff itself.

commit از ناحیه‌ آماده‌سازی ساخته می‌شود، نه از هرچه روی دیسک ماندهA commit comes from the index, not everything left on disk

نسخهٔ سوم را می‌سازیم: بعد از ناحیه‌ آماده‌سازی کردن «Invalid شناسه»، فایل را به «Invalid user شناسه» تغییر می‌دهیم. قبل از commit حدس بزن: کدام متن در عکس فوری بعدی خواهد بود؟

Create a third version: after staging “Invalid ID,” edit the file to say “Invalid user ID.” Before committing, predict which text the next snapshot will contain.

printf 'Invalid ID\n' > message.txt
git add message.txt
printf 'Invalid user ID\n' > message.txt
git status --short
git diff --staged
git diff
MM message.txt
staged:   Invalid request → Invalid ID
unstaged: Invalid ID → Invalid user ID

خروجی MM یعنی هر دو مقایسه تغییر دارند. برای commit هم باید بخش ناحیه‌ آماده‌سازیشده را بازبینی کنیم؛ فایل روی دیسک نسخهٔ جدیدتری دارد، ولی خودکار وارد ناحیه‌ آماده‌سازی نمی‌شود.

MM means both comparisons contain changes. Review the staged diff before committing: the disk file has a newer version, but it does not enter the index automatically.

پیش‌بینی را با ثبت commit و خواندن فایل از خود commit امتحان کن. این بار عمداً از git show HEAD:message.txt استفاده می‌کنیم، نه از ویرایشگر؛ پس عکس فوری ثبت‌شده را می‌خوانیم.

Test your prediction by committing and reading the file from the commit itself. We use git show HEAD:message.txt, not the editor, so we inspect the recorded snapshot.

git diff --staged
git commit -m 'Clarify invalid ID message'
git show HEAD:message.txt
git status --short
git diff
git diff --staged
Invalid ID
 M message.txt
git diff shows: -Invalid ID / +Invalid user ID
git diff --staged is empty

commit نسخهٔ ناحیه‌ آماده‌سازی یعنی «Invalid شناسه» را ثبت کرد و فایل روی دیسک هنوز «Invalid user شناسه» است؛ بنابراین وضعیت تغییر آماده‌نشده نشان می‌دهد. برای گنجاندن متن آخر باید دوباره git add message.txt بزنی و diff را دوباره بخوانی.

The commit recorded the index version, “Invalid ID,” while the disk file still says “Invalid user ID,” so status reports an unstaged edit. To include the latest text, run git add message.txt again and review the diff.

add یعنی انتخاب نسخه و مسیر، نه زدن تیک کل فایلadd selects content and paths; it does not tick a whole file

یک فایل handler.js را تصور کن: هم شرطی که باگ را حل می‌کند عوض شده، هم یک چاپ عیب‌یابی اضافه کرده‌ای. می‌خواهی اصلاح باگ را همین حالا ثبت کنی و عیب‌یابی را بعد از بررسی حذف کنی. git add handler.js هر دو تغییر را ناحیه‌ آماده‌سازی می‌کند؛ برای جدا کردنشان، git add -p را به کار ببر.

Imagine handler.js contains both a bug fix and a temporary debug print. You want to commit the fix now and remove the print after inspection. git add handler.js stages both changes; use git add -p to separate them.

git diff -- handler.js
git add -p handler.js
Stage this hunk [y,n,q,a,d,s,e,?]? y
Stage this hunk [y,n,q,a,d,s,e,?]? n
git diff --staged -- handler.js
git diff -- handler.js

در نمونه، برای hunk اصلاح باگ y و برای چاپ عیب‌یابی n می‌زنی. prompt واقعی گزینه‌های بیشتری دارد؛ s اگر بتواند hunk را خرد می‌کند و ? راهنمای همان نسخه را نشان می‌دهد. خروجی را فرض نکن—بعدش هر دو diff را بخوان تا مطمئن شوی انتخاب درست بوده.

In this example, answer y for the bug-fix hunk and n for the debug print. The real prompt offers more choices: s may split a hunk, and ? explains the options for your version. Inspect both diffs afterwards to verify the selection.

در Git امروزی، git add -A بدون مسیر کل پوشه‌ کاری را می‌گیرد؛ با pathspec فقط همان محدوده را هماهنگ می‌کند. git add . هم pathspec نقطه را دارد، یعنی پوشهٔ فعلی و زیرشاخه‌هایش؛ در نسخه‌های امروزی حذف‌ها را هم در این محدوده می‌بیند. رفتار تاریخی نسخه‌های خیلی قدیمی فرق داشت، پس راهنمای قدیمی را بی‌بررسی کپی نکن. برای commit دقیق، مسیر یا hunk را انتخاب کن و قبل از commit git diff --staged بخوان.

In current Git, pathless git add -A covers the whole working tree; with a pathspec, it updates only that scope. git add . uses the dot pathspec, meaning the current directory and its descendants; current versions also notice removals there. Very old versions behaved differently, so do not copy old guidance without checking. For a precise commit, choose paths or hunks and review git diff --staged.

حذف و تغییرنام را هم با همین مدل بخوانRead deletions and renames through the same model

اگر فایل ردیابی‌شده را از دیسک پاک کنی، ناحیه‌ آماده‌سازی هنوز نسخهٔ قبلی را دارد؛ پس وضعیت حذفِ آماده‌نشده نشان می‌دهد. git add FILE برای همان مسیر حذف‌شده یا git add -A حذف را در ناحیه‌ آماده‌سازی ثبت می‌کند. در تغییرنام هم Git یک شیء ویژهٔ تغییرنام ذخیره نمی‌کند: مسیر قدیمی حذف و مسیر تازه اضافه می‌شود؛ هنگام نمایش diff، Git ممکن است شباهت محتوا را تشخیص دهد و آن را تغییرنام نشان دهد.

If you remove a tracked file from disk, the index still contains its old version, so status reports an unstaged deletion. git add FILE for that removed path, or git add -A, stages the removal. A rename is not stored as a special object: the old path is removed and a new path added; Git may infer a rename from content similarity when showing a diff.

rm message.txt
git status --short
 D message.txt
git add message.txt
git status --short
D  message.txt
git diff --staged --summary

در خروجی کوتاه، D یعنی فایل روی دیسک حذف شده ولی هنوز ناحیه‌ آماده‌سازی نشده؛ D یعنی حذف در ناحیه‌ آماده‌سازی آمادهٔ commit است. کد تغییرنام نمایش‌داده‌شده نتیجهٔ تشخیص هنگام مقایسه است، نه مدخل ذخیره‌شدهٔ جداگانه.

In short status, D means the file is deleted on disk but not staged; D means the deletion is staged. A displayed rename code is inferred during comparison, not a separate stored index entry.

restore در این فصل: کدام کپی را نگه می‌داری؟restore in this chapter: which copy do you keep?

فرض کن متن را ناحیه‌ آماده‌سازی کرده‌ای، اما هنوز در پوشه‌ کاری یک اصلاح ناخواسته مانده. می‌خواهی فقط فایل روی دیسک را با نسخهٔ ناحیه‌ آماده‌سازی عوض کنی. این کار محتوای ناحیه‌ آماده‌سازیشده را نگه می‌دارد، ولی ویرایش آماده‌نشده را کنار می‌گذارد—پس فقط وقتی بزن که آن ویرایش را نمی‌خواهی.

Suppose you staged a version, then left an unwanted edit in the working tree. You want to replace only the disk file with the index version. This keeps the staged content but discards the unstaged edit—so use it only if you no longer want that edit.

git diff -- message.txt
-Invalid ID
+Invalid user ID
git restore -- message.txt
git diff -- message.txt
(no output: working tree now matches index)

بدون --staged، منبع پیش‌فرض پوشه‌ کاری، ناحیه‌ آماده‌سازی است. در مقابل، اگر چیزی را ناحیه‌ آماده‌سازی کرده‌ای و می‌خواهی ناحیه‌ آماده‌سازی را به HEAD برگردانی، git restore --staged FILE را بزن. نسخهٔ روی دیسک دست‌نخورده می‌ماند؛ تغییر فقط از ناحیه‌ آماده‌سازی بیرون می‌رود.

Without --staged, the default source for the working tree is the index. In contrast, to restore a staged path in the index to HEAD, run git restore --staged FILE. The disk copy stays untouched; only the index changes.

git diff --staged -- message.txt
(shows staged change)
git restore --staged -- message.txt
git status --short
 M message.txt
git diff -- message.txt
(change remains on disk, now unstaged)

اگر فایل تازه‌ای را ناحیه‌ آماده‌سازی کرده‌ای، restore --staged مدخل تازه را از ناحیه‌ آماده‌سازی برمی‌دارد و فایل روی دیسک را به حالت ردیابی‌نشده برمی‌گرداند. اگر فایل ردیابی‌شده را حذف و حذف را ناحیه‌ آماده‌سازی کرده‌ای، restore کردن ناحیه‌ آماده‌سازی نسخهٔ HEAD را به ناحیه‌ آماده‌سازی برمی‌گرداند، اما فایل ممکن است همچنان روی دیسک غایب باشد؛ آن وقت حذف، آماده‌نشده است. راه‌های دیگر برگشت، موضوع فصل ۹ هستند.

If you staged a new file, restore --staged removes its new index entry and leaves the disk file untracked. If you deleted a tracked file and staged the deletion, restoring the index brings the HEAD version back into the index, but the disk file may still be absent; the deletion is then unstaged. Other ways to undo work belong to Chapter 09.

وضعیت نقشهٔ تشخیصی استstatus is a diagnostic map

به‌جای حفظ کردن متن کامل وضعیت، خروجی کوتاه را مثل دو ستون بخوان. ستون چپ وضعیت ناحیه‌ آماده‌سازی نسبت به HEAD است؛ ستون راست وضعیت پوشه‌ کاری نسبت به index. پس یک حرف می‌تواند برای یک فایل دو بار ظاهر شود و هر بار دربارهٔ مقایسه‌ای جدا حرف بزند.

Rather than memorising every status sentence, read short status as two columns. The left column is the index relative to HEAD; the right is the working tree relative to the index. One path can show two letters, each describing a different comparison.

اگر تغییر مورد انتظار را نمی‌بینی، از همان‌جا حدس نزن که Git خراب است. git status --ignored کمک می‌کند فایل نادیده‌گرفته‌شده را از ردیابی‌نشده تشخیص بدهی؛ git check-ignore -v FILE هم قاعدهٔ مسئول را نشان می‌دهد. فایلی که هنوز track نشده ممکن است در git diff معمولی نیاید، چون آن دستور تغییر مسیرهای ردیابی‌شده را مقایسه می‌کند.

If an expected change is missing, do not conclude that Git is broken. git status --ignored helps distinguish an ignored file from an untracked one; git check-ignore -v FILE identifies the matching rule. A path never tracked may not appear in ordinary git diff, which compares changes to tracked paths.

git status --short --ignored
git check-ignore -v build/report.txt
.gitignore:4:build/    build/report.txt

این خروجی می‌گوید قاعدهٔ خط چهارم باعث نادیده‌گرفتن مسیر شده؛ ثابت نمی‌کند فایل بی‌ارزش است. اگر خروجی خالی بود، شاید مسیر وجود ندارد، از قبل track شده یا قاعدهٔ دیگری در کار است—وضعیت فایل را جدا بررسی کن.

This output says the fourth rule ignored the path; it does not prove the file is disposable. If output is empty, the path may not exist, may already be tracked, or may be governed differently—inspect its status separately.

چند دام رایج، با شاهد درستCommon traps, with the right evidence

تمرین‌هاExercises

در تمرین‌ها مهم‌تر از اسم دستور این است که بتوانی قبل از اجرا بگویی «این دستور کدام دو نسخه را مقایسه می‌کند یا کدام نسخه را جابه‌جا می‌کند؟» اگر این جمله را درست بگویی، شکل دستور را بعداً هم می‌توانی از راهنما پیدا کنی.

For each question, first predict the version in every area, then choose a command. Most can be tested in the disposable lab; stay away from repositories with valuable work.

پروژهٔ کوچک: دو commit از یک پوشهٔ شلوغMini project: two commits from one messy working tree

mkdir two-commits-lab && cd two-commits-lab
git init -q
git config user.name 'Ada Example'
git config user.email 'ada@example.test'
printf 'function findUser(id) {\n  return users[id] || null;\n}\n' > handler.js
printf '# راهنما\nدرخواست کاربر را برسی کن.\n' > README.md
printf 'build-output\n' > generated.txt
printf 'handler.js\ngenerated.txt\n' > .gitignore
git add handler.js README.md .gitignore
git commit -m 'Add user lookup and usage note'

git status --short --ignored
git diff -- handler.js README.md
git check-ignore -v generated.txt
# choose only the fix (or its hunk)
git add -p handler.js
git diff --staged
git diff
git commit -m 'Handle missing user in lookup'
# stage only README after verifying the first commit
git add README.md
git diff --staged
git commit -m 'Correct lookup instructions'
git status --short --ignored
git diff
git diff --staged
git log --stat -2

نقشهٔ سریع سه ناحیهQuick map of the three areas

اگر فقط یک نقشه از این فصل همراهت بماند، همین باشد: Git برای یک فایل می‌تواند هم‌زمان سه نسخه داشته باشد. هر بار گیج شدی، اول مشخص کن کدام نسخه را داری می‌بینی.

You can now locate changes and know which version a commit records. The next step is natural: once snapshots are committed, how do we read history as an investigation instead of scrolling through messages at random?