GIT-CAT-FILE(1) Git Manual GIT-CAT-FILE(1)

git-cat-file - ارائه محتوا یا جزئیات اشیاء مخزن

git cat-file <type> <object>
git cat-file (-e | -p | -t | -s) <object>
git cat-file (--textconv | --filters)
             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
             [--buffer] [--follow-symlinks] [--unordered]
             [--textconv | --filters] [-Z]

خروجی دادن محتویات یا ویژگی‌های دیگر مانند اندازه، نوع یا اطلاعات دلتا (delta) برای یک یا چند شیء.

این دستور بسته به اینکه گزینه‌ای از خانواده --batch مشخص شده باشد یا خیر، می‌تواند در دو حالت عمل کند.

در حالت غیردسته‌ای (non-batch)، دستور اطلاعات مربوط به شیئی را ارائه می‌دهد که نام آن در خط فرمان ذکر شده است.

در حالت دسته‌ای (batch)، آرگومان‌ها از ورودی استاندارد خوانده می‌شوند.

<object>

نام شیئی که باید نمایش داده شود. برای فهرست کامل‌تری از روش‌های نگارش نام اشیاء، بخش «مشخص کردن بازنگری‌ها» (SPECIFYING REVISIONS) را در gitrevisions(7) ببینید.

-t

به جای محتوا، نوع شیء مشخص‌شده توسط <object> را نشان می‌دهد.

-s

به جای محتوا، اندازه شیء مشخص‌شده توسط <object> را نشان می‌دهد. در صورت استفاده با گزینه --use-mailmap، اندازه شیء به‌روزرسانی‌شده را پس از جایگزینی هویت‌ها با سازوکار mailmap نشان خواهد داد.

-e

اگر <object> وجود داشته باشد و یک شیء معتبر باشد، با وضعیت صفر خارج می‌شود. اگر <object> دارای قالبی نامعتبر باشد، با وضعیت غیر صفر خارج شده و خطایی را در stderr منتشر می‌کند.

-p

محتوای <object> را بر اساس نوع آن به صورت خوانا (pretty-print) نمایش می‌دهد.

<type>

به طور معمول این با نوع واقعی <object> مطابقت دارد، اما درخواست نوعی که بتوان آن را به سادگی از <object> داده‌شده ارجاع‌زدایی (dereference) کرد نیز مجاز است. برای مثال می‌توان برای <object> که یک شیء کامیت حاوی آن است درخواست "tree" کرد، یا برای <object> که یک شیء تگ اشاره‌کننده به آن است درخواست "blob" نمود.

--mailmap, --no-mailmap, --use-mailmap, --no-use-mailmap

استفاده از فایل mailmap برای نگاشت نام‌ها و آدرس‌های ایمیل نویسنده، کامیت‌کننده و ایجادکننده تگ به نام‌ها و آدرس‌های ایمیل استاندارد. نگاه کنید به git-shortlog(1).

--textconv

نمایش محتوا به صورتی که توسط یک فیلتر textconv تبدیل شده است. در این حالت، <object> باید به شکل <tree-ish>:<path>، یا :<path> باشد تا فیلتر بر محتوای ثبت‌شده در ایندکس در مسیر <path> اعمال شود.

--filters

نمایش محتوا به صورتی که توسط فیلترهای پیکربندی‌شده در درخت کاری فعلی برای مسیر داده‌شده <path> تبدیل شده است (یعنی فیلترهای smudge، تبدیل انتهای خط و غیره). در این حالت، <object> باید به شکل <tree-ish>:<path>، یا :<path> باشد.

--filter=<filter-spec>, --no-filter

حذف اشیاء از فهرست اشیاء چاپ‌شده. این گزینه تنها در ترکیب با یکی از حالت‌های دسته‌ای قابل استفاده است. اشیاء مستثنی‌شده‌ای که به صراحت از طریق هر یک از حالت‌های دسته‌ای که اشیاء را از ورودی استاندارد می‌خوانند (--batch، --batch-check) درخواست شده‌اند، به عنوان "filtered" گزارش خواهند شد. اشیاء مستثنی‌شده در حالت --batch-all-objects اصلاً چاپ نخواهند شد. <filter-spec> می‌تواند یکی از موارد زیر باشد:

