GIT-LS-FILES(1) دستورات عمومی کاربر GIT-LS-FILES(1)

git-ls-files - نمایش اطلاعات مربوط به فایل‌های موجود در ایندکس و درخت کاری

git ls-files [-z] [-t] [-v] [-f]
                [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
                [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
                [--resolve-undo]
                [--directory [--no-empty-directory]] [--eol]
                [--deduplicate]
                [-x <pattern>|--exclude=<pattern>]
                [-X <file>|--exclude-from=<file>]
                [--exclude-per-directory=<file>]
                [--exclude-standard]
                [--error-unmatch] [--with-tree=<tree-ish>]
                [--full-name] [--recurse-submodules]
                [--abbrev[=<n>]] [--format=<format>] [--] [<file>...]

این دستور فهرست فایل‌های موجود در ایندکس را با فهرست واقعی دایرکتوری کاری ادغام می‌کند و ترکیب‌های مختلفی از این دو را نمایش می‌دهد.

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

-c, --cached

نمایش تمام فایل‌های کَش‌شده در ایندکس گیت، یعنی تمام فایل‌های ردگیری‌شده. (در صورتی که هیچ‌یک از گزینه‌های -c/-s/-d/-o/-u/-k/-m/--resolve-undo مشخص نشده باشند، این گزینه پیش‌فرض است.)

-d, --deleted

نمایش فایل‌هایی با حذف آماده‌سازی‌نشده (unstaged deletion)

-m, --modified

نمایش فایل‌هایی با تغییرات آماده‌سازی‌نشده (توجه داشته باشید که یک حذف آماده‌سازی‌نشده نیز یک تغییر آماده‌سازی‌نشده به حساب می‌آید)

-o, --others

نمایش فایل‌های دیگر (یعنی ردگیری‌نشده) در خروجی

-i, --ignored

نمایش فقط فایل‌های نادیده‌گرفته‌شده (ignored) در خروجی. باید همراه با یکی از گزینه‌های صریح -c یا -o استفاده شود. هنگام نمایش فایل‌های موجود در ایندکس (یعنی زمان استفاده همراه با -c)، فقط فایل‌هایی چاپ می‌شوند که با یک الگوی استثنا مطابقت دارند. هنگام نمایش فایل‌های «دیگر» (یعنی زمان استفاده همراه با -o)، فقط فایل‌هایی نمایش داده می‌شوند که با یک الگوی استثنا مطابقت دارند. قواعد نادیده‌گیری استاندارد به‌طور خودکار فعال نمی‌شوند؛ بنابراین، حداقل یکی از گزینه‌های --exclude* الزامی است.

-s, --stage

نمایش بیت‌های حالت (mode bits)، نام شیء و شماره مرحله (stage) محتویات آماده‌سازی‌شده در خروجی.

--directory

اگر یک دایرکتوری به طور کامل به عنوان «دیگر» طبقه‌بندی شده باشد، فقط نام آن (همراه با اسلش در انتها) را نمایش می‌دهد و کل محتویات آن را نشان نمی‌دهد. بدون -o/--others هیچ تاثیری ندارد.

--no-empty-directory

دایرکتوری‌های خالی را فهرست نکن. بدون --directory هیچ تاثیری ندارد.

-u, --unmerged

نمایش اطلاعات فایل‌های ادغام‌نشده در خروجی، بدون نمایش سایر فایل‌های ردگیری‌شده (گزینه --stage را اجباری می‌کند و --cached را لغو می‌کند).

-k, --killed

نمایش فایل‌های ردگیری‌نشده روی سیستم‌فایل که به دلیل تداخل فایل/دایرکتوری باید حذف شوند تا فایل‌های ردگیری‌شده بتوانند روی سیستم‌فایل نوشته شوند.

--resolve-undo

نمایش فایل‌هایی که دارای اطلاعات resolve-undo در ایندکس هستند به همراه اطلاعات resolve-undo آن‌ها. (اطلاعات resolve-undo همان چیزی است که برای پیاده‌سازی «git checkout -m $PATH» استفاده می‌شود، یعنی برای ایجاد مجدد تداخل‌های ادغامی که به طور تصادفی حل شده بودند)

-z

خاتمه خطوط با \0 در خروجی و عدم قرار دادن نام فایل‌ها در گیومه. برای اطلاعات بیشتر بخش خروجی (OUTPUT) را در ادامه ببینید.

--deduplicate

هنگامی که فقط نام فایل‌ها نمایش داده می‌شود، موارد تکراری را که ممکن است ناشی از وجود چندین مرحله (stage) در حین ادغام باشند، یا به دلیل تعیین همزمان گزینه‌های --deleted و --modified رخ دهند، حذف می‌کند. هنگامی که هر یک از گزینه‌های -t، --unmerged یا --stage در حال استفاده باشد، این گزینه هیچ تاثیری ندارد.

-x <pattern>, --exclude=<pattern>

نادیده گرفتن فایل‌های ردگیری‌نشده‌ای که با pattern مطابقت دارند. توجه داشته باشید که pattern یک الگوی جانشین شل (shell wildcard) است. برای اطلاعات بیشتر بخش الگوهای استثنا (EXCLUDE PATTERNS) را در ادامه ببینید.

-X <file>, --exclude-from=<file>

خواندن الگوهای استثنا از <file>؛ ۱ الگو در هر سطر.

--exclude-per-directory=<file>

خواندن الگوهای استثنای اضافی در <file> که فقط برای آن دایرکتوری و زیردایرکتوری‌های آن اعمال می‌شوند. اگر در حال تلاش برای شبیه‌سازی نحوه کارکرد دستورات Porcelain هستید، استفاده از گزینه --exclude-standard به جای این گزینه ساده‌تر و جامع‌تر است.

--exclude-standard

افزودن استثناهای استاندارد گیت: .git/info/exclude، .gitignore در هر دایرکتوری، و فایل استثناهای سراسری کاربر.

--error-unmatch

اگر هر <file> در ایندکس ظاهر نشود، با آن به عنوان یک خطا برخورد کن (مقدار ۱ را برمی‌گرداند).

--with-tree=<tree-ish>

هنگام استفاده از --error-unmatch برای بسط آرگومان‌های <file> ارائه‌شده توسط کاربر (یعنی الگوی مسیر) به مسیرها، وانمود می‌کند مسیرهایی که از زمان <tree-ish> مشخص‌شده در ایندکس حذف شده‌اند، همچنان وجود دارند. استفاده از این گزینه همراه با گزینه‌های -s یا -u هیچ معنا و کاربردی ندارد.

-t

نمایش برچسب‌های وضعیت همراه با نام فایل‌ها. توجه داشته باشید که برای اهداف اسکریپت‌نویسی، git-status(1) --porcelain و git-diff-files(1) --name-status تقریباً همیشه گزینه‌های بهتری هستند؛ کاربران باید برای گزینه‌های کاربرپسندتر به git-status(1) --short یا git-diff(1) --name-status نگاه کنند.

این گزینه دلیلی را برای نمایش هر نام فایل در قالب یک برچسب وضعیت ارائه می‌دهد (که پس از آن یک فاصله و سپس نام فایل می‌آید). برچسب‌های وضعیت همگی تک‌نویسه‌ای از فهرست زیر هستند:

H

فایل ردگیری‌شده‌ای که نه ادغام‌نشده است و نه skip-worktree

S

فایل ردگیری‌شده‌ای که skip-worktree است

M

فایل ردگیری‌شده‌ای که ادغام‌نشده است

R

فایل ردگیری‌شده با حذف آماده‌سازی‌نشده

C

فایل ردگیری‌شده با تغییرات آماده‌سازی‌نشده

K

مسیرهای ردگیری‌نشده‌ای که بخشی از تداخل‌های فایل/دایرکتوری هستند و مانع از چک‌اوت فایل‌های ردگیری‌شده می‌شوند

?

فایل ردگیری‌نشده

U

فایل با اطلاعات resolve-undo

-v

مشابه -t، اما برای فایل‌هایی که به عنوان assume unchanged علامت‌گذاری شده‌اند از حروف کوچک استفاده می‌کند (نگاه کنید به git-update-index(1)).

-f

مشابه -t، اما برای فایل‌هایی که به عنوان fsmonitor valid علامت‌گذاری شده‌اند از حروف کوچک استفاده می‌کند (نگاه کنید به git-update-index(1)).

--full-name

هنگامی که از یک زیردایرکتوری اجرا می‌شود، دستور معمولاً مسیرها را نسبت به دایرکتوری فعلی خروجی می‌دهد. این گزینه خروجی مسیرها را مجبور می‌کند که نسبت به دایرکتوری ریشه پروژه خروجی داده شوند.

--recurse-submodules

دستور ls-files را به طور بازگشتی روی هر ساب‌ماژول فعال در مخزن فراخوانی می‌کند. در حال حاضر فقط از حالت‌های --cached و --stage پشتیبانی می‌شود.

--abbrev[=<n>]

به جای نمایش خطوط کامل ۴۰ بایتی هگزادسیمال شیء، کوتاه‌ترین پیشوندی را نمایش می‌دهد که حداقل <n> رقم هگزادسیمال طول داشته باشد و به طور یکتا به شیء ارجاع دهد. تعداد ارقام غیرپیش‌فرض را می‌توان با --abbrev=<n> مشخص کرد.

--debug

پس از هر خط که فایلی را توصیف می‌کند، داده‌های بیشتری درباره مدخل کَش آن اضافه کن. هدف این است که تا جای ممکن اطلاعات برای بررسی دستی نمایش داده شود؛ قالب دقیق ممکن است در هر زمان تغییر کند.

--eol

نمایش <eolinfo> و <eolattr> فایل‌ها. مقدار <eolinfo> شناسه محتوای فایلی است که گیت زمانی که مشخصه «text» برابر با «auto» باشد (یا تنظیم نشده باشد و core.autocrlf نادرست نباشد) از آن استفاده می‌کند. مقدار <eolinfo> یکی از مقادیر «-text»، «none»، «lf»، «crlf»، «mixed» یا «» است.

«» به این معناست که فایل یک فایل معمولی نیست، در ایندکس نیست یا در درخت کاری قابل دسترسی نیست.

مقدار <eolattr> مشخصه‌ای است که هنگام چک‌اوت یا کامیت کردن استفاده می‌شود؛ این مقدار یکی از مقادیر «»، «-text»، «text»، «text=auto»، «text eol=lf» یا «text eol=crlf» است. از گیت ۲.۱۰ به بعد مقادیر «text=auto eol=lf» و «text=auto eol=crlf» پشتیبانی می‌شوند.

برای فایل‌های معمولی، هم <eolinfo> در ایندکس («i/<eolinfo>») و هم در درخت کاری («w/<eolinfo>») نمایش داده می‌شوند، و به دنبال آن‌ها («attr/<eolattr>») می‌آید.

--sparse

اگر ایندکس از نوع تنک (sparse) باشد، دایرکتوری‌های تنک را بدون بسط دادن به فایل‌های درونشان نمایش می‌دهد. دایرکتوری‌های تنک با یک اسلش در انتها نمایش داده می‌شوند، مانند «x/» برای یک دایرکتوری تنک «x».

--format=<format>

رشته‌ای که مقدار %(fieldname) را از نتیجه‌ای که نمایش داده می‌شود جای‌گذاری می‌کند. همچنین %% را به %، و %xXX را (که در آن XX ارقام هگزادسیمال هستند) به نویسه‌ای با کد هگزادسیمال XX جای‌گذاری می‌کند؛ برای مثال %x00 به \0 (NUL)، %x09 به \t (TAB) و %x0a به \n (LF) تبدیل می‌شود. گزینه --format نمی‌تواند با -s، -o، -k، -t، --resolve-undo و --eol ترکیب شود.

--

دیگر هیچ آرگومانی را به عنوان گزینه تفسیر نکن.

<file>

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

دستور git ls-files صرفاً نام فایل‌ها را خروجی می‌دهد، مگر اینکه --stage مشخص شده باشد که در این صورت خروجی آن به این صورت خواهد بود:

[<tag> ]<mode> <object> <stage> <file>

دستور git ls-files --eol به این شکل نمایش می‌دهد:

i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>

دستورهای git ls-files --unmerged و git ls-files --stage می‌توانند برای بررسی اطلاعات تفصیلی درباره مسیرهای ادغام‌نشده استفاده شوند.

برای یک مسیر ادغام‌نشده، ایندکس به جای ثبت یک جفت واحد mode/SHA-1، حداکثر تا سه جفت از این دست را ثبت می‌کند؛ یکی از درخت O در مرحله ۱، یکی از A در مرحله ۲، و یکی از B در مرحله ۳. این اطلاعات می‌تواند توسط کاربر (یا دستورات porcelain) برای مشاهده آنچه که باید در نهایت در آن مسیر ثبت شود استفاده شود. (برای اطلاعات بیشتر در مورد وضعیت، git-read-tree(1) را ببینید)

بدون گزینه -z، نام مسیرهایی با نویسه‌های «غیرعادی» همان‌طور که برای متغیر پیکربندی core.quotePath توضیح داده شده است در گیومه قرار می‌گیرند (نگاه کنید به git-config(1)). با استفاده از -z، نام فایل عینا خروجی داده می‌شود و انتهای خط با یک بایت NUL خاتمه می‌یابد.

امکان چاپ در یک قالب سفارشی با استفاده از گزینه --format وجود دارد، که می‌تواند فیلدهای مختلف را با استفاده از نمادگذاری %(fieldname) جای‌گذاری کند. برای مثال، اگر فقط فیلدهای «objectname» و «path» برایتان مهم است، می‌توانید دستور را با یک «--format» مشخص به این شکل اجرا کنید:

git ls-files --format='%(objectname) %(path)'

نحوه نمایش هر مسیر را می‌توان با استفاده از گزینه --format=<format> سفارشی‌سازی کرد، که در آن %(fieldname) در رشته <format> برای جنبه‌های گوناگون مدخل ایندکس جای‌گذاری می‌شود. «fieldname»های زیر قابل درک هستند:

objectmode

حالت (mode) فایل که در ایندکس ثبت شده است.

objecttype

نوع شیء (object type) فایل که در ایندکس ثبت شده است.

objectname

نام شیء فایل (شناسه شیء) که در ایندکس ثبت شده است.

objectsize[:padded]

اندازه شیء فایل که در ایندکس ثبت شده است (اگر شیء یک commit یا tree باشد، «-» نمایش داده می‌شود). همچنین از قالب پدشده (فاصله‌دار) اندازه با «%(objectsize:padded)» پشتیبانی می‌کند.

stage

مرحله (stage) فایل که در ایندکس ثبت شده است.

eolinfo:index, eolinfo:worktree

مقدار <eolinfo> (توضیحات مربوط به گزینه --eol را ببینید) محتویات موجود در ایندکس یا در درخت کاری برای آن مسیر.

eolattr

مقدار <eolattr> (توضیحات مربوط به گزینه --eol را ببینید) که برای آن مسیر اعمال می‌شود.

path

نام مسیر (pathname) فایل که در ایندکس ثبت شده است.

دستور git ls-files می‌تواند هنگام پیمایش درخت دایرکتوری و پیدا کردن فایل‌ها برای نمایش (در زمانی که فلگ‌های --others یا --ignored مشخص شده‌اند)، از فهرستی از «الگوهای استثنا» استفاده کند. صفحه راهنمای gitignore(5) قالب الگوهای استثنا را مشخص می‌کند.

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

1.فلگ خط فرمان --exclude=<pattern> یک الگوی تکی را مشخص می‌کند. الگوها دقیقاً به همان ترتیبی که در خط فرمان ظاهر می‌شوند اولویت‌بندی می‌شوند.
2.فلگ خط فرمان --exclude-from=<file> فایلی حاوی فهرستی از الگوها را مشخص می‌کند. الگوها به همان ترتیبی که در فایل ظاهر می‌شوند اولویت‌بندی می‌شوند.
3.فلگ خط فرمان --exclude-per-directory=<name> نام فایل موجود در هر دایرکتوری را که git ls-files بررسی می‌کند مشخص می‌سازد، که به طور معمول .gitignore است. فایل‌های موجود در دایرکتوری‌های عمیق‌تر اولویت دارند. الگوها دقیقاً به همان ترتیبی که در فایل‌ها ظاهر می‌شوند اولویت‌بندی می‌شوند.

الگویی که در خط فرمان با --exclude مشخص شود یا از فایل مشخص‌شده با --exclude-from خوانده شود، نسبت به ریشه درخت دایرکتوری در نظر گرفته می‌شود. الگویی که از یک فایل مشخص‌شده توسط --exclude-per-directory خوانده شود، نسبت به دایرکتوری‌ای در نظر گرفته می‌شود که فایل الگو در آن قرار دارد.

به طور کلی، هر گاه بخواهید قواعد استثنا به همان شکلی اعمال شوند که دستورات Porcelain اعمال می‌کنند، باید بتوانید از --exclude-standard استفاده کنید. برای شبیه‌سازی آنچه --exclude-standard مشخص می‌کند، می‌توانید --exclude-per-directory=.gitignore را بدهید، و سپس موارد زیر را مشخص کنید:

1.فایل مشخص‌شده توسط متغیر پیکربندی core.excludesfile (در صورت وجود)، یا فایل $XDG_CONFIG_HOME/git/ignore.
2.فایل $GIT_COMMON_DIR/info/exclude.

از طریق گزینه --exclude-from=.

git-read-tree(1)، gitignore(5)

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

2026-06-29 Git 2.55.0