نام (NAME)

git-lfs-migrate - مهاجرت تاریخچه به یا از Git LFS

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

git lfs migrate <mode> [options] [--] [branch ...]

توضیحات (DESCRIPTION)

فایل‌ها را در یک مخزن Git به اشاره‌گرهای Git LFS یا برعکس تبدیل می‌کند، یا اندازه‌های فایل‌های Git را بر اساس نوع فایل خلاصه می‌نماید. حالت import فایل‌های Git (یعنی blobها) را به Git LFS تبدیل می‌کند، در حالی که حالت export عمل معکوس آن را انجام می‌دهد، و حالت info یک خلاصه اطلاعاتی ارائه می‌دهد که می‌تواند در تصمیم‌گیری برای وارد کردن یا خارج کردن فایل‌ها مفید باشد.

در همه حالت‌ها، به طور پیش‌فرض git lfs migrate فقط روی شاخه فعلی بررسی‌شده (checked-out) و فقط روی فایل‌هایی (از هر اندازه و نوعی) کار می‌کند که در کامیت‌هایی اضافه شده‌اند که در هیچ مخزن دوردستی وجود ندارند. گزینه‌های متعددی برای لغو این رفتارهای پیش‌فرض در دسترس هستند.

هنگام تبدیل فایل‌ها به یا از Git LFS، دستور git lfs migrate فقط در مخزن محلی و نسخه کاری شما تغییرات ایجاد می‌کند و هرگز روی مخازن دوردست تاثیری نمی‌گذارد. این امر عمدی است زیرا حالت‌های import و export عموماً به این معنا «مخرب» هستند که تاریخچه Git شما را بازنویسی می‌کنند، کامیت‌ها را تغییر می‌دهند و کدهای SHA جدید برای کامیت‌ها تولید می‌نمایند. (استثناء این قاعده، زیرحالت «بدون بازنویسی» import است؛ برای جزئیات به بخش «وارد کردن بدون بازنویسی تاریخچه (IMPORT WITHOUT REWRITING HISTORY)» مراجعه کنید.)

بنابراین باید همیشه پیش از استفاده از حالت‌های import یا export کارهای کامیت‌نشده خود را کامیت یا stash کنید، و سپس پیش از ارسال تغییرات به مخازن دوردست، نتیجه مهاجرت را اعتبارسنجی نمایید، برای مثال با اجرای حالت info و بررسی تاریخچه بازنویسی‌شده کامیت‌ها.

هنگامی که از تغییرات رضایت داشتید، باید تاریخچه جدید Git شاخه‌های بازنویسی‌شده را با force-push به تمام مخازن دوردست خود ارسال کنید. این مرحله‌ای است که باید با دقت انجام شود، زیرا تاریخچه Git را در مخازن دوردست خود دگرگون خواهید کرد.

برای بررسی یا تغییر فایل‌ها در شاخه‌هایی غیر از شاخه بررسی‌شده فعلی، می‌توان ارجاعات شاخه را مستقیماً مشخص کرد، یا در یک یا چند گزینه --include-ref ارائه نمود. همچنین می‌توان آن‌ها را با افزودن پیشوند ^ یا مشخص کردن در گزینه‌های --exclude-ref مستثنی کرد. از گزینه --everything استفاده کنید تا مشخص شود تمام ارجاعات، از جمله تمام ارجاعات دوردست باید بررسی شوند. برای جزئیات به بخش «شامل کردن و مستثنی کردن ارجاعات (INCLUDE AND EXCLUDE REFERENCES)» مراجعه کنید.

برای حالت‌های info و import، تمام انواع فایل‌ها به طور پیش‌فرض در نظر گرفته می‌شوند؛ در حالی که این ویژگی در حالت info مفید است، اغلب هنگام وارد کردن (import) مطلوب نیست، بنابراین در این مورد معمولاً باید الگوهای نام فایل (pathspec) یا گزینه --fixup مشخص شوند. (حداقل یک pathspec برای شامل کردن در حالت export الزامی است.) الگوهای مسیر را می‌توان با استفاده از گزینه‌های --include و --exclude (به اختصار -I و -X) تعریف کرد، همان‌طور که در بخش «شامل کردن و مستثنی کردن (INCLUDE AND EXCLUDE)» توضیح داده شده است.

