GIT-FAST-EXPORT(1) Git Manual GIT-FAST-EXPORT(1)

git-fast-export - صادرکننده داده‌های گیت

git fast-export [<options>] | git fast-import

این برنامه ویرایش‌های داده‌شده را در قالبی مناسب برای هدایت از طریق لوله (pipe) به git fast-import تخلیه می‌کند.

می‌توانید از آن به عنوان یک جایگزین قابل خواندن برای انسان به جای باندل (ببینید git-bundle(1))، یا به عنوان قالبی که می‌تواند پیش از ارسال به git fast-import جهت بازنویسی تاریخچه ویرایش شود (قابلیتی که ابزارهایی مانند git filter-repo به آن متکی هستند) استفاده کنید.

--progress=<n>

درج عبارت‌های progress به ازای هر <n> شیء، تا توسط git fast-import در حین واردسازی نمایش داده شوند.

--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)

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

هنگام درخواست abort (که حالت پیش‌فرض است)، این برنامه در صورت مواجهه با یک برچسب امضاشده متوقف می‌شود. با strip، برچسب‌ها بدون هشدار به حالت فاقد امضا تبدیل می‌شوند، با warn-strip فاقد امضا می‌شوند اما یک هشدار نمایش داده می‌شود، با verbatim، بدون هشدار صادر می‌گردند و با warn-verbatim (یا warn، یک مترادف منسوخ)، صادر می‌شوند اما هشداری مشاهده خواهید کرد. verbatim و warn-verbatim تنها زمانی باید استفاده شوند که بدانید هیچ دگرگونی مؤثر بر برچسب‌ها یا کامیت‌های موجود در تاریخچه آنها توسط شما یا توسط fast-export یا fast-import انجام نخواهد شد، یا برایتان مهم نباشد که برچسب حاصل دارای امضای نامعتبر باشد.

--signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort)

نحوه مدیریت کامیت‌های امضاشده را مشخص می‌کند. دقیقاً مانند --signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort) رفتار می‌کند، اما برای کامیت‌ها. پیش‌فرض strip است، که مشابه رفتار نسخه‌های قبلی این دستور بدون این گزینه است.

هنگام صدور، یک امضا با عبارت زیر آغاز می‌شود:

gpgsig <git-hash-algo> <signature-format>

که در آن <git-hash-algo> هش شیء گیت است (یعنی "sha1" یا "sha256")، و <signature-format> نوع امضا است، یعنی "openpgp"، "x509"، "ssh" یا "unknown".

برای مثال، یک امضای OpenPGP روی یک کامیت SHA-1 با gpgsig sha1 openpgp آغاز می‌شود، در حالی که یک امضای SSH روی یک کامیت SHA-256 با gpgsig sha256 ssh شروع می‌گردد.

در حالی که تمام امضاهای یک کامیت صادر می‌شوند، ممکن است یک واردکننده ترجیح دهد فقط برخی از آنها را بپذیرد. به عنوان مثال git-fast-import(1) در حال حاضر حداکثر یک امضا به ازای هر الگوریتم هش گیت در هر کامیت ذخیره می‌کند.


نکته
این قابلیت کاملاً آزمایشی است و قالب جریان داده ممکن است در آینده بدون تضمین سازگاری تغییر کند.

--tag-of-filtered-object=(abort|drop|rewrite)

نحوه مدیریت برچسب‌هایی را مشخص می‌کند که شیء برچسب‌خورده آنها فیلتر شده است. از آنجا که ویرایش‌ها و فایل‌ها برای صدور را می‌توان با مسیر محدود کرد، ممکن است اشیاء برچسب‌خورده کاملاً فیلتر و حذف شوند.

هنگام درخواست abort (که حالت پیش‌فرض است)، این برنامه هنگام مواجهه با چنین برچسبی متوقف می‌شود. با drop چنین برچسب‌هایی را از خروجی حذف می‌کند. با rewrite، اگر شیء برچسب‌خورده یک کامیت باشد، برچسب را بازنویسی می‌کند تا به یک کامیت والد یا نیا اشاره کند (از طریق بازنویسی والد؛ ببینید git-rev-list(1)).