قالب --filter=blob:none تمامی blobها را حذف می‌کند.

قالب --filter=blob:limit=<n>[kmg] اشیاء blob با اندازه حداقل n بایت یا واحد را حذف می‌کند. n ممکن است صفر باشد. پسوندهای k، m و g می‌توانند برای نام‌گذاری واحدها بر حسب KiB، MiB یا GiB استفاده شوند. برای مثال، blob:limit=1k همانند blob:limit=1024 است.

قالب --filter=object:type=(tag|commit|tree|blob) تمامی اشیائی را که از نوع درخواستی نیستند حذف می‌کند.

--path=<path>

جهت استفاده با --textconv یا --filters، برای امکان تعیین نام شیء و مسیر به طور جداگانه؛ به عنوان مثال زمانی که تشخیص ویرایشی که blob از آن آمده دشوار است.

--batch, --batch=<format>

چاپ اطلاعات و محتویات هر شیء ارائه‌شده در stdin. نباید با هیچ گزینه یا آرگومان دیگری به جز --textconv، --filters، یا --use-mailmap ترکیب شود.
•هنگام استفاده با --textconv یا --filters، خطوط ورودی باید مسیر را که با فاصله خالی جدا شده است مشخص کنند. برای جزئیات بخش خروجی دسته‌ای (BATCH OUTPUT) را در زیر ببینید.
•هنگام استفاده با --use-mailmap، برای اشیاء کامیت و تگ، بخش محتوای خروجی هویت‌های جایگزین‌شده با سازوکار mailmap را نشان می‌دهد، در حالی که بخش اطلاعات خروجی اندازه شیء را به گونه‌ای نشان می‌دهد که گویی در واقع هویت‌های جایگزین را ثبت کرده است.

--batch-check, --batch-check=<format>

چاپ اطلاعات مربوط به هر شیء ارائه‌شده در stdin. نباید با هیچ گزینه یا آرگومان دیگری به جز --textconv، --filters یا --use-mailmap ترکیب شود.
•هنگام استفاده با --textconv یا --filters، خطوط ورودی باید مسیر را که با فاصله جدا شده است مشخص کنند. برای جزئیات بخش خروجی دسته‌ای (BATCH OUTPUT) را در زیر ببینید.
•هنگام استفاده با --use-mailmap، برای اشیاء کامیت و تگ، اطلاعات چاپ‌شده شیء اندازه آن را به گونه‌ای نشان می‌دهد که گویی هویت‌های ثبت‌شده در آن توسط سازوکار mailmap جایگزین شده‌اند.

--batch-command, --batch-command=<format>

ورود به حالت دستوری که دستورات و آرگومان‌ها را از stdin می‌خواند. تنها می‌تواند با --buffer، --textconv، --use-mailmap یا --filters ترکیب شود.
•هنگام استفاده با --textconv یا --filters، خطوط ورودی باید مسیر را با فاصله مشخص کنند. برای جزئیات بخش خروجی دسته‌ای (BATCH OUTPUT) را در زیر ببینید.
•هنگام استفاده با --use-mailmap، برای اشیاء کامیت و تگ، دستور contents هویت‌های جایگزین‌شده با سازوکار mailmap را نشان می‌دهد، در حالی که دستور info اندازه شیء را طوری نشان می‌دهد که گویی واقعاً هویت‌های جایگزین‌شده را ثبت کرده است.

--batch-command دستورات زیر را شناسایی می‌کند:

contents <object>

چاپ محتویات شیء برای ارجاع <object>. این معادل خروجی --batch است.

info <object>

چاپ اطلاعات شیء برای ارجاع <object>. این معادل خروجی --batch-check است.

flush

همراه با --buffer برای اجرای تمام دستورات قبلی که از ابتدا یا از زمان آخرین دستور flush صادر شده‌اند استفاده می‌شود. هنگام استفاده از --buffer، هیچ خروجی تا زمان صدور دستور flush ارائه نخواهد شد. هنگامی که از --buffer استفاده نشود، دستورات هر بار بدون نیاز به صدور flush تخلیه (flush) می‌شوند.

mailmap (<bool>)

