نام (NAME)

git-update-index - ثبت محتویات فایل‌های درخت کاری در ایندکس

خلاصه دستور (SYNOPSIS)

git update-index
             [--add] [--remove | --force-remove] [--replace]
             [--refresh] [-q] [--unmerged] [--ignore-missing]
             [(--cacheinfo <mode>,<object>,<file>)...]
             [--chmod=(+|-)x]
             [--[no-]assume-unchanged]
             [--[no-]skip-worktree]
             [--[no-]ignore-skip-worktree-entries]
             [--[no-]fsmonitor-valid]
             [--ignore-submodules]
             [--[no-]split-index]
             [--[no-|test-|force-]untracked-cache]
             [--[no-]fsmonitor]
             [--really-refresh] [--unresolve] [--again | -g]
             [--info-only] [--index-info]
             [-z] [--stdin] [--index-version <n>]
             [--show-index-version]
             [--verbose]
             [--] [<file>...]

توضیحات (DESCRIPTION)

ایندکس را ویرایش می‌کند. هر فایل مشخص‌شده درون ایندکس به‌روزرسانی شده و هر وضعیت unmerged (ادغام‌نشده) یا needs updating (نیازمند به‌روزرسانی) پاک می‌شود.

همچنین برای روشی کاربرپسندتر جهت انجام برخی از رایج‌ترین عملیات‌ها روی ایندکس، git-add(1) را ببینید.

نحوه مدیریت فایل‌های مشخص‌شده توسط git update-index را می‌توان با استفاده از گزینه‌های مختلف تغییر داد:

گزینه‌ها (OPTIONS)

--add

--remove

--refresh

-q

--ignore-submodules

--unmerged

--ignore-missing

--cacheinfo <mode>,<object>,<path>, --cacheinfo <mode> <object> <path>

--index-info

--chmod=(+|-)x

--assume-unchanged, --no-assume-unchanged

--really-refresh

--skip-worktree, --no-skip-worktree

--ignore-skip-worktree-entries, --no-ignore-skip-worktree-entries

--fsmonitor-valid, --no-fsmonitor-valid

-g, --again

--unresolve

--info-only

--force-remove

--replace

--stdin

--verbose

--index-version <n>

--show-index-version

-z

--split-index, --no-split-index

--untracked-cache, --no-untracked-cache

--test-untracked-cache

--force-untracked-cache

--fsmonitor, --no-fsmonitor

--

<file>

استفاده از --REFRESH (USING --REFRESH)

گزینه --refresh فایل sha1 جدیدی محاسبه نمی‌کند و ایندکس را برای تغییرات حالت یا محتوا به‌روز نمی‌کند. اما کاری که انجام می‌دهد این است که اطلاعات stat یک فایل را با ایندکس «تطبیق مجدد» می‌دهد، به طوری که می‌توانید ایندکس را برای فایلی که تغییر نکرده اما ورودی stat آن قدیمی شده است، تازه‌سازی کنید.

برای مثال، ممکن است پس از اجرای git read-tree بخواهید این کار را انجام دهید تا جزئیات stat ایندکس را با فایل‌های مناسب پیوند دهید.

استفاده از --CACHEINFO یا --INFO-ONLY (USING --CACHEINFO OR --INFO-ONLY)

گزینه --cacheinfo برای ثبت فایلی استفاده می‌شود که در دایرکتوری کاری فعلی وجود ندارد. این قابلیت برای ادغام با حداقل دریافت (minimum-checkout merging) مفید است.

برای اینکه وانمود کنید فایلی در یک مسیر مشخص با حالت (mode) و sha1 مشخص دارید، اجرا کنید:

$ git update-index --add --cacheinfo <mode>,<sha1>,<path>

گزینه --info-only برای ثبت فایل‌ها بدون قرار دادن آن‌ها در پایگاه داده اشیاء استفاده می‌شود. این قابلیت برای مخازن صرفاً وضعیتی (status-only) مفید است.

هر دو گزینه --cacheinfo و --info-only عملکرد مشابهی دارند: ایندکس به‌روزرسانی می‌شود اما پایگاه داده اشیاء به‌روزرسانی نمی‌شود. گزینه --cacheinfo زمانی مفید است که شیء در پایگاه داده موجود باشد اما فایل به صورت محلی در دسترس نباشد. گزینه --info-only زمانی مفید است که فایل در دسترس باشد، اما نمی‌خواهید پایگاه داده اشیاء را به‌روز کنید.

استفاده از --INDEX-INFO (USING --INDEX-INFO)