-M, -C

تشخیص جابه‌جایی و/یا کپی را همان‌طور که در صفحه راهنمای git-diff(1) شرح داده شده انجام می‌دهد، و از آن برای تولید دستورات تغییر نام و کپی در خروجی تخلیه‌شده استفاده می‌کند.

توجه داشته باشید که نسخه‌های قدیمی‌تر این دستور در صورت تعیین این گزینه‌ها خطایی صادر نمی‌کردند و نتایج نادرستی ایجاد می‌کردند.

--export-marks=<file>

پس از تکمیل، جدول نشان‌های داخلی را در <file> تخلیه می‌کند. نشان‌ها به صورت یک مورد در هر سطر با ساختار :markid SHA-1 نوشته می‌شوند. تنها نشان‌های مربوط به ویرایش‌ها تخلیه می‌شوند؛ نشان‌های مربوط به blobها نادیده گرفته می‌شوند. بک‌اندها می‌توانند از این فایل برای اعتبارسنجی واردسازی‌ها پس از تکمیل، یا ذخیره جدول نشان‌ها در سراسر اجراهای افزایشی استفاده کنند. از آنجا که <file> تنها در زمان تکمیل باز و خلاصه می‌شود، همان مسیر را می‌توان با خیال راحت به --import-marks=<file> نیز داد. اگر شیء جدیدی نشان‌گذاری/صادر نشده باشد، این فایل نوشته نخواهد شد.

--import-marks=<file>

پیش از پردازش هرگونه ورودی، نشان‌های مشخص‌شده در <file> را بارگذاری می‌کند. فایل ورودی باید موجود باشد، قابل خواندن باشد، و از همان قالبی که توسط --export-marks=<file> تولید شده استفاده کند.

--mark-tags

علاوه بر نشانه‌گذاری blobها و کامیت‌ها با شناسه‌های نشان، برچسب‌ها را نیز نشانه‌گذاری می‌کند. این قابلیت در ترکیب با --export-marks=<file> و --import-marks=<file> مفید است، و همچنین برای صدور برچسب‌های تو در تو سودمند (و ضروری) است. به موارد دیگر آسیبی نمی‌رساند و می‌توانست حالت پیش‌فرض باشد، اما بسیاری از فرانت‌اندهای fast-import برای پذیرش برچسب‌های دارای شناسه‌های نشان آماده نیستند.

هر کامیت (یا برچسبی) که از قبل نشانه‌گذاری شده باشد مجدداً صادر نخواهد شد. اگر بک‌اند از فایل --import-marks=<file> مشابهی استفاده کند، این ویژگی با یکسان نگه داشتن نشان‌ها در طول اجراها، امکان صدور افزایشی دوطرفه مخزن را فراهم می‌سازد.

--fake-missing-tagger

برخی مخازن قدیمی دارای برچسب‌هایی بدون ثبت‌کننده برچسب (tagger) هستند. پروتکل fast-import در این خصوص سخت‌گیر بود و آن را مجاز نمی‌شمرد. بنابراین یک ثبت‌کننده ساختگی ایجاد می‌کند تا خروجی بتواند به کمک fast-import وارد شود.

--use-done-feature

جریان داده را با عبارت feature done شروع کرده و آن را با دستور done خاتمه دهید.

--no-data

از خروجی اشیاء blob صرف‌نظر کرده و در عوض به blobها از طریق هش اصلی SHA-1 آنها ارجاع دهید. این گزینه هنگام بازنویسی ساختار دایرکتوری یا تاریخچه یک مخزن بدون دستکاری محتوای فایل‌های جداگانه کاربرد دارد. توجه داشته باشید که جریان حاصل تنها توسط مخزنی قابل استفاده است که از قبل شامل اشیاء لازم باشد.

--full-tree

این گزینه باعث می‌شود fast-export یک دستورالعمل "deleteall" برای هر کامیت صادر کند و به دنبال آن لیست کاملی از تمام فایل‌های کامیت آورده شود (برخلاف حالت عادی که فقط فایل‌های متفاوت با والد اول کامیت فهرست می‌شوند).