از آنجا که استفاده معمول از Git LFS به ردیابی انواع فایل خاص با استفاده از الگوهای نام فایل تعریف‌شده در فایل‌های .gitattributes وابسته است، دستور git lfs migrate فایل‌های .gitattributes را در صورت لزوم بررسی، ایجاد و اصلاح خواهد کرد. فایل‌های .gitattributes همیشه با مجوز پیش‌فرض خواندن/نوشتن (یعنی بدون مجوز اجرا) اختصاص داده می‌شوند. هر پیوند نمادین (symbolic link) با این نام باعث توقف زودهنگام فرآیند مهاجرت خواهد شد.

حالت import (به بخش «IMPORT» مراجعه کنید) اشیاء Git از انواع فایل مشخص‌شده (مثلاً با --include) را به اشاره‌گرهای Git LFS تبدیل کرده و مدخل‌هایی برای آن انواع فایل به فایل‌های .gitattributes اضافه می‌کند، و در صورت عدم وجود این فایل‌ها، آن‌ها را ایجاد می‌نماید. نتیجه باید همانند این باشد که دستورات git lfs track در نقاطی از تاریخچه Git شما متناظر با جایی که هر نوع فایل تبدیل‌شده برای اولین بار ظاهر شده است، اجرا شده باشند. استثناء زمانی است که گزینه --fixup داده شود، که در این صورت حالت import فقط فایل‌های موجود .gitattributes را بررسی کرده و سپس اشیاء Git را که باید توسط Git LFS ردیابی شوند اما هنوز ردیابی نشده‌اند، تبدیل می‌کند.

حالت export (به بخش «EXPORT» مراجعه کنید) به عنوان عملیات معکوس برای حالت import عمل می‌کند، و هر اشاره‌گر Git LFS را که با انواع فایل مشخص‌شده با --include مطابقت دارد (که باید حداقل یک بار داده شود) تبدیل می‌نماید. توجه داشته باشید که مدخل‌های .gitattributes حذف نخواهند شد، و فایل‌ها نیز حذف نمی‌شوند؛ در عوض، حالت export مدخل‌های «ردیابی نشود» مشابه آنچه توسط دستور git lfs untrack ایجاد می‌شود درج می‌کند. گزینه --remote در حالت export برای مشخص کردن مخزن دوردستی که اشیاء Git LFS در صورت عدم وجود در حافظه نهان محلی LFS باید از آن واکشی شوند، در دسترس است؛ در صورت عدم ارائه، origin به طور پیش‌فرض استفاده می‌شود.

حالت info (به بخش «INFO» مراجعه کنید) تعداد کل و اندازه فایل‌ها را در یک مخزن بر اساس نوع فایل (یعنی بر اساس پسوند نام فایل) خلاصه می‌کند. توجه داشته باشید که همانند دو حالت دیگر، به طور پیش‌فرض حالت info فقط روی شاخه بررسی‌شده فعلی و فقط روی کامیت‌هایی که در هیچ مخزن دوردستی وجود ندارند عمل می‌کند، بنابراین برای دریافت خلاصه‌ای از کل مخزن در تمام شاخه‌ها، از گزینه --everything استفاده کنید. اگر اشیاء قبلاً به اشاره‌گرهای Git LFS تبدیل شده باشند، به طور پیش‌فرض اندازه اشیاء ارجاع‌شده جمع‌بندی شده و به طور جداگانه گزارش می‌شود. همچنین می‌توانید با استفاده از --pointers=ignore آن‌ها را نادیده بگیرید یا با استفاده از --pointers=no-follow با اشاره‌گرها مانند فایل رفتار کنید. (گزینه دوم مشابه نحوه برخورد با اشاره‌گرهای موجود Git LFS توسط حالت info در نسخه‌های پیشین Git LFS است).

هنگام استفاده از گزینه --everything، توجه داشته باشید که این به معنای در نظر گرفتن تمام کامیت‌های در دسترس از تمام ارجاعات (محلی و دوردست) است، اما لزوماً شامل همه انواع فایل نمی‌شود. حالت‌های import و info به طور پیش‌فرض همه انواع فایل را در نظر می‌گیرند، اگرچه گزینه‌های --include و --exclude این رفتار را محدود می‌کنند.