گزینه --index-info سازوکار قدرتمندتری است که به شما امکان می‌دهد تعاریف چندگانه ورودی را از طریق ورودی استاندارد تغذیه کنید، و به طور خاص برای اسکریپت‌ها طراحی شده است. این گزینه می‌تواند ورودی‌هایی در سه قالب دریافت کند:

برای قرار دادن یک ورودی مرحله بالاتر در ایندکس، مسیر ابتدا باید با تغذیه یک ورودی mode=0 برای آن مسیر حذف شود، و سپس خطوط ورودی لازم در قالب سوم تغذیه شوند.

به عنوان مثال، با شروع از این ایندکس:

$ git ls-files -s
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0       frotz

می‌توانید ورودی زیر را به --index-info بدهید:

$ git update-index --index-info
0 0000000000000000000000000000000000000000      frotz
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1       frotz
100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2       frotz

خط اول ورودی مقدار 0 را به عنوان mode برای حذف مسیر تغذیه می‌کند؛ تا زمانی که SHA-1 دارای قالب‌بندی صحیحی باشد، مقدار آن اهمیتی ندارد. سپس خط دوم و سوم ورودی‌های مرحله 1 و مرحله 2 را برای آن مسیر تغذیه می‌کنند. پس از موارد فوق، با این نتیجه مواجه خواهیم شد:

$ git ls-files -s
100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1       frotz
100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2       frotz

استفاده از بیت “ASSUME UNCHANGED” (USING ASSUME UNCHANGED BIT)

بسیاری از عملیات‌ها در گیت وابسته به این هستند که سیستم فایل شما پیاده‌سازی کارآمدی از lstat(2) داشته باشد، تا اطلاعات st_mtime فایل‌های درخت کاری بتواند با کمترین هزینه بررسی شود و مشخص گردد آیا محتویات فایل نسبت به نسخه ثبت‌شده در فایل ایندکس تغییر کرده است یا خیر. متأسفانه برخی سیستم‌های فایل دارای lstat(2) ناکارآمد هستند. اگر سیستم فایل شما یکی از آن‌هاست، می‌توانید بیت «assume unchanged» را روی مسیرهایی که تغییر نداده‌اید تنظیم کنید تا گیت این بررسی را انجام ندهد. توجه داشته باشید که تنظیم این بیت روی یک مسیر به این معنا نیست که گیت محتویات فایل را برای بررسی تغییرات چک می‌کند — بلکه باعث می‌شود گیت از هرگونه بررسی صرف‌نظر کرده و فرض کند فایل تغییر نکرده است. هنگامی که تغییراتی در فایل‌های درخت کاری ایجاد می‌کنید، باید با حذف بیت «assume unchanged»، چه قبل و چه بعد از ویرایش آن‌ها، این موضوع را صراحتاً به گیت اطلاع دهید.

به منظور تنظیم بیت «assume unchanged»، از گزینه --assume-unchanged استفاده کنید. برای لغو آن، از --no-assume-unchanged استفاده نمایید. برای مشاهده فایل‌هایی که بیت «assume unchanged» روی آن‌ها تنظیم شده است، از git ls-files -v استفاده کنید (نگاه کنید به git-ls-files(1)).

این دستور متغیر پیکربندی core.ignorestat را بررسی می‌کند. وقتی مقدار آن true باشد، مسیرهای به‌روزرسانی‌شده با git update-index paths... و مسیرهای به‌روزرسانی‌شده با سایر دستورات گیت که هم ایندکس و هم درخت کاری را به‌روزرسانی می‌کنند (مانند git apply --index، git checkout-index -u و git read-tree -u) به طور خودکار به عنوان «assume unchanged» علامت‌گذاری می‌شوند. توجه داشته باشید که اگر git update-index --refresh متوجه شود که فایل درخت کاری با ایندکس مطابقت دارد، بیت «assume unchanged» تنظیم نمی‌شود (اگر می‌خواهید آن‌ها را به عنوان «assume unchanged» علامت‌گذاری کنید، از git update-index --really-refresh استفاده کنید).

گاهی کاربران بیت assume-unchanged را با بیت skip-worktree اشتباه می‌گیرند. برای توضیح تفاوت‌ها به بند پایانی در بخش «بیت SKIP-WORKTREE» در ادامه مراجعه کنید.

مثال‌ها (EXAMPLES)

برای به‌روزرسانی و تازه‌سازی تنها فایل‌هایی که از قبل دریافت (checkout) شده‌اند:

$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh

روی یک سیستم فایل ناکارآمد با تنظیم core.ignorestat:

$ git update-index --really-refresh              (1)
$ git update-index --no-assume-unchanged foo.c   (2)
$ git diff --name-only                           (3)
$ edit foo.c
$ git diff --name-only                           (4)
M foo.c
$ git update-index foo.c                         (5)
$ git diff --name-only                           (6)
$ edit foo.c
$ git diff --name-only                           (7)
$ git update-index --no-assume-unchanged foo.c   (8)
$ git diff --name-only                           (9)
M foo.c

بیت SKIP-WORKTREE (SKIP-WORKTREE BIT)

بیت skip-worktree را می‌توان در یک جمله (طولانی) تعریف کرد: به گیت بگو تا حد امکان از نوشتن فایل در دایرکتوری کاری خودداری کند، و در صورتی که فایل در دایرکتوری کاری وجود نداشت، با آن طوری رفتار کند که گویی تغییر نکرده است.

توجه داشته باشید که همه دستورات گیت به این بیت توجه نمی‌کنند، و برخی تنها تا حدی از آن پشتیبانی می‌کنند.

فلگ‌های update-index و قابلیت‌های read-tree مربوط به بیت skip-worktree، قبل از معرفی دستور git-sparse-checkout(1) وجود داشتند که روشی بسیار آسان‌تر برای پیکربندی و مدیریت بیت‌های skip-worktree ارائه می‌دهد. اگر می‌خواهید درخت کاری خود را کاهش دهید تا تنها با زیرمجموعه‌ای از فایل‌های مخزن سر و کار داشته باشید، اکیداً توصیه می‌کنیم از git-sparse-checkout(1) به جای دستورات سطح پایین update-index و read-tree استفاده کنید.

هدف اصلی بیت skip-worktree فعال‌سازی دریافت‌های کم‌پشت (sparse checkouts) است، یعنی داشتن دایرکتوری‌های کاری که تنها زیرمجموعه‌ای از مسیرها در آن‌ها وجود دارد. هنگامی که بیت skip-worktree تنظیم شود، دستورات گیت (مانند switch، pull و merge) از نوشتن این فایل‌ها خودداری خواهند کرد. با این حال، این دستورات گاهی اوقات در موارد مهم مانند تداخل در حین ادغام یا بازنشانی (rebase) این فایل‌ها را در هر صورت می‌نویسند. همچنین دستورات گیت از تلقی عدم وجود این فایل‌ها به عنوان یک حذف عمدی خودداری می‌کنند؛ برای مثال git add -u حذفی را برای این فایل‌ها مرحله‌بندی نمی‌کند و git commit -a نیز کامیتی برای حذف آن‌ها ایجاد نخواهد کرد.

اگرچه این بیت شبیه به بیت assume-unchanged به نظر می‌رسد، اما هدف آن متفاوت است. بیت assume-unchanged برای باقی گذاشتن فایل در درخت کاری است به طوری که گیت بررسی تغییرات آن را نادیده گرفته و فرض کند فایل تغییر نکرده است (هرچند اگر بتواند بدون stat گرفتن از فایل متوجه تغییر آن شود، مجاز به ثبت تغییرات است). در حالی که skip-worktree به گیت می‌گوید عدم حضور فایل را نادیده بگیرد، تا حد امکان از به‌روزرسانی آن با دستوراتی که بخش عمده دایرکتوری کاری را به‌روز می‌کنند (مانند checkout، switch، pull و غیره) خودداری کند، و نبودِ آن در کامیت‌ها ثبت نشود. توجه داشته باشید که در sparse checkoutها (راه‌اندازی‌شده توسط git sparse-checkout یا با تنظیم core.sparseCheckout روی true)، اگر فایلی در ایندکس با skip-worktree علامت‌گذاری شده باشد اما در درخت کاری یافت شود، گیت بیت skip-worktree را برای آن فایل پاک خواهد کرد.

ایندکس تفکیک‌شده (SPLIT INDEX)

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

در این حالت، ایندکس به دو فایل تقسیم می‌شود: $GIT_DIR/index و $GIT_DIR/sharedindex.<SHA-1>. تغییرات در $GIT_DIR/index (ایندکس تفکیک‌شده) انباشته می‌شوند، در حالی که فایل ایندکس مشترک شامل تمام ورودی‌های ایندکس بوده و بدون تغییر باقی می‌ماند.

هنگامی که تعداد ورودی‌ها در ایندکس تفکیک‌شده به مقداری برسد که توسط متغیر پیکربندی splitIndex.maxPercentChange مشخص شده است، تمام تغییرات در ایندکس تفکیک‌شده به فایل ایندکس مشترک بازگردانده می‌شوند (نگاه کنید به git-config(1)).

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