فعال یا غیرفعال کردن mailmap برای دستورات بعدی. آرگومان <bool> همان مقادیر بولی متناظر در git-config(1) را می‌پذیرد. داده‌های mailmap با اولین استفاده و تنها یک بار خوانده می‌شوند.

--batch-all-objects

به جای خواندن فهرستی از اشیاء از stdin، عملیات دسته‌ای درخواستی را بر روی تمام اشیاء موجود در مخزن و هر فضای ذخیره‌سازی شیء جایگزین انجام می‌دهد (نه فقط اشیاء در دسترس). نیازمند مشخص شدن --batch یا --batch-check است. به طور پیش‌فرض، اشیاء به ترتیبی که بر اساس هش آن‌ها مرتب شده است پیمایش می‌شوند؛ همچنین گزینه --unordered را در زیر ببینید. اشیاء همان‌طور که هستند و بدون در نظر گرفتن سازوکار "replace" در git-replace(1) ارائه می‌شوند.

--buffer

به طور معمول خروجی دسته‌ای پس از خروجی هر شیء تخلیه (flush) می‌شود، به طوری که یک فرآیند می‌تواند به صورت تعاملی از cat-file بخواند و در آن بنویسد. با این گزینه، خروجی از بافرینگ معمول stdio استفاده می‌کند؛ این امر هنگام فراخوانی --batch-check یا --batch-command روی تعداد زیادی از اشیاء بسیار کارآمدتر است.

--unordered

هنگام استفاده از --batch-all-objects، اشیاء را به ترتیبی پیمایش می‌کند که ممکن است برای دسترسی به محتویات شیء کارآمدتر از ترتیب هش باشد. جزئیات دقیق این ترتیب مشخص نیست، اما اگر به ترتیب خاصی نیاز ندارید، این به طور کلی باید منجر به خروجی سریع‌تر شود، به ویژه همراه با --batch. توجه داشته باشید که cat-file همچنان هر شیء را تنها یک بار نشان خواهد داد، حتی اگر چندین بار در مخزن ذخیره شده باشد.

--follow-symlinks

همراه با --batch یا --batch-check، پیوندهای نمادین درون مخزن را هنگام درخواست اشیاء با عبارت‌های گسترش‌یافته SHA-1 به شکل tree-ish:path-in-tree دنبال می‌کند. به جای ارائه خروجی درباره خود پیوند، خروجی را درباره شیء پیوندداده‌شده ارائه می‌دهد. اگر یک پیوند نمادین به بیرون از tree-ish اشاره کند (مانند پیوندی به /foo یا پیوندی در سطح ریشه به ../foo)، بخشی از پیوند که در خارج از درخت قرار دارد چاپ خواهد شد.

این گزینه (در حال حاضر) هنگامی که شیئی در ایندکس مشخص شده باشد (مثلاً :link به جای HEAD:link) به جای شیئی در درخت، به درستی کار نمی‌کند.

این گزینه (در حال حاضر) قابل استفاده نیست مگر اینکه --batch یا --batch-check استفاده شود.

به عنوان مثال، یک مخزن گیت شامل موارد زیر را در نظر بگیرید:

f: a file containing "hello\n"
link: a symlink to f
dir/link: a symlink to ../f
plink: a symlink to ../f
alink: a symlink to /etc/passwd

برای یک فایل معمولی f، دستور echo HEAD:f | git cat-file --batch عبارت زیر را چاپ می‌کند:

ce013625030ba8dba906f756967f9e9ca394464a blob 6

و دستور echo HEAD:link | git cat-file --batch --follow-symlinks همان مورد را چاپ خواهد کرد، درست همانند HEAD:dir/link، زیرا هر دو به HEAD:f اشاره می‌کنند.

بدون --follow-symlinks، این دستورات داده‌های مربوط به خود پیوند نمادین را چاپ می‌کنند. در مورد HEAD:link، شما چنین خروجی را مشاهده خواهید کرد:

4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1

هر دوی plink و alink به خارج از درخت اشاره دارند، بنابراین به ترتیب چاپ خواهند کرد:

symlink 4
../f
symlink 11
/etc/passwd

-Z

تنها همراه با --batch، --batch-check یا --batch-command معنا دارد؛ ورودی و خروجی به جای خط جدید با کاراکتر NUL از یکدیگر جدا می‌شوند.

