BUNDLE-UPDATE(1) General Commands Manual BUNDLE-UPDATE(1)

bundle-update - به‌روزرسانی gemها به آخرین نسخه‌های موجود

bundle update *gems [--all] [--group=NAME] [--source=NAME] [--local] [--ruby] [--bundler[=VERSION]] [--force] [--full-index] [--gemfile=GEMFILE] [--jobs=NUMBER] [--quiet] [--patch|--minor|--major] [--pre] [--strict] [--conservative]

gemهای مشخص‌شده (در صورت استفاده از پرچم --all تمام gemها) را به‌روزرسانی می‌کند و gemهای نصب‌شدهٔ پیشین مشخص‌شده در Gemfile.lock را نادیده می‌گیرد. به‌طور کلی، باید از bundle install(1) bundle-install.1.html برای نصب دقیقاً همان gemها و نسخه‌ها در تمامی ماشین‌ها استفاده کنید.

برای به‌روزرسانی صریح نسخهٔ یک gem، از bundle update استفاده می‌کنید.

به‌روزرسانی تمامی gemهای مشخص‌شده در Gemfile.
تنها gemهای موجود در گروه مشخص‌شده را به‌روزرسانی می‌کند. برای نمونه، می‌توانید تمام gemهای گروه development را با دستور bundle update --group development به‌روزرسانی کنید. همچنین می‌توانید برای مثال دستور bundle update rails --group test را فراخوانی کنید تا gem مربوط به rails و تمام gemهای گروه test به‌روزرسانی شوند.
نام منبع :git یا :path استفاده‌شده در Gemfile(5). برای نمونه، با منبع :git به نشانی http://github.com/rails/rails.git، دستور bundle update --source rails را فراخوانی می‌کنید.
از تلاش برای دریافت gemها از راه دور خودداری کرده و به‌جای آن از حافظهٔ موقت (کَش) gem استفاده می‌کند.
نسخهٔ قفل‌شدهٔ Ruby را به نسخهٔ فعلی Ruby به‌روزرسانی می‌کند.
نسخهٔ قفل‌شدهٔ bundler را به نسخهٔ فعلی اجراشده از bundler به‌روزرسانی می‌کند.
نصب مجدد اجباری تمام gemها، حتی اگر از قبل نصب شده باشند.
بازگشت به استفاده از نمایهٔ تک‌فایلی تمام gemها.
استفاده از فایل gem مشخص‌شده به‌جای [Gemfile(5)][Gemfile(5)].
مشخص کردن تعداد کارهایی که به‌طور هم‌زمان اجرا می‌شوند. مقدار پیش‌فرض برابر با تعداد پردازنده‌های در دسترس است.
تلاش مجدد برای درخواست‌های ناموفق شبکه یا git به تعداد number بار.
تنها هشدارها و خطاها را در خروجی نمایش می‌دهد.
ترجیح دادن به‌روزرسانی تنها به نسخهٔ وصله (patch) بعدی.
ترجیح دادن به‌روزرسانی تنها به نسخهٔ فرعی (minor) بعدی.
ترجیح دادن به‌روزرسانی به نسخهٔ اصلی (major) بعدی (پیش‌فرض).
همواره بالاترین نسخهٔ مجاز را بدون در نظر گرفتن وضعیت پیش‌انتشار (prerelease) انتخاب می‌کند.
اجازه نمی‌دهد هیچ gemای فراتر از آخرین نسخه بر اساس --patch | --minor | --major به‌روزرسانی شود.
استفاده از رفتار به‌روزرسانی محتاطانهٔ bundle install و عدم اجازه برای به‌روزرسانی وابستگی‌های غیرمستقیم.

اگر دستور bundle update --all را اجرا کنید، bundler هرگونه gem نصب‌شدهٔ قبلی را نادیده گرفته و تمام وابستگی‌ها را مجدداً بر اساس آخرین نسخه‌های موجود تمامی gemها در منابع حل (resolve) می‌کند.

Gemfile(5) زیر را در نظر بگیرید:

source "https://rubygems.org"
gem "rails", "3.0.0.rc"
gem "nokogiri"

هنگامی که برای نخستین بار bundle install(1) bundle-install.1.html را اجرا می‌کنید، bundler تمام وابستگی‌ها را تا پایین‌ترین سطح حل کرده و آنچه را نیاز دارید نصب می‌کند:

Fetching gem metadata from https://rubygems.org/.........
Resolving dependencies...
Installing builder 2.1.2
Installing abstract 1.0.0
Installing rack 1.2.8
Using bundler 1.7.6
Installing rake 10.4.0
Installing polyglot 0.3.5
Installing mime-types 1.25.1
Installing i18n 0.4.2
Installing mini_portile 0.6.1
Installing tzinfo 0.3.42
Installing rack-mount 0.6.14
Installing rack-test 0.5.7
Installing treetop 1.4.15
Installing thor 0.14.6
Installing activesupport 3.0.0.rc
Installing erubis 2.6.6
Installing activemodel 3.0.0.rc
Installing arel 0.4.0
Installing mail 2.2.20
Installing activeresource 3.0.0.rc
Installing actionpack 3.0.0.rc
Installing activerecord 3.0.0.rc
Installing actionmailer 3.0.0.rc
Installing railties 3.0.0.rc
Installing rails 3.0.0.rc
Installing nokogiri 1.6.5
Bundle complete! 2 Gemfile dependencies, 26 gems total.
Use `bundle show [gemname]` to see where a bundled gem is installed.

همان‌طور که مشاهده می‌کنید، اگرچه تنها دو gem در Gemfile(5) دارید، اما برنامه شما برای اجرا به ۲۶ gem مختلف نیاز دارد. برنامهٔ bundler نسخه‌های دقیق نصب‌شده را در Gemfile.lock ذخیره می‌کند. دفعهٔ بعد که bundle install(1) bundle-install.1.html را اجرا کنید، bundler از مرحلهٔ حل وابستگی‌ها صرف‌نظر کرده و همان gemهایی را نصب می‌کند که دفعه پیش نصب کرده بود.

پس از ثبت کردن (commit) فایل Gemfile.lock در سامانهٔ کنترل نسخه و کلون کردن آن روی ماشینی دیگر، اجرای bundle install(1) bundle-install.1.html همچنان همان gemهایی را نصب خواهد کرد که دفعه پیش نصب کرده بودید. لازم نیست نگران باشید که نسخه جدیدی از erubis یا mail باعث تغییر gemهای مورداستفاده شما شود.

با این حال، هر از چند گاهی ممکن است بخواهید gemهای مورد استفادهٔ خود را به جدیدترین نسخه‌هایی که همچنان با مشخصات Gemfile(5) شما مطابقت دارند به‌روزرسانی کنید.

برای انجام این کار، دستور bundle update --all را اجرا کنید که Gemfile.lock را نادیده گرفته و تمام وابستگی‌ها را مجدداً حل می‌کند. به یاد داشته باشید که این فرایند می‌تواند بر اساس نیازمندی‌های gemهای جدیدی که سازندگان آن‌ها از زمان آخرین اجرای bundle update --all منتشر کرده‌اند، به مجموعه‌ای کاملاً متفاوت از آن ۲۵ gem منجر شود.

گاهی اوقات می‌خواهید یک gem منفرد را در Gemfile(5) به‌روزرسانی کنید و بقیهٔ gemهایی را که مشخص کرده‌اید روی همان نسخه‌های موجود در Gemfile.lock قفل نگه دارید.

برای نمونه، در سناریوی بالا تصور کنید نسخهٔ 1.4.4 از nokogiri منتشر شده است و شما می‌خواهید آن را بدون به‌روزرسانی Rails و تمام وابستگی‌هایش به‌روز کنید. برای این کار، دستور bundle update nokogiri را اجرا کنید.

برنامهٔ bundler بستهٔ nokogiri و هر یک از وابستگی‌های آن را به‌روزرسانی می‌کند، اما به Rails و وابستگی‌های آن کاری نخواهد داشت.

گاهی اوقات، چندین gem تعریف‌شده در Gemfile(5) شما با یک وابستگی سطح دوم مشترک برآورده می‌شوند. برای نمونه، مورد thin و rack-perftools-profiler را در نظر بگیرید:

source "https://rubygems.org"
gem "thin"
gem "rack-perftools-profiler"

بستهٔ thin به rack >= 1.0 وابسته است، در حالی که rack-perftools-profiler به rack ~> 1.0 وابستگی دارد. اگر bundle install را اجرا کنید، نتیجه به این صورت خواهد بود:

Fetching source index for https://rubygems.org
Installing daemons (1.1.0)
Installing eventmachine (0.12.10) with native extensions
Installing open4 (1.0.1)
Installing perftools.rb (0.4.7) with native extensions
Installing rack (1.2.1)
Installing rack-perftools_profiler (0.0.2)
Installing thin (1.2.7) with native extensions
Using bundler (1.0.0.rc.3)

