نام (NAME)

gdal-vsi-sync - همگام‌سازی فایل یا دایرکتوری مبدأ و مقصد در واسط سیستم مجازی GDAL (VSI)

در نسخه 3.11 اضافه شد.

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

Usage: gdal vsi sync [OPTIONS] <SOURCE> <DESTINATION>
همگام‌سازی فایل یا دایرکتوری مبدأ و مقصد در واسط سیستم مجازی GDAL (VSI).
آرگومان‌های موقعیتی:
  --source <SOURCE>                نام فایل یا دایرکتوری مبدأ [الزامی]
  --destination <DESTINATION>      نام فایل یا دایرکتوری مقصد [الزامی]
گزینه‌های عمومی:
  -h, --help                       نمایش پیام راهنما و خروج
  --json-usage                     نمایش نحوه استفاده به صورت سند JSON و خروج
  --config <KEY>=<VALUE>           گزینه پیکربندی [قابل تکرار]
  -q, --quiet                      حالت ساکت (بدون نوار پیشرفت یا پیام هشدار) [در خطوط لوله در دسترس نیست]
گزینه‌ها:
  -r, --recursive                  همگام‌سازی به صورت بازگشتی
  --strategy <STRATEGY>            راهبرد همگام‌سازی. STRATEGY=timestamp|ETag|overwrite (پیش‌فرض: timestamp)
  -j, --num-threads <NUM-THREADS>  تعداد وظایف همزمان (یا ALL_CPUS)

توضیحات (DESCRIPTION)

دستور gdal vsi sync فایل‌ها و دایرکتوری‌های واقع در سیستم‌های فایل مجازی GDAL (فشرده‌شده، میزبانی‌شده در شبکه و غیره: /vsimem، /vsizip، /vsitar، /vsicurl و...) را همگام‌سازی می‌کند.

این ابزار مشابه دستور rsync در یونیکس است. در پیاده‌سازی فعلی، rsync برای کپی محلی فایل‌ها کارآمدتر است، اما مزیت اصلی gdal vsi sync زمانی است که مبدأ یا مقصد یک سیستم فایل راه دور مانند /vsis3/ یا /vsigs/ باشد؛ در این حالت می‌تواند زمان ثبت فایل‌ها (یا به صورت اختیاری ETag/MD5Sum) را در نظر بگیرد تا از عملیات کپی غیرضروری جلوگیری شود.

این عملکرد به صورت بهینه برای موارد زیر پیاده‌سازی شده است:

سیستم فایل محلی <--> سیستم فایل راه دور.
سیستم فایل راه دور <--> سیستم فایل راه دور، جایی که سیستم‌های فایل مبدأ و مقصد یکسان و یکی از /vsis3/، /vsigs/ یا /vsiaz/ باشند؛ یا وقتی مقصد /vsiaz/ و مبدأ یکی از /vsis3/، /vsigs/، /vsiadls/ یا /vsicurl/ باشد.

مشابه با رفتار rsync، اگر نام فایل مبدأ با یک اسلش به پایان برسد، به این معناست که محتوای دایرکتوری باید کپی شود، نه خود نام دایرکتوری. برای مثال، با فرض اینکه /home/even/foo حاوی فایل bar باشد، اجرای gdal vsi sync -r /home/even/foo/ /mnt/media فایل /mnt/media/bar را ایجاد می‌کند. در حالی که اجرای gdal vsi sync -r /home/even/foo /mnt/media دایرکتوری /mnt/media/foo را ایجاد می‌کند که حاوی فایل bar است.

این ویژگی توسط VSISync() پیاده‌سازی شده است.

گزینه‌ها (OPTIONS)

-r, --recursive: همگام‌سازی به صورت بازگشتی.

--strategy timestamp|ETag|overwrite

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

مقدار پیش‌فرض timestamp است (مشابه نحوه عملکرد aws s3 sync). برای عملیات بارگذاری (upload)، فایل راه دور در صورتی که اندازه متفاوتی داشته باشد یا قدیمی‌تر از فایل مبدأ باشد، جایگزین می‌شود. برای عملیات بارگیری (download)، فایل محلی در صورتی که اندازه متفاوتی داشته باشد یا جدیدتر از فایل راه دور باشد، جایگزین می‌شود.

راهبرد ETag فرض می‌کند که متادیتای ETag فایل راه دور، همان MD5Sum محتوای فایل است که این فرض تنها در مورد /vsis3/ برای فایل‌هایی که از رمزنگاری سمت سرور KMS استفاده نمی‌کنند و در یک عملیات تک‌مرحله‌ای PUT بارگذاری شده‌اند (بنابراین با توجه به مقدار پیش‌فرض GDAL، کوچکتر از ۵۰ مگابایت هستند) صادق است. این گزینه تنها باید برای /vsis3/، /vsigs/ یا سایر سیستم‌های فایلی که از MD5Sum به عنوان ETag استفاده می‌کنند به کار رود.

راهبرد overwrite همواره فایل مقصد را با فایل مبدأ بازنویسی می‌کند.

-j, --num-threads <value>: تعداد وظایف همزمان برای اجرا

کد وضعیت خروج (RETURN STATUS CODE)

این برنامه در صورت موفقیت کد وضعیت ۰ و در صورت بروز خطا مقدار غیرصفر را برمی‌گرداند (خطاهای غیرمسدودکننده که به صورت هشدار صادر می‌شوند، به عنوان اجرای موفق در نظر گرفته می‌شوند).

مثال‌ها (EXAMPLES)

مثال ۱: همگام‌سازی یک دایرکتوری محلی روی یک باکت S3

$ gdal vsi sync -r my_directory/ /vsis3/bucket/my_directory

نویسندگان (AUTHORS)

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026