برای جلوگیری از حذف فایل ایندکس مشترکی که هنوز مورد استفاده قرار می‌گیرد، هر بار که یک ایندکس تفکیک‌شده جدید بر اساس فایل ایندکس مشترک ایجاد شده یا از آن خوانده می‌شود، زمان ویرایش آن به زمان فعلی به‌روزرسانی می‌گردد.

حافظه پنهان ردیابی‌نشده (UNTRACKED CACHE)

این حافظه پنهان (cache) با هدف افزایش سرعت دستوراتی در نظر گرفته شده است که به شناسایی فایل‌های ردیابی‌نشده می‌پردازند، مانند git status.

این قابلیت با ثبت mtime دایرکتوری‌های درخت کاری و سپس صرف‌نظر کردن از خواندن دایرکتوری‌ها و فراخوان‌های stat برای فایل‌های درون آن دایرکتوری‌هایی که mtime آن‌ها تغییر نکرده است، کار می‌کند. برای کارکرد صحیح این قابلیت، سیستم‌عامل و سیستم فایل زیربنایی باید در صورت افزودن، ویرایش یا حذف فایل‌ها در دایرکتوری، فیلد st_mtime دایرکتوری‌ها را تغییر دهند.

می‌توانید با گزینه --test-untracked-cache بررسی کنید که آیا سیستم فایل از این قابلیت پشتیبانی می‌کند یا خیر. گزینه --untracked-cache در نسخه‌های قدیمی‌تر گیت این آزمایش را به صورت ضمنی انجام می‌داد، اما اکنون دیگر این‌طور نیست.

اگر می‌خواهید این ویژگی را فعال (یا غیرفعال) کنید، استفاده از متغیر پیکربندی core.untrackedCache (نگاه کنید به git-config(1)) آسان‌تر از استفاده از گزینه --untracked-cache در دستور git update-index در تک‌تک مخازن است، به ویژه اگر بخواهید این کار را در تمام مخازنی که استفاده می‌کنید انجام دهید؛ چرا که می‌توانید متغیر پیکربندی را تنها یک بار در $HOME/.gitconfig خود روی true (یا false) تنظیم کنید و تمام مخازن شما را تحت تأثیر قرار دهد.

هنگامی که متغیر پیکربندی core.untrackedCache تغییر می‌کند، دفعه بعد که دستوری ایندکس را می‌خواند، حافظه پنهان ردیابی‌نشده به ایندکس اضافه یا از آن حذف می‌شود؛ در حالی که هنگام استفاده از --[no-|force-]untracked-cache، حافظه پنهان ردیابی‌نشده بلافاصله به ایندکس افزوده یا از آن حذف می‌گردد.

قبل از نسخه 2.17، حافظه پنهان ردیابی‌نشده دارای باگی بود که در آن جایگزینی یک دایرکتوری با یک پیوند نمادین (symlink) به دایرکتوری دیگر می‌توانست باعث شود فایل‌های ردیابی‌شده توسط گیت به اشتباه به عنوان ردیابی‌نشده نشان داده شوند. کامیت «status: add a failing test showing a core.untrackedCache bug» در مخزن git.git را ببینید. یک راهکار موقت برای آن این است (و این ممکن است برای سایر باگ‌های کشف‌نشده در آینده نیز کار کند):

$ git -c core.untrackedCache=false status

همچنین نشان داده شده است که این باگ در ساختارهای داخلی حافظه پنهان ردیابی‌نشده، موارد غیرپیوند نمادین جایگزینی یک دایرکتوری با یک فایل را نیز تحت تأثیر قرار می‌دهد، اما هیچ موردی گزارش نشده که منجر به خروجی نادرست «git status» شده باشد.

همچنین مواردی وجود دارد که در آن‌ها ایندکس‌های موجود که توسط نسخه‌های گیت قبل از 2.17 نوشته شده‌اند، به دایرکتوری‌هایی ارجاع می‌دهند که دیگر وجود ندارند، و این ممکن است باعث چاپ هشدارهای متعدد «could not open directory» در «git status» شود. این‌ها هشدارهای جدیدی برای مشکلات موجود قبلی هستند که پیش از این بی‌صدا نادیده گرفته می‌شدند.

همانند باگ توضیح‌داده‌شده در بالا، راهکار این است که یک بار دستور «git status» را با core.untrackedCache=false اجرا کنید تا داده‌های معیوب باقی‌مانده پاک‌سازی شوند.

پایشگر سیستم فایل (FILE SYSTEM MONITOR)

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

این ویژگی به گیت امکان می‌دهد با یک پایشگر سیستم فایل (نگاه کنید به git-fsmonitor--daemon(1) و بخش «fsmonitor-watchman» در githooks(5)) که می‌تواند تغییر فایل‌ها را اطلاع دهد، همکاری کند. این کار به گیت امکان می‌دهد از اجرای lstat() روی تک‌تک فایل‌ها برای یافتن فایل‌های تغییریافته بی‌نیاز شود.

