گیت روزمره: شاخه، ثبت تغییر، تفاوت و ادغام

وقتی Git موفق است اما هنوز نمی‌توان گفت تغییر قابل پذیرش است

یک تغییر کوچک برای اصلاح گرد کردن مبلغ روی یک topic branch آماده شده است. branch اسم مناسبی دارد، commit ساخته شده و تست محلی همان branch سبز است. با این حال، قبل از merge سه سؤال باز می‌ماند: branch از کدام نقطهٔ target جدا شده، commit دقیقاً چه deltaی را حمل می‌کند، و نتیجهٔ ادغام‌شده روی state جدید target چگونه رفتار می‌کند؟

این درس branch، staging، diff، commit و merge را به یک گیت evidence تبدیل می‌کند، نه به فهرست commandها. خروجی اصلی Daily Git Change Gate Record v1 است. این رکورد باید نشان دهد base/target انتخاب‌شده چیست، delta قابل بازبینی کدام است، snapshot مورد commit چه محدوده‌ای دارد، verification قبل و بعد از integration چه چیزی را پوشش می‌دهد، و تصمیم انسانی نهایی چیست.

یک branch تمیز، یک commit مرتب یا یک merge بدون conflict فقط دربارهٔ state و عملیات Git evidence می‌دهند. هیچ‌کدام به‌تنهایی correctness رفتاری یا آمادگی پذیرش را ثابت نمی‌کنند. معیار این درس این است که claimهای تو به evidence قابل بازرسی متصل باشند و هر محدودیت صریح بماند.

سه مسیر یادگیری، یک evidence bar

مسیر Foundation برای زمانی است که هنوز branch context، comparison boundary و commit snapshot را با هم قاطی می‌کنی. تعریف‌ها و یک case هدایت‌شده را کامل می‌کنی.

مسیر Repair فقط به اولین تمایز خراب برمی‌گردد. اگر base را درست پیدا می‌کنی ولی diffی را بررسی می‌کنی که unrelated delta را پنهان می‌کند، تمرین روی انتخاب comparison و evidence آن متمرکز می‌شود.

مسیر Experienced / Fast Path syntax را کوتاه می‌کند، نه artifact یا verification را. تجربهٔ زیاد با Git مجوز این نیست که branch name، commit message یا merge success را جای evidence بگذاری.

Self-check: آیا می‌توانی با evidence نشان دهی topic branch نسبت به target فعلی چه چیزی را تغییر می‌دهد؟ آیا می‌توانی بگویی commit فعلی دقیقاً snapshot مورد نظر را دارد؟ آیا بعد از merge یک check مستقل روی integrated state داری؟ اگر هر پاسخ به حدس وابسته است، گیت هنوز بسته نشده است.

مدل ذهنی: پنج مرز جدا

Branch/base context محل و ancestry تغییر را مشخص می‌کند. branch درست‌نام لزوماً از base مناسب ساخته نشده است.

Working/index boundary می‌گوید چه چیزی در working tree، index و commit history قرار دارد. staged بودن برچسب intent نیست؛ فقط state نسبت به index/HEAD است.

Diff boundary باید comparisonی را انتخاب کند که claim مورد نظر را قابل بازرسی کند. برای بررسی «این topic branch چه deltaی نسبت به target دارد؟» باید comparison با همان سؤال سازگار باشد، نه صرفاً diffی که خروجی کوتاه‌تری تولید می‌کند.

Commit boundary snapshot index را به history ثبت می‌کند. commit message توضیح است، نه oracle محتوا. قبل از commit باید inspectable evidence داشته باشی که index همان review unit مورد نظر است.

Integration boundary بعد از merge یا integration تازه شروع می‌شود. موفقیت merge ثابت می‌کند Git histories را در آن operation ادغام کرده؛ verification رفتاری integrated state هنوز claim دیگری است.

در پایان، human gate یکی از ACCEPT، MODIFY، REJECT یا BOUNDED_DEFER را با rationale، limitation و non-claim ثبت می‌کند.

ساخت Daily Git Change Gate Record v1

رکورد را از evidence خام به decision بساز:

1. Base/target: repository، topic ref، target ref، HEAD و merge-base یا evidence معادل را ثبت کن. هدف اثبات یک branching model جهانی نیست؛ فقط باید ancestry مورد استفاده برای این task روشن باشد.
2. Observed boundaries: status/index/worktree و comparison مورد بررسی را ثبت کن. اگر delta نامرتبط یا نامشخص می‌بینی، آن را پنهان نکن.
3. Task-relevant diff: locator یا command/resultی بده که reviewer بتواند delta مورد claim را مستقل ببیند. اندازهٔ کوچک diff correctness نیست.
4. Commit intent: توضیح بده snapshot ثبت‌شده چرا همان review unit است. وجود commit یا پیام خوب، محتوا را تضمین نمی‌کند.
5. Pre-integration verification: check، result، state/fingerprint و limitation را ثبت کن. PASS فقط روی همان state و scope معتبر است.
6. Integration: روش، target state و نتیجهٔ Git operation را ثبت کن.
7. Post-integration verification: integrated state را دوباره بررسی کن. evidence قبل از merge را خودکار reuse نکن.
8. Decision: human decision، residual risk، non-claim و در صورت material بودن disclosure کمک AI/support را ثبت کن.

