تنظیم امروز خراب است؛ از کجا سرنخ بگیریم؟Today's configuration is broken. Where do we look?

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

The service will not start, and the latest error points to timeout=0. We know the value is wrong, but several questions remain: when did it enter the file, in which commit, under what earlier filename, and what else changed with it? Does the person who last touched the line know why?

در فصل اول نگاهی کوتاه به git log و git show داشتیم؛ فصل دوم هم نشان داد commit یک عکس فوری است، نه فهرست تغییرات ذخیره‌شده. اینجا همان مدل را به ابزار تحقیق وصل می‌کنیم: اول سؤال را دقیق می‌کنیم، بعد نمایی از تاریخچه می‌گیریم، و سرنخ را تا patch دنبال می‌کنیم.

Chapter 01 introduced git log and git show; Chapter 02 showed that a commit is a snapshot, not a stored list of changes. Here we connect that model to investigation: make the question precise, get a view of history, then follow the lead down to a patch.

log را برای یک سؤال مشخص اجرا کنRun log to answer a specific question

برای شروع، یک نمای فشرده از commitهای اخیر می‌گیریم. پیام‌ها نامزد را نشان می‌دهند، نه جزئیات باگ را. بعد گراف و اشاره‌گرها را اضافه می‌کنیم تا بفهمیم HEAD کجاست و تاریخچه خطی است یا شاخه دارد.

Start with a compact view of recent commits. Subjects suggest a candidate; they do not reveal the bug's details. Then add graph shape and refs to see where HEAD is and whether history is linear or branched.

git log --oneline -5
9bd41a2 (HEAD -> main) Document restart procedure
41fe88c Set timeout to zero
b70c215 Rename service config
0ca6e10 Add retry setting
178a4d0 Add initial service config
git log --oneline --graph --decorate --all

شناسه‌ها و نام شاخه نمونه‌اند و در مخزن تو فرق می‌کنند. commit مشکوک دوم است؛ HEAD روی تغییر README ایستاده. --graph اتصال commitها را با خط و شاخه نشان می‌دهد، --decorate نام اشاره‌گرها را کنار commit می‌آورد، و --all اشاره‌گرهای محلی را هم برای این پرس‌وجو در نظر می‌گیرد. این گزینه‌ها فقط نمایی خواناتر می‌سازند؛ محتوای patch هنوز معلوم نیست.

IDs are illustrative and will differ in your repository. The suspect is second; HEAD sits on the README change. --graph draws parent connections, --decorate adds ref names beside commits, and --all includes local refs in the query. These options improve the view; the patch is still unknown.

برای دیدن فقط فایل‌های درگیر، --name-status را می‌گیریم؛ برای اندازهٔ تقریبی تغییر از --stat استفاده می‌کنیم. این دو پاسخ متفاوت دارند: یکی مسیر و نوع تغییر را می‌گوید و دیگری شمار تقریبی خط‌ها را.

Use --name-status to list paths involved, or --stat for approximate change size. They answer different questions: one gives paths and change types; the other summarizes line counts.

git log --stat -3
git log --name-status -4
A\tREADME.md
M\tapp.conf
R100\tservice.conf\tapp.conf

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

In this representative output, R100 means Git paired two paths with full similarity and reports a rename in this view. A rename is not a distinct object or stored operation in the commit; it is inferred by comparing snapshots and can vary with content.

نسخهٔ تاریخچهها را دقیق نام ببرName revisions precisely

برای بازکردن commit مشکوک لازم نیست شناسهٔ کامل را حفظ کنی. HEAD جایی است که اشاره‌گر جاری می‌رسد؛ در تاریخچهٔ خطی، HEAD~1 یک گام روی زنجیرهٔ والد اول به عقب و HEAD~2 دو گام است. HEAD^ والد اول مستقیم است، پس در commit تک‌والدی با HEAD~1 یکی است.

You need not memorize a full ID to inspect the suspect. HEAD is where the current ref points; in linear history, HEAD~1 is one first-parent step back and HEAD~2 is two. HEAD^ is the direct first parent, so on a single-parent commit it equals HEAD~1.

در merge، ^ والد اول و ^2 والد دوم را می‌خواهد. شناسهٔ کوتاه هم فقط تا وقتی کافی است که در همین مخزن مبهم نباشد؛ اگر Git گفت ambiguous، چند نویسهٔ بیشتر بگیر. برای commit آخر در برابر والدش می‌توانی git diff HEAD^ HEAD بنویسی.

At a merge, ^ names the first parent and ^2 the second. An abbreviated ID works only while it is unambiguous in this repository; use more characters if Git reports ambiguity. To compare the latest commit with its parent, write git diff HEAD^ HEAD.

git log --format='%h %ad %an <%ae> %s' --date=short -4
9bd41a2 2025-04-12 Mina Example <mina@example.test> Document restart procedure
41fe88c 2025-04-11 Arman Example <arman@example.test> Set timeout to zero
git show --format=fuller --stat HEAD~1
git show --format= --word-diff=plain HEAD~1 -- app.conf