هنگامی که این قابلیت همراه با حافظه پنهان ردیابی‌نشده استفاده شود، می‌تواند با پرهیز از هزینه پویش کل دایرکتوری کاری برای یافتن فایل‌های جدید، کارایی را بیش از پیش بهبود بخشد.

اگر می‌خواهید این ویژگی را فعال (یا غیرفعال) کنید، استفاده از متغیر پیکربندی core.fsmonitor (نگاه کنید به git-config(1)) آسان‌تر از استفاده از گزینه --fsmonitor در دستور git update-index در تک‌تک مخازن است، به ویژه اگر بخواهید این کار را در تمام مخازنی که استفاده می‌کنید انجام دهید؛ زیرا می‌توانید متغیر پیکربندی را تنها یک بار در $HOME/.gitconfig خود تنظیم کنید تا همه مخازن مورد استفاده شما را تحت تأثیر قرار دهد.

هنگامی که متغیر پیکربندی core.fsmonitor تغییر می‌کند، دفعه بعدی که دستوری ایندکس را می‌خواند، پایشگر سیستم فایل به ایندکس اضافه یا از آن حذف می‌شود. هنگام استفاده از --[no-]fsmonitor، پایشگر سیستم فایل بلافاصله به ایندکس افزوده یا از آن حذف می‌گردد.

پیکربندی (CONFIGURATION)

این دستور از متغیر پیکربندی core.filemode پیروی می‌کند. اگر مخزن شما روی سیستم فایلی قرار دارد که بیت‌های اجرایی آن غیرقابل اعتماد هستند، این متغیر باید روی false تنظیم شود (نگاه کنید به git-config(1)). این کار باعث می‌شود در صورتی که تفاوت فقط در بیت اجرایی باشد، دستور تفاوت بین حالت‌های فایل ثبت‌شده در ایندکس و حالت فایل روی سیستم فایل را نادیده بگیرد. در چنین سیستم فایل نامساعدی، ممکن است لازم باشد از git update-index --chmod= استفاده کنید.

به طور مشابه، اگر متغیر پیکربندی core.symlinks روی false تنظیم شده باشد (نگاه کنید به git-config(1))، پیوندهای نمادین به صورت فایل‌های معمولی دریافت (checkout) می‌شوند و این دستور حالت ثبت‌شده فایل را از پیوند نمادین به فایل معمولی تغییر نمی‌دهد.

این دستور متغیر پیکربندی core.ignorestat را بررسی می‌کند. بخش استفاده از بیت "assume unchanged" در بالا را ببینید.

این دستور همچنین متغیر پیکربندی core.trustctime را بررسی می‌کند. این متغیر زمانی می‌تواند مفید باشد که زمان تغییر inode مرتباً توسط چیزی خارج از گیت ویرایش می‌شود (خزنده‌های سیستم فایل و سیستم‌های پشتیبان‌گیری از ctime برای علامت‌گذاری فایل‌های پردازش‌شده استفاده می‌کنند) (نگاه کنید به git-config(1)).

افزونه حافظه پنهان ردیابی‌نشده را می‌توان توسط متغیر پیکربندی core.untrackedCache فعال کرد (نگاه کنید به git-config(1)).

نکات (NOTES)

کاربران اغلب تلاش می‌کنند از بیت‌های assume-unchanged و skip-worktree استفاده کنند تا به گیت بگویند تغییرات فایل‌های ردیابی‌شده را نادیده بگیرد. این کار طبق انتظار عمل نمی‌کند، چرا که گیت ممکن است هنگام انجام برخی عملیات‌ها همچنان فایل‌های درخت کاری را با ایندکس مقایسه کند. به طور کلی، گیت روشی برای نادیده گرفتن تغییرات فایل‌های ردیابی‌شده ارائه نمی‌دهد، بنابراین راهکارهای جایگزین توصیه می‌شوند.

برای مثال، اگر فایلی که می‌خواهید تغییر دهید نوعی فایل پیکربندی است، مخزن می‌تواند شامل یک فایل پیکربندی نمونه باشد که بتوان آن را به نامی که نادیده گرفته شده کپی کرده و ویرایش نمود. مخزن حتی می‌تواند شامل اسکریپتی باشد که با فایل نمونه به عنوان الگو رفتار کرده و آن را به صورت خودکار تغییر داده و کپی کند.

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

git-config(1), git-add(1), git-ls-files(1)

گیت (GIT)

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