گیت زمانی بسته می‌شود که زنجیرهٔ evidence برای claim مورد نظر کافی باشد، نه وقتی تعداد commandها به حدی خاص برسد.

توضیح عمیق: چرا comparison درست مهم‌تر از ظاهر تمیز است

Git چند state را هم‌زمان مدل می‌کند. git diff بسته به آرگومان‌ها می‌تواند working tree، index یا commitها را مقایسه کند. بنابراین عبارت «diff را دیدم» ناقص است؛ باید بدانی کدام دو state را برای کدام سؤال مقایسه کردی.

همین منطق دربارهٔ commit صادق است. commit snapshot محتویات index را ثبت می‌کند. اگر unrelated change داخل index باشد، یک commit موفق همان unrelated delta را هم ثبت می‌کند. اگر intended change هنوز فقط در working tree باشد، commit ممکن است ناقص باشد. پس commit success فقط operation success است.

merge نیز historyها را ادغام می‌کند. conflict-free بودن می‌گوید Git در سطح merge operation نیاز به resolution متنی/ساختاری پیدا نکرده است؛ رفتار integrated code باید جداگانه آزمایش شود. یک تغییر جدید روی target می‌تواند بدون conflict وارد شود ولی invariant رفتاری را عوض کند.

به همین دلیل diagram این درس یک loop است: establish context → inspect boundary → bound diff → commit snapshot → verify → integrate → verify integrated state → human decision. هیچ arrowی از «Git success» مستقیماً به «accepted» نمی‌رود.

مثال کارشده: تغییر مستندات همراه با metadata تولیدشده

فرض کن task محدود، تغییر نام یک flag خط فرمان در مستندات کاربر است. snapshot شاخهٔ topic هم docs/usage.md را تغییر داده و هم یک index تولیدشدهٔ مستندات را. این index صرفاً به‌خاطر نام فایل داخل یا خارج scope نیست؛ رکورد باید با evidence مثل rule تولید، policy پروژه یا build قابل بازتولید نشان دهد که آیا این فایل بخشی از همان review unit است یا نه.

رکورد دفاع‌پذیر base و target را مشخص می‌کند، pathهای تغییرکرده و comparison واقعی را ثبت می‌کند و برای هر delta مهم basis scope می‌آورد. اگر authority کافی برای scope وجود ندارد، رکورد باید همان عدم قطعیت را حفظ کند و از filename، staging state یا commit message نتیجه‌گیری نکند.

اگر target از زمان شروع topic جلو رفته است، رفتار پیش از integration، نتیجهٔ واقعی عملیات Git و یک check تازه روی integrated state را سه observation جدا ثبت کن. نتیجهٔ integrated state را از clean status، موفقیت command یا topic-side check پیش‌بینی نکن؛ decision محدود باید از evidence جدید ساخته شود.

failure modeهای فریبنده

«branch درست است، پس base درست است.» نام branch ancestry را اثبات نمی‌کند. repair: target/ref و ancestry evidence را ثبت کن.

«status clean است، پس ready است.» clean فقط نبود deltaهای گزارش‌شده در working/index نسبت به HEAD را نشان می‌دهد؛ نمی‌گوید HEAD همان change صحیح است یا verification کافی دارد.

«commit message task را می‌گوید، پس commit همان task است.» message narrative است. repair: snapshot diff را inspect کن.

«diff کوچک است، پس امن است.» اندازه evidence نیست. repair: scope و behavior را جدا بررسی کن.

«merge conflict ندارد، پس integration سالم است.» conflict-free بودن behavioral compatibility را ثابت نمی‌کند. repair: integrated state را با check مستقل validate کن.

«AI گفت تغییر کم‌ریسک است.» AI می‌تواند hypothesis یا command پیشنهاد دهد، اما evidence و decision باید مستقل باشد. استفادهٔ material را disclose کن.

برای مهندس باتجربه: workflow آزاد است، invariantها ثابت‌اند

تیم تو ممکن است trunk-based development، short-lived branches، worktree، pull request، merge queue یا ابزار داخلی داشته باشد. این درس یک branching model واحد تحمیل نمی‌کند. مهم این invariantهاست:

• context و target قابل تعیین باشند؛
• changed-content boundary قابل بازبینی باشد؛
• commit/integration claim به snapshot واقعی وصل شود؛
• verification به state خودش bind باشد؛
• integrated state evidence تازه داشته باشد؛
• human decision و limitation صریح باشند.

می‌توانی command sequence دیگری استفاده کنی یا artifact را در سیستم داخلی mirror کنی، به شرط اینکه همان evidence bar حفظ شود. این درس history rewriting، backport و release-line policy را به FND-010 واگذار می‌کند و project-state handoff کامل را دوباره آموزش نمی‌دهد.

trade-offها بدون dogma

برای بعضی taskها comparison مستقیم target↔topic کافی است؛ در بعضی repositoryها generated files، submodules یا multiple worktrees هم باید در boundary بیایند. معیار، claim و evidence مورد نیاز است.

یک commit یا چند commit؟ این درس عدد ثابت نمی‌دهد. مهم این است که review unit inspectable باشد و unrelated delta در snapshot مورد پذیرش پنهان نشود.

merge یا rebase؟ این درس سیاست واحدی تعیین نمی‌کند. انتخاب باید با policy پروژه سازگار باشد و integrated result در هر حال verification مستقل بگیرد.

ACCEPT یا BOUNDED_DEFER؟ اگر technical evidence خوب است اما authority یا scope یک delta نامشخص است، defer محدود می‌تواند سالم‌تر از حدس باشد. scope تعویق و evidence گمشده باید مشخص باشند.

تمرین هدایت‌شده و transfer

در FND009-LAB1 ابتدا fixture را بساز و بدون تغییر repository evidence اولیه را capture کن. task brief را بخوان، branch/target/base را inspect کن، exact change boundary را بررسی کن و pre-integration check را ثبت کن. سپس artifact را کامل کن. command sequence اجباری نیست؛ evidence fields اجباری‌اند.

برای S2 باید Daily Git Change Gate Record v1 را با locatorهای واقعی پر کنی. narrative-only یا فهرست commandها کافی نیست.

برای transfer، یک fixture دوم با base متفاوت و staged boundary متفاوت دریافت می‌کنی. هیچ path classification یا integration assumption از case اول را کپی نکن. دوباره context، diff و verification را از evidence جدید بساز. invariantها ثابت‌اند؛ strategy باید با context تغییر کند.

حداقل evidence قابل دفاع

رکورد نهایی باید حداقل این‌ها را داشته باشد: repository/topic/target/head/base evidence، observed state boundary، task-relevant diff locator، commit snapshot/intent evidence، pre-integration check و covered state، integration result، post-integration check، residual limitation، human decision و non-claim.

Evidence باید قابلیت ابطال claim را داشته باشد. «همه چیز خوب است» evidence نیست. یک diff locator، object id، test output، file fingerprint یا equivalent observable artifact می‌تواند claim را محدود و قابل بازبینی کند.

اگر support یا AI materially روی انتخاب probe یا interpretation اثر گذاشته، disclosure را ثبت کن. نتیجهٔ ابزار یا AI authority نهایی نیست.

ارزیابی از retrieval تا transfer

S1 مفاهیم branch context، diff boundary و commit boundary را در یک case کوتاه جدا می‌کند.

S2 artifact مرکزی را از repository واقعی lab می‌سازد و همهٔ نتیجه‌های blocking را به evidence متصل می‌کند.

S3 اولین promotion نامعتبر از Git-success به correctness/acceptance را پیدا می‌کند و probe متمایزکننده پیشنهاد می‌دهد.

S4 با evidence موجود یکی از چهار decision enum را انتخاب می‌کند و limitation و non-claim را ثبت می‌کند.

S5 روش را در repository تغییرکرده دوباره اجرا می‌کند؛ base، staging و integration context جدید است و commandهای حفظی کافی نیستند.

چهار dimension بحرانی—technical state/history، traceability، human judgment/limitations و transfer—non-compensatory هستند.

منابع و freshness boundary

claimهای current فنی این درس به مستندات رسمی Git محدودند: git switch برای branch/worktree context، git diff برای comparison semantics، git commit برای ثبت snapshot index، و git merge برای ادغام historyها و conflict handling. هیچ‌کدام به‌عنوان correctness یا release authority استفاده نمی‌شوند.

منابع قفل‌شده در 2026-09-02 بازیابی شده‌اند و review_due آن‌ها 2026-10-17 است. در تاریخ authoring این stage refresh لازم نیست. اگر source materially تغییر کند، review_due بگذرد یا claim فنی تازه‌ای خارج از research map اضافه شود، source verification باید دوباره انجام شود.

سیاست evidence gate این درس یک DESIGN claim در MAKNOW است، نه ادعای جهانی دربارهٔ Git workflow.