اگرچه گزینه --everything به این معناست که تمام کامیت‌های در دسترس از هر ارجاعی برای مهاجرت در نظر گرفته می‌شوند، اما پس از مهاجرت حتی در صورت مشخص شدن --everything فقط ارجاعات محلی به‌روزرسانی خواهند شد. این امر همگام ماندن ارجاعات دوردست با مخزن دوردست مربوطه‌شان را تضمین می‌کند. به عبارت دیگر، refs/heads/foo با گزینه --everything به‌روزرسانی خواهد شد، اما refs/remotes/origin/foo به‌روزرسانی نخواهد شد، بنابراین تا زمانی که git push origin foo انجام نشود، با دوردست همگام می‌ماند. پس از بررسی اینکه نتایج یک مهاجرت با --everything رضایت‌بخش است، ارسال تمام شاخه‌های محلی به مخازن دوردست با استفاده از گزینه --all در دستور git push می‌تواند راحت باشد.

مگر اینکه گزینه --skip-fetch داده شده باشد، git lfs migrate همیشه با واکشی فهرست‌های به‌روزشده ارجاعات از تمام مخازن دوردست بازگردانده‌شده توسط git remote آغاز می‌شود، اما همان‌طور که در بالا ذکر شد، پس از اعمال تغییرات در تاریخچه محلی Git در حین تبدیل اشیاء، هرگز آن تغییرات را به طور خودکار به مخازن دوردست شما ارسال نخواهد کرد.

حالت‌ها (MODES)

info

import

export

گزینه‌ها (OPTIONS)

-I <paths>, --include=<paths>

-X <paths>, --exclude=<paths>

--include-ref=<refname>

--exclude-ref=<refname>

--skip-fetch

--everything

--yes

[branch ...]

*.gif               93 MB   9480/10504 files(s)  90%
*.png               14 MB    1732/1877 files(s)  92%

شامل کردن و مستثنی کردن (INCLUDE AND EXCLUDE)

می‌توانید مشخص کنید که git lfs migrate فقط فایل‌هایی را تبدیل کند که تطبیق مسیر آن‌ها (pathspec) با الگوهای گلوب (glob) گزینه --include مطابقت دارد و با الگوهای --exclude مطابقت ندارد، تا یا زمان کل مهاجرت کاهش یابد یا فقط بخشی از مخزن شما مهاجرت داده شود. می‌توان چندین الگو را با استفاده از کاما به عنوان جداکننده مشخص کرد.

