GIT-ARCHIVE(1)                    Git Manual                    GIT-ARCHIVE(1)

نام (NAME)
       git-archive - ساخت بایگانی از فایل‌های یک درخت مشخص

خلاصه دستور (SYNOPSIS)
       git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
                     [-o <file> | --output=<file>] [--worktree-attributes]
                     [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
                     [<path>...]


توضیحات (DESCRIPTION)
       یک بایگانی با قالب مشخص‌شده که شامل ساختار درختیِ درخت نام‌برده است ایجاد
       کرده و آن را در خروجی استاندارد می‌نویسد. در صورت تعیین <prefix>، این
       پیشوند به ابتدای نام فایل‌ها در بایگانی اضافه می‌شود.

       رفتار git archive هنگامی که یک شناسه درخت (tree ID) به آن داده می‌شود در
       مقایسه با زمانی که شناسه کامیت (commit ID) یا شناسه برچسب (tag ID) داده
       می‌شود متفاوت است. وقتی شناسه درخت داده شود، از زمان فعلی به عنوان زمان
       تغییر هر فایل در بایگانی استفاده می‌شود. از سوی دیگر، وقتی شناسه کامیت
       یا برچسب مشخص شود، از زمان کامیت ثبت‌شده در شیء کامیت ارجاع‌شده استفاده
       خواهد شد. علاوه بر این، در صورت استفاده از قالب tar، شناسه کامیت در یک
       هدر pax سراسری گسترش‌یافته ذخیره می‌شود؛ این مقدار را می‌توان با استفاده
       از git get-tar-commit-id استخراج کرد. در فایل‌های ZIP نیز به عنوان توضیح
       فایل (file comment) ذخیره می‌شود.

گزینه‌ها (OPTIONS)
       --format=<fmt>
           قالب بایگانی خروجی. مقادیر ممکن عبارتند از tar، zip، tar.gz، tgz، و
           هر قالبی که با استفاده از گزینه پیکربندی tar.<format>.command تعریف
           شده باشد. اگر --format مشخص نشده باشد و فایل خروجی تعیین شده باشد،
           در صورت امکان قالب از نام فایل برداشت می‌شود (برای مثال، نوشتن در
           foo.zip باعث می‌شود خروجی در قالب zip باشد). در غیر این صورت، قالب
           خروجی tar خواهد بود.

       -l, --list
           نمایش تمامی قالب‌های موجود.

       -v, --verbose
           گزارش روند پیشرفت در خروجی خطای استاندارد (stderr).

       --prefix=<prefix>/
           افزودن پیشوند <prefix>/ به ابتدای مسیرها در بایگانی. می‌تواند تکرار
           شود؛ راست‌ترین مقدار آن برای تمام فایل‌های ردگیری‌شده استفاده می‌شود.
           برای اطلاع از اینکه کدام مقدار توسط --add-file استفاده می‌شود، به
           توضیحات زیر مراجعه کنید.

           مقدار <prefix> دقیقاً همان‌طور که وارد شده استفاده می‌شود و نرمال‌سازی
           نمی‌شود. ممکن است شامل اسلش‌های ابتدایی یا مؤلفه‌های دایرکتوری والد
           باشد (مانند ../). برخی از برنامه‌های مصرف‌کننده بایگانی ممکن است چنین
           مسیرهایی را بالقوه ناامن تلقی کرده و در زمان استخراج، آنها را اصلاح
           کنند یا هشدار دهند.

       -o <file>, --output=<file>
           نوشتن بایگانی در <file> به جای خروجی استاندارد (stdout).

       --add-file=<file>
           افزودن یک فایل ردگیری‌نشده به بایگانی. برای افزودن چندین فایل می‌توان
           آن را تکرار کرد. مسیر فایل در بایگانی با الحاق مقدار آخرین گزینه
           --prefix (در صورت وجود) پیش از این --add-file و نام پایه (basename)
           فایل <file> ساخته می‌شود.

       --add-virtual-file=<path>:<content>
           افزودن محتوای مشخص‌شده به بایگانی. برای افزودن چندین فایل می‌توان آن
           را تکرار کرد.

           آرگومان <path> می‌تواند با یک نویسه گیومه دوتایی شروع و پایان یابد؛
           نام فایل درون آن به عنوان یک رشته به سبک C تفسیر می‌شود، یعنی بک‌اسلش
           به عنوان نویسه اسکیپ تعبیر می‌گردد. اگر مسیر شامل دونقطه (:) باشد،
           باید درون گیومه قرار گیرد تا از اشتباه گرفته شدن دونقطه به عنوان
           جداکننده بین مسیر و محتوا جلوگیری شود، یا اگر مسیر با نویسه گیومه
           شروع یا تمام شود نیز باید درون گیومه باشد.

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

           توجه داشته باشید که برخلاف --add-file، مسیر ایجادشده در بایگانی تحت
           تأثیر گزینه --prefix قرار نمی‌گیرد، زیرا یک <path> کامل می‌تواند به
           عنوان مقدار این گزینه داده شود.

       --worktree-attributes
           جستجوی مشخصه‌ها در فایل‌های .gitattributes در درخت کاری نیز (به بخش
           “مشخصه‌ها (ATTRIBUTES)” مراجعه کنید).

       --mtime=<time>
           تنظیم زمان تغییر (mtime) ورودی‌های بایگانی. بدون این گزینه، در صورتی
           که <tree-ish> یک کامیت یا برچسب باشد از زمان کامیت‌کننده (committer
           time) استفاده می‌شود و اگر یک درخت باشد از زمان فعلی استفاده خواهد
           شد.

       <extra>
           می‌تواند هر گزینه‌ای باشد که بخش پشتیبان (backend) بایگانی‌ساز آن را
           درک می‌کند. بخش بعدی را ببینید.

       --remote=<repo>
           به جای ساخت بایگانی tar از مخزن محلی، یک بایگانی tar را از یک مخزن
           دوردست (ریموت) دریافت می‌کند. توجه داشته باشید که مخزن دوردست ممکن
           است محدودیت‌هایی در مورد اینکه کدام عبارت‌های sha1 در <tree-ish> مجاز
           هستند اعمال کند. برای جزئیات به git-upload-archive(1) مراجعه کنید.

       --exec=<git-upload-archive>
           همراه با --remote برای مشخص کردن مسیر به git-upload-archive در سمت
           دوردست استفاده می‌شود.

       <tree-ish>
           درخت یا کامیت مورد نظر برای تولید بایگانی.

       <path>
           بدون پارامتر اختیاری مسیر، تمام فایل‌ها و زیردایرکتوری‌های دایرکتوری
           کاری فعلی در بایگانی گنجانده می‌شوند. اگر یک یا چند مسیر مشخص شود،
           فقط این مسیرها گنجانده خواهند شد.

گزینه‌های اضافی بخش پشتیبان (BACKEND EXTRA OPTIONS)
   zip
       -<digit>
           تعیین سطح فشرده‌سازی. مقادیر بزرگ‌تر به دستور اجازه می‌دهند تا زمان
           بیشتری را برای فشرده‌سازی به اندازه کوچک‌تر صرف کند. مقادیر
           پشتیبانی‌شده از -0 (فقط ذخیره/بدون فشرده‌سازی) تا -9 (بهترین ضریب
           فشرده‌سازی) هستند. در صورت تعیین نشدن، پیش‌فرض -6 است.

   tar
       -<number>
           تعیین سطح فشرده‌سازی. این مقدار به دستور فشرده‌سازی پیکربندی‌شده در
           tar.<format>.command ارسال خواهد شد. برای اطلاع از فهرست سطوح
           پشتیبانی‌شده و سطح پیش‌فرض در صورت مشخص نشدن این گزینه، به صفحه
           راهنمای دستور پیکربندی‌شده مراجعه کنید.

پیکربندی (CONFIGURATION)
       tar.umask
           این متغیر می‌تواند برای محدود کردن بیت‌های دسترسی ورودی‌های بایگانی
           tar استفاده شود. پیش‌فرض 0002 است که بیت نوشتن برای همگان (world
           write) را خاموش می‌کند. مقدار ویژه "user" نشان می‌دهد که به جای آن از
           umask کاربر بایگانی‌کننده استفاده خواهد شد. برای جزئیات به umask(2)
           مراجعه کنید. اگر --remote استفاده شود، تنها پیکربندی مخزن دوردست
           اعمال می‌شود.

       tar.<format>.command
           این متغیر یک دستور پوسته را مشخص می‌کند که خروجی tar تولیدشده توسط
           git archive باید از طریق پایپ به آن هدایت شود. دستور با استفاده از
           پوسته اجرا می‌شود و فایل tar تولیدشده در ورودی استاندارد آن قرار
           می‌گیرد، و باید خروجی نهایی را در خروجی استاندارد خود تولید کند. هر
           گزینه‌ای مربوط به سطح فشرده‌سازی به دستور ارسال خواهد شد (مانند -9).

           قالب‌های tar.gz و tgz به طور خودکار تعریف شده‌اند و به طور پیش‌فرض از
           دستور جادویی git archive gzip استفاده می‌کنند که یک پیاده‌سازی داخلی
           از gzip را فراخوانی می‌کند.

       tar.<format>.remote
           در صورت true بودن، قالب را برای استفاده کلاینت‌های دوردست از طریق
           git-upload-archive(1) فعال می‌کند. پیش‌فرض برای قالب‌های تعریف‌شده توسط
           کاربر false است، اما برای قالب‌های tar.gz و tgz برابر true می‌باشد.

مشخصه‌ها (ATTRIBUTES)
       export-ignore
           فایل‌ها و دایرکتوری‌های دارای مشخصه export-ignore به فایل‌های بایگانی
           اضافه نخواهند شد. برای جزئیات به gitattributes(5) مراجعه کنید.

       export-subst
           اگر مشخصه export-subst برای فایلی تنظیم شده باشد، گیت هنگام افزودن
           این فایل به بایگانی چندین جانگهدار (placeholder) را بسط می‌دهد. برای
           جزئیات به gitattributes(5) مراجعه کنید.

       توجه داشته باشید که مشخصه‌ها به طور پیش‌فرض از فایل‌های .gitattributes در
       درختی که در حال بایگانی است گرفته می‌شوند. اگر می‌خواهید نحوه تولید خروجی
       را پس از واقعه تغییر دهید (مثلاً بدون افزودن export-ignore مناسب در
       .gitattributes آن، کامیت کرده‌اید)، فایل .gitattributes خارج‌شده (checked
       out) را بر حسب نیاز تنظیم کنید و از گزینه --worktree-attributes استفاده
       نمایید. متناوباً می‌توانید مشخصه‌های لازم را که باید هنگام بایگانی هر
       درختی اعمال شوند در فایل $GIT_DIR/info/attributes خود نگه دارید.

مثال‌ها (EXAMPLES)
       git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf
       -)
           ایجاد یک بایگانی tar شامل محتویات آخرین کامیت روی شاخه فعلی، و
           استخراج آن در دایرکتوری /var/tmp/junk.

       git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip
       >git-1.4.0.tar.gz
           ایجاد یک فایل فشرده tarball برای نسخه انتشار v1.4.0.

       git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0
       >git-1.4.0.tar.gz
           مشابه مورد بالا، اما با استفاده از مدیریت داخلی tar.gz.

       git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0
           مشابه مورد بالا، اما قالب از فایل خروجی استنباط می‌شود.

       git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip
       >git-1.4.0.tar.gz
           ایجاد یک فایل فشرده tarball برای نسخه انتشار v1.4.0، اما بدون هدر
           سراسری گسترش‌یافته pax.

       git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ >
       git-1.4.0-docs.zip
           قرار دادن همه‌چیز در دایرکتوری Documentation/ مربوط به HEAD فعلی در
           git-1.4.0-docs.zip، با پیشوند git-docs/.

       git archive -o latest.zip HEAD
           ایجاد یک بایگانی Zip شامل محتویات آخرین کامیت در شاخه فعلی. توجه
           داشته باشید که قالب خروجی از پسوند فایل خروجی استنباط می‌شود.

       git archive -o latest.tar --prefix=build/ --add-file=configure
       --prefix= HEAD
           ایجاد یک بایگانی tar شامل محتویات آخرین کامیت در شاخه فعلی بدون
           پیشوند، و فایل ردگیری‌نشده configure با پیشوند build/.

       git config tar.tar.xz.command "xz -c"
           پیکربندی قالب "tar.xz" برای ساخت فایل‌های tar فشرده‌شده با LZMA.
           می‌توانید با مشخص کردن --format=tar.xz یا با ایجاد یک فایل خروجی
           مانند -o foo.tar.xz از آن استفاده کنید.

همچنین ببینید (SEE ALSO)
       gitattributes(5)

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

Git 2.55.0                        2026-06-29                    GIT-ARCHIVE(1)