قالب سفارشی ردیف را می‌چیند: %h شناسهٔ کوتاه، %ad تاریخ نویسنده، %an نام نویسنده و %s عنوان پیام. در خروجی fuller نویسنده کسی است که تغییر را نوشته و ثبت‌کننده کسی که commit را ثبت کرده؛ این دو می‌توانند متفاوت باشند، مثلاً وقتی دیگری patch را اعمال می‌کند.

A custom format arranges fields: %h abbreviated ID, %ad author date, %an author name, and %s subject. In fuller output, the author wrote the change and the committer recorded the commit; they can differ, for example when someone applies another person's patch.

git show یک commit را با فراداده و patch آن می‌خواند؛ در فرمان آخر، --format= سرآیند را حذف کرده‌ایم تا تغییر واژه‌ای فایل را ببینیم. --word-diff یا --unified=0 برای یک مقدار کوچک خواناتر است، اما زمینه را کم می‌کند. پیام commit ادعای نویسنده است؛ patch محتوای مقایسه‌شده را نشان می‌دهد.

git show reads a commit with its metadata and patch; the last command uses --format= to omit the header and focus on changed words. --word-diff or --unified=0 can help with a small value, but reduce context. A commit message is the author's claim; the patch shows compared content.

وقتی فایل تغییرنام شده، تاریخش را تا کجا می‌بینی؟How far does a renamed file's history go?

حالا می‌دانیم مقدار خراب بعد از تغییرنام وارد app.conf شده. git log -- app.conf تاریخچه را به همین مسیر محدود می‌کند. برای دنبال‌کردن یک تغییرنام ساده، --follow را امتحان می‌کنیم؛ این گزینه محدودیت دارد و جای بررسی گراف یا mergeها را نمی‌گیرد.

We know the bad value entered app.conf after a rename. git log -- app.conf limits history to that path. Try --follow to trace a simple rename; it has limits and does not replace understanding the graph or merges.

git log --oneline -- app.conf
41fe88c Set timeout to zero
b70c215 Rename service config
git log --oneline --follow -- app.conf
41fe88c Set timeout to zero
b70c215 Rename service config
0ca6e10 Add retry setting
178a4d0 Add initial service config

خروجی به تاریخچه و نسخهٔ Git بستگی دارد؛ در این آزمایش --follow مسیر را قبل از نام قبلی هم پیدا می‌کند. این گزینه فقط برای یک فایل است و تغییرنام را از شباهت محتوا حدس می‌زند. تغییرهای بزرگ هم‌زمان با تغییرنام یا تاریخچهٔ شاخه‌دار می‌توانند ردگیری را پیچیده کنند.

Output depends on history and Git version; in this lab, --follow reaches commits before the old name. It applies to one file and infers a rename from content similarity. Large edits alongside the rename or branched history can complicate tracing.

اگر خروجی خالی شد، اول نام مسیر را در عکس فوری انتخاب‌شده بررسی کن: git ls-tree -r --name-only HEAD. بعد نام قدیمی و فیلترها را امتحان کن. نتیجهٔ خالی به‌تنهایی نمی‌گوید فایل چرا حذف شده یا اصلاً در تاریخچهٔ قابل‌دسترست بوده است.

If output is empty, first check paths in the selected snapshot with git ls-tree -r --name-only HEAD. Then try the old name and review filters. Empty output alone does not explain why a file was deleted or whether it exists in reachable history.

blame می‌گوید خط آخرین بار کجا عوض شد، نه چراblame says where a line last changed, not why

می‌خواهیم ببینیم خط timeout=0 به کدام commit نسبت داده می‌شود. git blame برای هر خط نسخهٔ انتخابی، نسخهٔ تاریخچه و اطلاعات نویسنده تغییری را نشان می‌دهد که Git آن خط را به آن نسبت می‌دهد. این سرنخ است، نه حکم اخلاقی و نه شرح نیت.

We want to see which commit is attributed to timeout=0. For each line in a selected file version, git blame shows a revision and author information for the change Git attributes that line to. This is a lead, not a moral verdict or a statement of intent.

git blame -L 1,3 -- app.conf
^178a4d0 (Nika Example 2025-04-10 1) [http]
41fe88c  (Nika Example 2025-04-10 2) timeout=0
0ca6e10  (Nika Example 2025-04-10 3) retries=2
git show --format=fuller 41fe88c -- app.conf

blame نسبت خط را به commit می‌دهد؛ اما یک commit قالب‌بندی ممکن است خط‌ها را دوباره نسبت بدهد. در چنین وضعی git blame -w FILE تفاوت whitespace را نادیده می‌گیرد و -M/-C می‌تواند جابه‌جایی/کپی خط را دنبال کند. این گزینه‌ها heuristic هستند؛ patch را هم بخوان.