تطبیق الگو به گونه‌ای انجام می‌شود که از نظر عملکردی معادل قالب تطبیق الگو در .gitattributes باشد. علاوه بر تطبیق ساده پسوند فایل (مثلاً .gif)، الگوها همچنین می‌توانند مسیرهای دایرکتوری را مشخص کنند که در این صورت می‌توان از قالب path/* برای تطبیق بازگشتی استفاده کرد.

توجه داشته باشید که این شیوه تطبیق الگو برای گزینه‌های --include و --exclude مورد استفاده در دستور git lfs migrate، در بین مجموعه‌دستورات git lfs منحصر‌به‌فرد است. سایر دستوراتی که این گزینه‌ها را می‌پذیرند، مانند git lfs ls-files، در عوض از شکل تطبیق الگوی gitignore(5) استفاده می‌کنند.

شامل کردن و مستثنی کردن ارجاعات (INCLUDE AND EXCLUDE REFERENCES)

می‌توانید مشخص کنید که git lfs migrate فقط فایل‌های اضافه‌شده در کامیت‌های در دسترس از ارجاعات خاص را تبدیل کند، یعنی ارجاعاتی که با استفاده از یک یا چند گزینه --include-ref تعریف شده‌اند، و فایل‌های موجود در کامیت‌های در دسترس از ارجاعات تعریف‌شده در گزینه‌های --exclude-ref را نادیده بگیرد.

      D---E---F
     /         \
A---B------C    refs/heads/my-feature
 \          \
  \          refs/heads/main
   \
    refs/remotes/origin/main

در پیکربندی بالا، کامیت‌های زیر توسط هر ارجاع قابل دسترسی هستند:

refs/heads/main:           C, B, A
refs/heads/my-feature:     F, E, D, B, A
refs/remote/origin/main:   A

بنابراین، گزینه‌های زیر در git lfs migrate کامیت‌های F، E، D، C، و B را شامل شده، اما کامیت A را مستثنی می‌کنند:

--include-ref=refs/heads/my-feature
--include-ref=refs/heads/main
--exclude-ref=refs/remotes/origin/main

وجود فلگ --everything نشان می‌دهد که تمام کامیت‌های در دسترس از کلیه ارجاعات محلی و دوردست باید مهاجرت داده شوند (اما توجه داشته باشید که خود ارجاعات دوردست به‌روزرسانی نخواهند شد).

مثال‌ها (EXAMPLES)

$ git lfs migrate info
Fetching remote refs: ..., done
Sorting commits: ..., done
Examining commits: 100% (1/1), done
*.mp3   284 MB    1/1 files(s)  100%
*.pdf   42 MB     8/8 files(s)  100%
*.psd   9.8 MB  15/15 files(s)  100%
*.ipynb 6.9 MB    6/6 files(s)  100%
*.csv   5.8 MB    2/2 files(s)  100%

$ git lfs migrate import --include="*.mp3,*.psd"
Fetching remote refs: ..., done
Sorting commits: ..., done
Rewriting commits: 100% (1/1), done
  main  d2b959babd099fe70da1c1512e2475e8a24de163 -> 136e706bf1ae79643915c134e17a6c933fd53c61
Updating refs: ..., done

# بررسی فایل‌های بزرگ و اشیاء موجود Git LFS در شاخه اصلی محلی
$ git lfs migrate info --include-ref=main
# بررسی فایل‌های بزرگ و اشیاء موجود Git LFS در تمام شاخه‌ها
$ git lfs migrate info --everything
# بررسی فایل‌های بزرگ در تمام شاخه‌ها با نادیده گرفتن اشیاء موجود Git LFS،
# و فهرست کردن ۱۰۰ نتیجه برتر یا کمتر
$ git lfs migrate info --everything --pointers=ignore --top=100

# تبدیل تمام فایل‌های zip در شاخه اصلی شما
$ git lfs migrate import --include-ref=main --include="*.zip"
# تبدیل تمام فایل‌های zip در تمام شاخه‌های محلی
$ git lfs migrate import --everything --include="*.zip"
# تبدیل تمام فایل‌های بزرگتر از 100K در تمام شاخه‌های محلی
$ git lfs migrate import --everything --above=100Kb

$ git lfs track "*.zip" "*.mp3" "*.psd"
$ git add .gitattributes
$ git commit -m "add Git LFS attributes"
$ git lfs migrate import --no-rewrite --yes test.zip audios/*.mp3 images/*.psd

$ git lfs track "*.zip" "*.mp3" "*.psd"
$ git add .gitattributes
$ git commit -m "add Git LFS attributes"
$ git lfs migrate import --no-rewrite --yes \
  -m "Import test.zip, audios/*.mp3, and images/*.psd files" \
  test.zip audios/*.mp3 images/*.psd

$ git lfs migrate import --no-rewrite --yes \
  $(find . -name "*.zip" -o -name "*.mp3" -o -name "*.psd" | sed "s/^\.\///")

$ git lfs track "*.zip" "*.mp3" "*.psd"
$ git add .gitattributes
$ git add --renormalize .
$ git commit -m "Import all *.zip, *.mp3, and *.psd files to Git LFS"

# تبدیل تمام اشیاء Git LFS نوع zip به فایل در شاخه اصلی شما
$ git lfs migrate export --include-ref=main --include="*.zip"
# تبدیل تمام اشیاء Git LFS نوع zip به فایل در تمام شاخه‌های محلی،
# و واکشی داده‌های اشیایی که به صورت محلی کش نشده‌اند از مخزن دوردست my-remote
$ git lfs migrate export --everything --include="*.zip" --remote=my-remote
# تبدیل تمام اشیاء Git LFS به فایل در تمام شاخه‌های محلی
$ git lfs migrate export --everything --include="*"

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

git-lfs-checkout(1), git-lfs-ls-files(1), git-lfs-track(1), git-lfs-untrack(1), gitattributes(5), gitignore(5).

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