در این مورد، این دو gem هر کدام مجموعه‌ای از وابستگی‌های خود را دارند، اما در rack مشترک هستند. اگر دستور bundle update thin را اجرا کنید، bundler بسته‌های daemons، eventmachine و rack را که وابستگی‌های thin هستند به‌روزرسانی می‌کند، اما به سراغ open4 یا perftools.rb که وابستگی‌های rack-perftools_profiler هستند نمی‌رود. توجه داشته باشید که bundle update thin بستهٔ rack را به‌روزرسانی خواهد کرد، هرچند که این بسته هم‌زمان وابستگی rack-perftools_profiler نیز محسوب می‌شود.

به‌طور خلاصه، به‌طور پیش‌فرض زمانی که یک gem را با bundle update به‌روزرسانی می‌کنید، bundler تمام وابستگی‌های آن gem را به‌روزرسانی خواهد کرد، از جمله مواردی که هم‌زمان وابستگی gem دیگری نیز هستند.

برای جلوگیری از به‌روزرسانی وابستگی‌های غیرمستقیم، پیش از نسخهٔ 1.14 تنها گزینه رفتار CONSERVATIVE UPDATING در bundle install(1) bundle-install.1.html بود:

در این سناریو، به‌روزرسانی دستی نسخهٔ thin در Gemfile(5) و سپس اجرای bundle install(1) bundle-install.1.html تنها daemons و eventmachine را به‌روزرسانی می‌کند و دست به rack نمی‌زند. برای اطلاعات بیشتر، بخش CONSERVATIVE UPDATING از bundle install(1) bundle-install.1.html را ببینید.

از نسخهٔ 1.14 به بعد، مشخص کردن گزینهٔ --conservative نیز مانع از به‌روزرسانی وابستگی‌های غیرمستقیم می‌شود.

نسخهٔ 1.14 چهار گزینه در سطح وصله (patch-level) معرفی کرد که بر چگونگی حل نسخه‌های gem اثر می‌گذارند. یکی از گزینه‌های زیر را می‌توان استفاده کرد: --patch، --minor یا --major. گزینهٔ --strict را می‌توان برای تأثیر بیشتر بر فرایند حل نسخه اضافه کرد.

ترجیح دادن به‌روزرسانی تنها به نسخهٔ وصله (patch) بعدی.
ترجیح دادن به‌روزرسانی تنها به نسخهٔ فرعی (minor) بعدی.
ترجیح دادن به‌روزرسانی به نسخهٔ اصلی (major) بعدی (پیش‌فرض).
اجازه نمی‌دهد هیچ gemای فراتر از آخرین نسخه بر اساس --patch | --minor | --major به‌روزرسانی شود.

هنگامی که Bundler در حال حل این مسئله است که چه نسخه‌هایی باید برای برآورده کردن پیش‌نیازهای تعریف‌شده در Gemfile یا در gemهای والد استفاده شوند، تمام نسخه‌های موجود را بررسی می‌کند، هر نسخه‌ای را که پیش‌نیاز را برآورده نکند پالایش (فیلتر) می‌کند، و سپس به‌طور پیش‌فرض آن‌ها را از جدیدترین به قدیمی‌ترین مرتب کرده و به همان ترتیب بررسی می‌کند.

ارائهٔ یکی از گزینه‌های سطح وصله (مانند --patch) ترتیب مرتب‌سازی نسخه‌های منطبق را تغییر می‌دهد و سبب می‌شود Bundler آخرین نسخهٔ --patch یا --minor موجود را پیش از دیگر نسخه‌ها در نظر بگیرد. توجه داشته باشید که در صورت نیاز برای یافتن یک گراف وابستگی مناسب، همچنان ممکن است نسخه‌های خارج از سطح وصلهٔ تعیین‌شده انتخاب و حل شوند.

برای نمونه، اگر gem 'foo' روی 1.0.2 قفل شده باشد، بدون اینکه پیش‌نیاز خاصی در Gemfile تعیین شده باشد، و نسخه‌های 1.0.3، 1.0.4، 1.1.0، 1.1.1، 2.0.0 همگی وجود داشته باشند، ترتیب اولویت پیش‌فرض (--major) به صورت "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2" خواهد بود.

اگر گزینهٔ --patch استفاده شود، ترتیب اولویت به "1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0" تغییر خواهد کرد.

اگر گزینهٔ --minor استفاده شود، ترتیب اولویت به "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0" تغییر خواهد یافت.

ترکیب گزینهٔ --strict با هر یک از گزینه‌های سطح وصله، هرگونه نسخه‌ای فراتر از دامنهٔ گزینهٔ سطح وصله را حذف می‌کند تا اطمینان حاصل شود هیچ gemای تا آن حد به‌روزرسانی نشود.