Blame attributes a line to a commit, but a formatting commit may change attribution. git blame -w FILE ignores whitespace differences, while -M/-C can trace moved/copied lines. These options are heuristic; inspect the patch too.

اسم blame کمی تند است؛ آن را «ردگیری خط» بخوان. Git می‌گوید آخرین تغییر قابل‌ردگیری کجا بوده، نه چه کسی تصمیم را گرفته، چرا پذیرفته شده یا آیا همان تغییر علت خطای امروز است. git show --format=fuller نویسنده را از ثبت‌کننده جدا می‌کند؛ این دو ممکن است یک نفر نباشند.

The name blame sounds accusatory; think “line tracing.” Git shows the last traceable change, not who made a decision, why it was accepted, or whether it caused today's failure. git show --format=fuller separates author from committer; they may be different people.

اگر خط خراب در نسخهٔ فعلی حذف شده باشد، blame دیگر آن را نمایش نمی‌دهد. اینجا -S و -G سرنخ می‌دهند: اولی commitهایی را می‌یابد که تعداد رخداد یک رشتهٔ دقیق عوض شده؛ دومی commitهایی را که خط افزوده/حذف‌شده‌شان با regex منطبق است.

If the bad line was deleted from the current version, blame cannot display it. -S and -G provide leads: the former finds commits where an exact string's occurrence count changed; the latter finds commits whose added or removed patch lines match a regex.

git log --oneline --follow -S'timeout=0' -- app.conf
41fe88c Set timeout to zero
git log --oneline --follow -G'timeout[[:space:]]*=[[:space:]]*0' -- app.conf
41fe88c Set timeout to zero

در این پرونده هر دو commit را می‌یابند، اما سؤال یکی نیست: -S تغییر شمار رخدادهای متن دقیق را می‌سنجد؛ -G regex را روی خط‌های patch امتحان می‌کند و فاصله‌های متفاوت را هم می‌تواند بگیرد. اگر عبارتی جابه‌جا شود اما شمار رخدادهایش ثابت بماند، ممکن است -S آن commit را نگیرد و -G بگیرد.

Both find the commit here, but they ask different questions: -S checks the exact string's occurrence count; -G tests a regex against patch lines and can match spacing variations. If text moves while its count stays constant, -S may omit the commit while -G finds it.

اگر جست‌وجو نتیجه نداد، رشته را از patch واقعی بردار، مسیر قدیمی و جدید را بررسی کن و فیلتر نسخهٔ تاریخچه را بازبینی کن. نبودن نتیجه نمی‌گوید عبارت هیچ‌وقت وجود نداشته؛ شاید commit نشده یا در اشاره‌گرهای قابل‌دسترسی فعلی نیست.

If the search finds nothing, copy the string from a real patch, check old and new paths, and review revision filters. No result does not prove the text never existed; it may never have been committed or may not be reachable from current refs.

وقتی خروجی با انتظارمان نمی‌خواندWhen output does not match expectation

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

In a history investigation, an empty command is rarely the end; it is a signal to revisit the question or scope. Change one assumption at a time to learn which one was wrong.

تمرین‌ها: از خواندن پیام تا ساختن پروندهExercises: from reading a message to building a case

این تمرین‌ها مثل پروندهٔ بررسی‌اند. به جای اینکه یک دستور را از حفظ بزنی، از خودت بپرس دنبال چه چیزی هستی: یک commit خاص؟ زمان ورود یک عبارت؟ تفاوت دو عکس فوری؟ یا آخرین کسی که این خط را عوض کرده؟ بعد ابزار مناسب را انتخاب کن.

Predict from the evidence before opening a solution. No history-rewriting command is needed; use the project's disposable repository for experiments.

پروژهٔ کوچک: چه کسی تنظیم را خراب کرد؟Mini project: who broke the configuration?

mkdir who-broke-config && cd who-broke-config
git init -q
git config user.name 'Nika Example'
git config user.email 'nika@example.test'
printf '[http]\ntimeout=30\n' > service.conf
git add service.conf && git commit -m 'Add initial service config'

printf '[http]\ntimeout=30\nretries=2\n' > service.conf
git add service.conf && git commit -m 'Add retry setting'

git mv service.conf app.conf
git commit -m 'Rename service config'

printf '[http]\ntimeout=0\nretries=2\n' > app.conf
git add app.conf && git commit -m 'Set timeout to zero'

printf '# Operations\nRestart service after config updates.\n' > README.md
git add README.md && git commit -m 'Document restart procedure'

نقشهٔ سریع برای بررسی تاریخچهQuick map for a history investigation

مرور سریع خوب است، ولی این فصل با حفظ پرچم‌های log یاد گرفته نمی‌شود. سؤال درست را انتخاب کن و بعد از Git بخواه فقط همان بخش از تاریخچه را نشانت بدهد.

You can now read a graph and follow a change down to its patch. Next is not history rewriting; it is changing the path of work. Chapter 05 shows that a branch is not a copy of the project—it is a movable name pointing into this graph.