--anonymize

محتوای مخزن را ناشناس می‌سازد در حالی که همچنان ساختار تاریخچه و درخت ذخیره‌شده را حفظ می‌کند. بخش ANONYMIZING در ادامه را ببینید.

--anonymize-map

تبدیل نشانه <from> به <to> در خروجی ناشناس‌شده. اگر <to> حذف شود، <from> به خودش نگاشت می‌شود (یعنی ناشناس نمی‌شود). بخش ANONYMIZING در ادامه را ببینید.

--reference-excluded-parents

به طور پیش‌فرض، اجرای دستوری مانند git fast-export master~5..master کامیت master~5 را شامل نمی‌شود و باعث می‌شود master~4 دیگر master~5 را به عنوان والد نداشته باشد (اگرچه هر دو master~4 قدیمی و master~4 جدید تمام فایل‌های یکسان را خواهند داشت). از --reference-excluded-parents استفاده کنید تا جریان در عوض به کامیت‌های موجود در محدوده مستثنی‌شده تاریخچه با sha1sum آنها ارجاع دهد. توجه داشته باشید که جریان حاصل تنها توسط مخزنی قابل استفاده است که از قبل شامل کامیت‌های والد لازم باشد.

--show-original-ids

افزودن یک دستورالعمل اضافی به خروجی برای کامیت‌ها و blobها، به صورت original-oid <SHA1SUM>. در حالی که چنین دستورالعمل‌هایی احتمالاً توسط واردکنندگانی مانند git-fast-import نادیده گرفته می‌شوند، ممکن است برای فیلترهای واسط (مانند بازنویسی پیام‌های کامیت که به کامیت‌های قدیمی‌تر اشاره دارند، یا حذف blobها بر اساس شناسه) مفید باشند.

--reencode=(yes|no|abort)

نحوه مدیریت هدر encoding در اشیاء کامیت را مشخص می‌کند. هنگام درخواست abort (که حالت پیش‌فرض است)، این برنامه هنگام مواجهه با چنین شیء کامیتی متوقف می‌شود. با yes، پیام کامیت مجدداً به UTF-8 کدگذاری می‌شود. با no، کدگذاری اصلی حفظ خواهد شد.

--refspec

اعمال refspec مشخص‌شده بر روی هر مرجع صادرشده. چندین مورد از آن را می‌توان مشخص کرد.

[<git-rev-list-args>...]

فهرستی از آرگومان‌ها، قابل قبول برای git rev-parse و git rev-list، که اشیاء و مراجع خاص را برای صدور مشخص می‌کند. به عنوان مثال، master~10..master باعث می‌شود مرجع جاری master به همراه تمام اشیاء اضافه‌شده از دهمین کامیت نیا صادر شود و (مگر اینکه گزینه --reference-excluded-parents تعیین شده باشد) تمام فایل‌های مشترک با master~9 و master~10 صادر گردند.

$ git fast-export --all | (cd /empty/repository && git fast-import)

این دستور کل مخزن را صادر کرده و آن را به مخزن خالی موجود وارد می‌کند. به جز بازکدگذاری کامیت‌هایی که در قالب UTF-8 نیستند، یک بازتاب نظیر به نظیر خواهد بود.

$ git fast-export master~5..master |
        sed "s|refs/heads/master|refs/heads/other|" |
        git fast-import

این دستور یک شاخه جدید به نام other از master~5..master ایجاد می‌کند (یعنی اگر master دارای تاریخچه خطی باشد، ۵ کامیت آخر را در نظر می‌گیرد).

توجه داشته باشید که این فرض می‌کند هیچ‌یک از blobها و پیام‌های کامیت ارجاع‌شده در آن بازه ویرایشی شامل رشته refs/heads/master نباشند.

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