در ادامهٔ مثال پیشین، اگر هر دو گزینهٔ --patch و --strict استفاده شوند، نسخه‌های موجود برای حل وابستگی "1.0.4, 1.0.3, 1.0.2" خواهند بود. اگر --minor و --strict استفاده شوند، این نسخه‌ها "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2" خواهند بود.

پیش‌نیازهای gem همان‌طور که در Gemfile تعریف شده‌اند، همچنان نخستین عامل تعیین‌کننده برای مشخص کردن نسخه‌های موجود خواهند بود. اگر پیش‌نیاز gem برای foo در Gemfile برابر با '~> 1.0' باشد، همان نتیجه‌ای را در بر خواهد داشت که ارائهٔ گزینه‌های --minor و --strict ایجاد می‌کند.

با فرض تعاریف gemهای زیر:

foo 1.4.3, requires: ~> bar 2.0
foo 1.4.4, requires: ~> bar 2.0
foo 1.4.5, requires: ~> bar 2.1
foo 1.5.0, requires: ~> bar 2.1
foo 1.5.1, requires: ~> bar 3.0
bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0

فایل Gemfile:

gem 'foo'

فایل Gemfile.lock:

foo (1.4.3)
  bar (~> 2.0)
bar (2.0.3)

حالت‌ها:

#  Command Line                     Result
------------------------------------------------------------
1  bundle update --patch            'foo 1.4.5', 'bar 2.1.1'
2  bundle update --patch foo        'foo 1.4.5', 'bar 2.1.1'
3  bundle update --minor            'foo 1.5.1', 'bar 3.0.0'
4  bundle update --minor --strict   'foo 1.5.0', 'bar 2.1.1'
5  bundle update --patch --strict   'foo 1.4.4', 'bar 2.0.4'

در حالت ۱، bar به 2.1.1 ارتقا می‌یابد (یک افزایش در نسخهٔ فرعی)، زیرا وابستگی از سمت foo 1.4.5 به آن نیاز داشت.

در حالت ۲، تنها برای foo درخواست باز شدن قفل نسخه شده است، اما bar نیز اجازه جابه‌جایی دارد چرا که به عنوان وابستگی مستقیم در Gemfile تعریف نشده است.

در حالت ۳، بستهٔ bar یک نسخهٔ اصلی کامل ارتقا می‌یابد، زیرا در حال حاضر ارتقای فرعی برای foo ترجیح داده شده است، و زمانی که به 1.5.1 می‌رود، به نسخهٔ 3.0.0 از bar نیاز دارد.

در حالت ۴، برای foo ارتقا تا یک نسخهٔ فرعی ترجیح داده شده است، اما 1.5.1 کار نخواهد کرد زیرا پرچم --strict نسخهٔ bar 3.0.0 را از گزینه‌ها حذف می‌کند چرا که یک افزایش در نسخهٔ اصلی محسوب می‌شود.

در حالت ۵، به دلیل وجود پرچم --strict برای هر دو بستهٔ foo و bar هرگونه افزایش نسخهٔ فرعی یا اصلی از دامنهٔ بررسی حذف می‌شود، بنابراین بیشترین مقداری که می‌توانند ارتقا یابند 1.4.4 و 2.0.4 است.

به‌طور کلی، هنگام کار با برنامه‌ای که با bundler مدیریت می‌شود، باید از گردش کار زیر استفاده کنید:

•
پس از آن‌که Gemfile(5) خود را برای نخستین بار ایجاد کردید، اجرا کنید:
$ bundle install
•
فایل Gemfile.lock حاصل را در سامانهٔ کنترل نسخه ثبت (commit) کنید:
$ git add Gemfile.lock
•
هنگام دریافت (checkout) این مخزن در یک ماشین توسعهٔ دیگر، اجرا کنید:
$ bundle install
•
هنگام دریافت این مخزن در یک ماشین استقرار (deployment)، اجرا کنید:
$ bundle install --deployment
•
پس از تغییر دادن Gemfile(5) برای اعمال یک وابستگی جدید یا به‌روزرسانی‌شده، اجرا کنید:
$ bundle install
•
اطمینان حاصل کنید که Gemfile.lock به‌روزرسانی‌شده را در سامانهٔ کنترل نسخه ثبت کنید:
$ git add Gemfile.lock
•
اگر bundle install(1) bundle-install.1.html تداخلی را گزارش کرد، gemهای خاصی را که در Gemfile(5) تغییر داده‌اید به‌صورت دستی به‌روزرسانی کنید:
$ bundle update rails thin
•
اگر می‌خواهید تمام gemها را به آخرین نسخه‌های ممکنی که همچنان با gemهای فهرست‌شده در Gemfile(5) هم‌خوانی دارند به‌روزرسانی کنید، اجرا کنید:
$ bundle update --all
September 2025