-z

تنها همراه با --batch، --batch-check یا --batch-command معنا دارد؛ ورودی به جای خط جدید با کاراکتر NUL جدا می‌شود. این گزینه به نفع -Z منسوخ شده است، زیرا در غیر این صورت خروجی می‌تواند مبهم باشد.

اگر -t مشخص شود، یکی از مقادیر <type> چاپ می‌شود.

اگر -s مشخص شود، اندازه <object> بر حسب بایت.

اگر -e مشخص شود، هیچ خروجی داده نمی‌شود، مگر اینکه <object> ناقص یا معیوب باشد.

اگر -p مشخص شود، محتویات <object> به صورت خوانا چاپ می‌شود.

اگر <type> مشخص شود، محتویات خام (اگرچه فشرده‌نشده) <object> بازگردانده خواهد شد.

اگر --batch یا --batch-check داده شود، cat-file اشیاء را از stdin، هر خط یک شیء می‌خواند و اطلاعات مربوط به آن‌ها را به همان ترتیبی که خوانده شده‌اند چاپ می‌کند. به طور پیش‌فرض، کل خط به عنوان یک شیء در نظر گرفته می‌شود، همان‌طور که گویی به git-rev-parse(1) ارسال شده است.

هنگامی که --batch-command داده می‌شود، cat-file دستورات را از stdin، هر خط یک دستور می‌خواند و اطلاعات را بر اساس دستور ارائه‌شده چاپ می‌کند. با --batch-command، دستور info به همراه یک شیء اطلاعات مربوط به شیء را به همان روشی که --batch-check چاپ می‌کند نمایش می‌دهد، و دستور contents به همراه یک شیء محتویات را به همان شیوه‌ای که --batch انجام می‌دهد چاپ می‌کند.

شما می‌توانید اطلاعات نمایش‌داده‌شده برای هر شیء را با استفاده از یک <format> سفارشی مشخص کنید. <format> برای هر شیء به طور دقیق در stdout کپی می‌شود و جایگزین‌های به شکل %(atom) بسط داده شده و یک خط جدید به دنبال آن می‌آید. اتم‌های موجود عبارتند از:

objectname

نمایش کامل هگزادسیمال نام شیء.

objecttype

نوع شیء (همان چیزی که cat-file -t گزارش می‌دهد).

objectmode

اگر شیء مشخص‌شده دارای اطلاعات حالت (مانند مدخل tree یا index) باشد، حالت به صورت یک عدد صحیح هشت‌هشتی (octal) نمایش می‌یابد. در غیر این صورت، رشته خالی.

objectsize

اندازه شیء بر حسب بایت (همان چیزی که cat-file -s گزارش می‌دهد).

objectsize:disk

اندازه‌ای بر حسب بایت که شیء روی دیسک اشغال می‌کند. یادداشت مربوط به اندازه‌های روی دیسک را در بخش هشدارها (CAVEATS) در زیر ببینید.

deltabase

اگر شیء به عنوان یک دلتا روی دیسک ذخیره شده باشد، به نمایش کامل هگزادسیمال نام شیء پایه دلتا بسط می‌یابد. در غیر این صورت، به OID تهی (همه صفرها) بسط می‌یابد. بخش هشدارها (CAVEATS) در زیر را ببینید.

rest

اگر این اتم در رشته خروجی استفاده شود، خطوط ورودی در مرز اولین فاصله خالی تقسیم می‌شوند. تمامی کاراکترهای قبل از آن فاصله به عنوان نام شیء در نظر گرفته می‌شوند؛ کاراکترهای پس از آن اولین توالی فاصله خالی (یعنی "بقیه" خط) به جای اتم %(rest) خروجی داده می‌شوند.

اگر هیچ قالبی مشخص نشود، قالب پیش‌فرض %(objectname) %(objecttype) %(objectsize) است.

اگر --batch مشخص شود، یا اگر --batch-command همراه با دستور contents استفاده شود، اطلاعات شیء همراه با محتویات شیء (متشکل از %(objectsize) بایت) و به دنبال آن یک خط جدید چاپ خواهد شد.

به عنوان مثال، --batch بدون یک قالب سفارشی عبارت زیر را تولید می‌کند:

<oid> SP <type> SP <size> LF
<contents> LF

در حالی که --batch-check='%(objectname) %(objecttype)' عبارت زیر را تولید خواهد کرد:

<oid> SP <type> LF

اگر نامی در stdin مشخص شود که نتوان آن را به شیئی در مخزن ارجاع داد، آن‌گاه cat-file هر قالب سفارشی را نادیده گرفته و چاپ خواهد کرد:

<object> SP missing LF

اگر نامی در stdin مشخص شود که از طریق --filter= فیلتر شده است، آن‌گاه cat-file هر قالب سفارشی را نادیده گرفته و چاپ خواهد کرد:

<object> SP excluded LF

اگر نامی مشخص شود که ممکن است به بیش از یک شیء اشاره داشته باشد (یک sha کوتاه مبهم)، آن‌گاه cat-file هر قالب سفارشی را نادیده گرفته و چاپ خواهد کرد:

<object> SP ambiguous LF

اگر نامی مشخص شود که به یک مدخل زیرماژول در یک درخت اشاره دارد و شیء هدف در مخزن وجود ندارد، آن‌گاه cat-file هر قالب سفارشی را نادیده گرفته و چاپ می‌کند (با شناسه شیء مربوط به زیرماژول):

<oid> SP submodule LF

اگر --follow-symlinks استفاده شود، و پیوندی نمادین در مخزن به خارج از مخزن اشاره داشته باشد، آن‌گاه cat-file هر قالب سفارشی را نادیده گرفته و چاپ خواهد کرد:

symlink SP <size> LF
<symlink> LF

پیوند نمادین یا مطلق خواهد بود (که با یک / آغاز می‌شود)، یا نسبت به ریشه درخت. به عنوان مثال، اگر dir/link به ../../foo اشاره کند، آن‌گاه <symlink> برابر با ../foo خواهد بود. <size> اندازه پیوند نمادین بر حسب بایت است.

اگر --follow-symlinks استفاده شود، پیام‌های خطای زیر نمایش داده خواهند شد:

<object> SP missing LF

زمانی چاپ می‌شود که پیوند نمادین اولیه درخواستی وجود نداشته باشد.

dangling SP <size> LF
<object> LF

زمانی چاپ می‌شود که پیوند نمادین اولیه وجود دارد، اما چیزی که (به صورت متعدی) به آن اشاره می‌کند وجود ندارد.

loop SP <size> LF
<object> LF

برای حلقه‌های پیوند نمادین (یا هر پیوند نمادینی که به بیش از ۴۰ بار حل پیوند برای حل نیاز دارد) چاپ می‌شود.

notdir SP <size> LF
<object> LF

زمانی چاپ می‌شود که در حین حل پیوند نمادین، از یک فایل به عنوان نام دایرکتوری استفاده شود.

در روش جایگزین، هنگامی که -Z ارسال می‌شود، کاراکترهای شکست خط (line feeds) در هر یک از مثال‌های بالا با کاراکترهای پایان‌دهنده NUL جایگزین می‌شوند. این امر تضمین می‌کند که اگر خود خروجی حاوی خط جدید باشد، خروجی همچنان قابل تجزیه (parse) خواهد بود و بنابراین برای مقاصد اسکریپت‌نویسی توصیه می‌شود.

توجه داشته باشید که اندازه‌های اشیاء روی دیسک به طور دقیق گزارش می‌شوند، اما باید در نتیجه‌گیری درباره اینکه کدام ارجاعات یا اشیاء مسئول مصرف دیسک هستند دقت کرد. اندازه یک شیء فشرده غیردلتا (non-delta) ممکن است بسیار بزرگ‌تر از اندازه اشیائی باشد که نسبت به آن دلتا شده‌اند، اما انتخاب اینکه کدام شیء پایه و کدام دلتا باشد اختیاری است و ممکن است در طول یک فرآیند بسته‌بندی مجدد (repack) تغییر کند.

همچنین توجه داشته باشید که چندین نسخه از یک شیء ممکن است در پایگاه داده اشیاء وجود داشته باشد؛ در این حالت، مشخص نیست که اندازه یا پایه دلتای کدام نسخه گزارش خواهد شد.

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

2026-06-29 Git 2.55.0