با این گزینه، گیت تمام نام‌های مراجع، مسیرها، محتوای blob، پیام‌های کامیت و برچسب، نام‌ها و نشانی‌های ایمیل را در خروجی با داده‌های ناشناس جایگزین می‌کند. دو نمونه از یک رشته یکسان به طور معادل جایگزین می‌شوند (مثلاً دو کامیت با نویسنده یکسان در خروجی دارای نویسنده ناشناس یکسانی خواهند بود، اما هیچ شباهتی به رشته نویسنده اصلی نخواهد داشت). ارتباط میان کامیت‌ها، شاخه‌ها و برچسب‌ها حفظ می‌شود، همچنین برچسب‌های زمانی کامیت (اما پیام‌های کامیت و نام مراجع شباهتی به نسخه‌های اصلی ندارند). ترکیب نسبی درخت حفظ می‌شود (برای مثال، اگر یک درخت ریشه با ۱۰ فایل و ۳ درخت دارید، خروجی نیز به همان شکل خواهد بود)، اما نام‌ها و محتوای فایل‌ها جایگزین خواهند شد.

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

$ git fast-export --anonymize --all >anon-stream

سپس بررسی و تأیید کنید که آیا باگ در مخزن ایجادشده از آن جریان نیز پابرجا می‌ماند (بسیاری از اشکالات باقی نخواهند ماند، چرا که واقعاً به محتوای دقیق مخزن وابسته‌اند):

$ git init anon-repo
$ cd anon-repo
$ git fast-import <../anon-stream
$ ... test your bug ...

اگر مخزن ناشناس‌شده باگ را نشان دهد، ممکن است ارزش داشته باشد که anon-stream را همراه با یک گزارش باگ معمولی به اشتراک بگذارید. توجه داشته باشید که جریان ناشناس بسیار خوب فشرده می‌شود، بنابراین فشرده‌سازی آن با gzip توصیه می‌شود. اگر می‌خواهید جریان را بررسی کنید تا ببینید حاوی داده‌های خصوصی نباشد، می‌توانید قبل از ارسال مستقیماً آن را بررسی نمایید. همچنین ممکن است بخواهید موارد زیر را امتحان کنید:

$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less

که تمام خطوط یکتا را نشان می‌دهد (با اعدادی که به "X" تبدیل شده‌اند تا "User 0"، "User 1" و غیره به صورت "User X" خلاصه شوند). این امر خروجی بسیار کوچک‌تری تولید می‌کند و معمولاً تأیید سریع عدم وجود داده‌های خصوصی در جریان را آسان می‌سازد.

بازتولید برخی از باگ‌ها ممکن است مستلزم ارجاع به کامیت‌ها یا مسیرهای خاصی باشد، که این امر پس از ناشناس‌سازی نام مراجع و مسیرها دشوار می‌شود. می‌توانید درخواست کنید که یک نشانه خاص همان‌طور که هست باقی بماند یا به یک مقدار جدید نگاشت شود. به عنوان مثال، اگر باگی دارید که با git rev-list sensitive -- secret.c بازتولید می‌شود، می‌توانید دستور زیر را اجرا کنید:

$ git fast-export --anonymize --all \
      --anonymize-map=sensitive:foo \
      --anonymize-map=secret.c:bar.c \
      >stream

پس از واردسازی جریان، سپس می‌توانید git rev-list foo -- bar.c را در مخزن ناشناس‌شده اجرا کنید.

توجه داشته باشید که مسیرها و نام مراجع در مرزهای اسلش به نشانه‌ها تقسیم می‌شوند. دستور فوق subdir/secret.c را به چیزی شبیه path123/bar.c ناشناس می‌کند؛ سپس می‌توانید bar.c را در مخزن ناشناس جستجو کنید تا نام مسیر نهایی مشخص شود.

برای ساده‌تر کردن ارجاع به نام مسیر نهایی، می‌توانید هر بخش مسیر را نگاشت کنید؛ بنابراین اگر subdir را نیز به publicdir ناشناس کنید، نام مسیر نهایی publicdir/bar.c خواهد بود.

از آنجا که git fast-import نمی‌تواند درخت‌ها را برچسب‌گذاری کند، قادر نخواهید بود مخزن linux.git را به طور کامل صادر کنید، زیرا حاوی برچسبی است که به جای یک کامیت به یک درخت اشاره دارد.

git-fast-import(1)

بخشی از مجموعه git(1)

2026-06-29 Git 2.55.0