.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-INSTALL" "1" "September 2025" ""
.SH "نام (NAME)"
\fBbundle\-install\fR \- وابستگی‌های مشخص‌شده در Gemfile را نصب می‌کند
.SH "خلاصه دستور (SYNOPSIS)"
\fBbundle install\fR [\-\-force] [\-\-full\-index] [\-\-gemfile=GEMFILE] [\-\-jobs=NUMBER] [\-\-local] [\-\-lockfile=LOCKFILE] [\-\-no\-cache] [\-\-no\-lock] [\-\-prefer\-local] [\-\-quiet] [\-\-retry=NUMBER] [\-\-standalone[=GROUP[ GROUP\|\.\|\.\|\.]]] [\-\-trust\-policy=TRUST\-POLICY] [\-\-target\-rbconfig=TARGET\-RBCONFIG]
.SH "توضیحات (DESCRIPTION)"
بسته‌های gem مشخص‌شده در Gemfile(5) شما را نصب می‌کند\. اگر این نخستین باری است که bundle install را اجرا می‌کنید (و فایل \fBGemfile\.lock\fR وجود ندارد)، Bundler تمام منابع دوردست (remote) را واکشی کرده، وابستگی‌ها را حل‌وفصل می‌کند و تمامی gemهای مورد نیاز را نصب می‌نماید\.
.P
اگر فایل \fBGemfile\.lock\fR وجود داشته باشد و شما Gemfile(5) خود را به‌روزرسانی نکرده باشید، Bundler تمام منابع دوردست را واکشی می‌کند، اما به جای حل‌وفصل وابستگی‌ها، از وابستگی‌های مشخص‌شده در \fBGemfile\.lock\fR استفاده خواهد کرد\.
.P
اگر فایل \fBGemfile\.lock\fR وجود داشته باشد و شما Gemfile(5) خود را به‌روزرسانی کرده باشید، Bundler از وابستگی‌های موجود در \fBGemfile\.lock\fR برای تمامی gemهایی که به‌روزرسانی نکرده‌اید استفاده می‌کند، اما وابستگی‌های gemهایی را که به‌روزرسانی کرده‌اید دوباره حل‌وفصل خواهد کرد\. اطلاعات بیشتر درباره این فرآیند به‌روزرسانی را می‌توانید در بخش \fIبه‌روزرسانی محافظه‌کارانه (CONSERVATIVE UPDATING)\fR در ادامه بیابید\.
.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-\-force\fR, \fB\-\-redownload\fR
نصب مجدد اجباری تمام gemها، حتی اگر از قبل نصب شده باشند\.
.TP
\fB\-\-full\-index\fR
به جای فراخوانی نقطه پایانی API مربوط به Rubygems (پیش‌فرض)، یک فایل نمایه (index) از تمام gemها را که در حال حاضر حجیم است دانلود و کش می‌کند\. با فعال‌سازی این گزینه می‌توان عملکرد را برای بسته‌های بزرگی که به ندرت تغییر می‌کنند بهبود بخشید\.
.TP
\fB\-\-gemfile=GEMFILE\fR
مکان Gemfile(5) که Bundler باید از آن استفاده کند\. مقدار پیش‌فرض آن فایل Gemfile(5) در دایرکتوری کاری جاری است\. به‌طور کلی، Bundler فرض می‌کند که مکان Gemfile(5) همان ریشه پروژه است و تلاش می‌کند \fBGemfile\.lock\fR و \fBvendor/cache\fR را نسبت به این مکان پیدا کند\.
.TP
\fB\-\-jobs=<number>\fR, \fB\-j=<number>\fR
حداکثر تعداد کارهای موازی برای دانلود و نصب\. مقدار پیش‌فرض برابر با تعداد پردازنده‌های در دسترس است\.
.TP
\fB\-\-local\fR
برای اتصال به \fBrubygems\.org\fR تلاشی نمی‌کند\. در عوض، Bundler از gemهایی استفاده می‌کند که از قبل در کش Rubygems یا در \fBvendor/cache\fR موجود هستند\. توجه داشته باشید که اگر gem خاصی مناسب برای پلتفرم در \fBrubygems\.org\fR وجود داشته باشد، پیدا نخواهد شد\.
.TP
\fB\-\-lockfile=LOCKFILE\fR
مکان فایل lockfile که Bundler باید استفاده کند\. مقدار پیش‌فرض آن همان مکان Gemfile است که \fB\.lock\fR به انتهای آن ضمیمه شده است\.
.TP
\fB\-\-prefer\-local\fR
استفاده اجباری از gemهای نصب‌شده به‌صورت محلی، یا gemهایی که از قبل در کش Rubygems یا در \fBvendor/cache\fR موجود هستند در هنگام حل‌وفصل، حتی اگر نسخه‌های جدیدتری از راه دور در دسترس باشند\. تنها برای gemهایی که به‌صورت محلی موجود نیستند اقدام به اتصال به \fBrubygems\.org\fR می‌کند\.
.TP
\fB\-\-no\-cache\fR
کش موجود در \fBvendor/cache\fR را با gemهای تازه بسته‌بندی‌شده به‌روزرسانی نمی‌کند\. این کار هیچ‌یک از gemهای موجود در کش را حذف نمی‌کند، اما از کش شدن gemهای تازه بسته‌بندی‌شده در حین نصب جلوگیری می‌کند\.
.TP
\fB\-\-no\-lock\fR
فایل lockfile ایجاد نمی‌کند\. زمانی کاربرد دارد که می‌خواهید وابستگی‌ها را نصب کنید اما نسخه‌های gemها قفل نشوند\. برای توسعه کتابخانه‌ها و شرایط دیگری که انتظار می‌رود کد با طیفی از نسخه‌های وابستگی کار کند، توصیه می‌شود\.
.IP
این گزینه همان اثری را دارد که استفاده از \fBlockfile false\fR در Gemfile ایجاد می‌کند\. برای اطلاعات بیشتر به gemfile(5) مراجعه کنید\.
.TP
\fB\-\-quiet\fR
اطلاعات پیشرفت را در خروجی استاندارد چاپ نمی‌کند\.
.TP
\fB\-\-retry=[<number>]\fR
درخواست‌های ناموفق شبکه یا git را به تعداد \fInumber\fR بار تکرار می‌کند\.
.TP
\fB\-\-standalone[=<list>]\fR
بسته‌ای ایجاد می‌کند که می‌تواند در زمان اجرا بدون وابستگی به Rubygems یا Bundler کار کند\. می‌توان فهرستی از گروه‌ها را که با فاصله جدا شده‌اند برای نصب مشخص کرد\. Bundler دایرکتوری با نام \fBbundle\fR ایجاد کرده و بسته را در آنجا نصب می‌کند\. همچنین یک فایل \fBbundle/bundler/setup\.rb\fR ایجاد می‌کند تا طبق نیاز جایگزین راه‌اندازی پیش‌فرض Bundler شود\.
.TP
\fB\-\-trust\-policy=TRUST\-POLICY\fR
سیاست امنیتی Rubygems با نام \fIpolicy\fR را اعمال می‌کند، که در آن policy یکی از مقادیر \fBHighSecurity\fR، \fBMediumSecurity\fR، \fBLowSecurity\fR، \fBAlmostNoSecurity\fR، یا \fBNoSecurity\fR است\. برای جزئیات بیشتر، لطفاً به مستندات امضای Rubygems که پیوند آن در بخش \fIهمچنین ببینید (SEE ALSO)\fR آمده است مراجعه کنید\.
.TP
\fB\-\-target\-rbconfig=TARGET\-RBCONFIG\fR
مسیر rbconfig\.rb برای پلتفرم هدف استقرار\.
.SH "حالت استقرار (DEPLOYMENT MODE)"
پیش‌فرض‌های Bundler برای محیط توسعه بهینه‌سازی شده‌اند\. برای تغییر به پیش‌فرض‌های بهینه‌سازی‌شده برای استقرار و CI، از تنظیمات \fBdeployment\fR استفاده کنید\. حالت استقرار را روی رایانه‌های توسعه فعال نکنید، زیرا هنگام تغییر Gemfile(5) باعث ایجاد خطا می‌شود\.
.IP "1." 4
وجود \fBGemfile\.lock\fR الزامی است\.
.IP
برای اطمینان از اینکه همان نسخه‌هایی از gemها که هنگام توسعه و آزمایش استفاده کرده‌اید در استقرار نیز به کار می‌روند، وجود \fBGemfile\.lock\fR الزامی است\.
.IP
این موضوع عمدتاً برای اطمینان از این است که سپردن (commit) فایل \fBGemfile\.lock\fR خود را به سیستم کنترل نسخه فراموش نکنید\.
.IP "2." 4
فایل \fBGemfile\.lock\fR باید به‌روز باشد
.IP
در محیط توسعه، می‌توانید Gemfile(5) خود را تغییر داده و دوباره \fBbundle install\fR را اجرا کنید تا وضعیت لحظه‌ای (snapshot) فایل \fBGemfile\.lock\fR خود را \fIبه‌طور محافظه‌کارانه به‌روزرسانی کنید\fR\.
.IP
در محیط استقرار، فایل \fBGemfile\.lock\fR شما باید با تغییرات اعمال‌شده در Gemfile(5) کاملاً به‌روز باشد\.
.IP "3." 4
بسته‌های gem در \fBvendor/bundle\fR نصب می‌شوند، نه در مکان پیش‌فرض سیستم شما
.IP
در محیط توسعه، به اشتراک گذاشتن gemهای مورد استفاده در برنامه‌تان با سایر برنامه‌ها و اسکریپت‌هایی که روی سیستم اجرا می‌شوند راحت‌تر است\.
.IP
در محیط استقرار، ایزوله‌سازی یک پیش‌فرض مهم‌تر است\. علاوه بر این، کاربری که برنامه را مستقر می‌کند ممکن است مجوز نصب gemها را روی سیستم نداشته باشد، یا وب‌سرور ممکن است اجازه خواندن آن‌ها را نداشته باشد\.
.IP
در نتیجه، هنگامی که \fBdeployment\fR پیکربندی شده باشد، دستور \fBbundle install\fR بسته‌های gem را در دایرکتوری \fBvendor/bundle\fR درون برنامه نصب می‌کند\. این رفتار را می‌توان با استفاده از تنظیمات \fBpath\fR بازنویسی کرد\.
.IP "" 0
.SH "نصب گروه‌ها (INSTALLING GROUPS)"
به‌طور پیش‌فرض، \fBbundle install\fR تمام gemهای موجود در تمام گروه‌های Gemfile(5) شما را نصب می‌کند، به جز مواردی که برای پلتفرم دیگری اعلان شده‌اند\.
.P
با این حال، می‌توانید صراحتاً با استفاده از تنظیمات \fBwithout\fR به Bundler بگویید که از نصب گروه‌های خاصی صرف‌نظر کند\. این تنظیم فهرستی از گروه‌ها را که با فاصله جدا شده‌اند دریافت می‌کند\.
.P
با اینکه تنظیم \fBwithout\fR از \fIنصب\fR gemها در گروه‌های مشخص‌شده صرف‌نظر می‌کند، \fBbundle install\fR همچنان آن gemها را \fIدانلود\fR کرده و از آن‌ها برای حل‌وفصل وابستگی‌های هر gem در Gemfile(5) شما استفاده می‌کند\.
.P
این رفتار برای آن است که نصب مجموعه‌ای متفاوت از گروه‌ها روی سیستمی دیگر (مانند یک سرور پروداکشن) باعث تغییر gemها و نسخه‌هایی نشود که قبلاً بر اساس آن‌ها توسعه و آزمایش را انجام داده‌اید\.
.P
\fBBundler تضمین بسیار محکمی می‌دهد کدی شخص‌ثالثی که در توسعه و آزمایش اجرا می‌کنید، دقیقاً همان کد شخص‌ثالثی است که در محیط پروداکشن اجرا می‌کنید\. شما می‌توانید انتخاب کنید که بخشی از آن کد در محیط‌های مختلف نادیده گرفته شود، اما هرگز با استفاده غیرمنتظره از نسخه‌های متفاوتی از کد شخص‌ثالث در محیط‌های گوناگون غافلگیر نخواهید شد\.\fR
.P
برای یک نمونه ساده، Gemfile(5) زیر را در نظر بگیرید:
.IP "" 4
.nf
source 'https://rubygems\.org'

gem 'sinatra'

group :production do
  gem 'rack\-perftools\-profiler'
end
.fi
.IP "" 0
.P
در این حالت، \fBsinatra\fR به هر نسخه‌ای از Rack وابسته است (\fB>= 1\.0\fR)، در حالی که \fBrack\-perftools\-profiler\fR به نسخه 1\.x وابسته است (\fB~> 1\.0\fR)\.
.P
وقتی دستور \fBbundle config without production\fR را در محیط توسعه پیکربندی می‌کنید، وابستگی‌های \fBrack\-perftools\-profiler\fR نیز بررسی می‌شوند\. به این ترتیب، تمام وقت خود را صرف توسعه بر پایه Rack 2\.0 و استفاده از APIهای جدید ناموجود در Rack 1\.x نمی‌کنید، تا در نهایت وقتی از گروه \fBproduction\fR استفاده \fIمی‌شود\fR، Bundler ناگهان به Rack 1\.2 بازگردد\.
.P
این موضوع در عمل نباید مشکلی ایجاد کند، زیرا ما تلاشی برای \fBنصب\fR gemها در گروه‌های مستثنی‌شده نمی‌کنیم و آن‌ها تنها به عنوان بخشی از فرآیند حل‌وفصل وابستگی‌ها ارزیابی می‌شوند\.
.P
این همچنین بدان معناست که نمی‌توانید نسخه‌های متفاوتی از یک gem یکسان را در گروه‌های مختلف قرار دهید، زیرا انجام این کار منجر به استفاده از مجموعه‌های متفاوتی از وابستگی‌ها در محیط‌های توسعه و پروداکشن خواهد شد\. به دلیل پیچیدگی‌های فرآیند حل‌وفصل وابستگی، این امر معمولاً فراتر از gemهای فهرست‌شده در Gemfile(5) تأثیر می‌گذارد و می‌تواند به شکلی چشمگیر gemهایی را که استفاده می‌کنید دگرگون کند\.
.SH "فایل GEMFILE.LOCK (THE GEMFILE.LOCK)"
هنگامی که \fBbundle install\fR را اجرا می‌کنید، Bundler نام‌های کامل و نسخه‌های تمام gemهایی را که استفاده کرده‌اید (از جمله وابستگی‌های gemهای مشخص‌شده در Gemfile(5)) در فایلی به نام \fBGemfile\.lock\fR ذخیره و ماندگار می‌کند\.
.P
دستور Bundler در تمام فراخوانی‌های بعدی \fBbundle install\fR از این فایل استفاده می‌کند، که تضمین می‌نماید شما همیشه دقیقاً از همان کد استفاده می‌کنید، حتی زمانی که برنامه‌تان بین رایانه‌های مختلف جابه‌جا شود\.
.P
به دلیل شیوه کارکرد حل‌وفصل وابستگی‌ها، حتی یک تغییر به ظاهر کوچک (برای مثال، به‌روزرسانی به یک انتشار فرعی از وابستگی یکی از gemها در Gemfile(5)) می‌تواند به نیاز به gemهایی کاملاً متفاوت برای برآورده کردن تمام وابستگی‌ها منجر شود\.
.P
در نتیجه، شما \fBباید\fR فایل \fBGemfile\.lock\fR خود را، چه در برنامه‌ها و چه در gemها، به سیستم کنترل نسخه اضافه کنید\. اگر این کار را نکنید، هر سیستمی که مخزن شما را دریافت کند (از جمله سرور پروداکشن شما) دوباره تمام وابستگی‌ها را حل‌وفصل خواهد کرد، که در صورت به‌روزرسانی \fBهر یک\fR از gemها در Gemfile(5) یا هر کدام از وابستگی‌های آن‌ها، منجر به استفاده از نسخه‌های متفاوتی از کد شخص‌ثالث خواهد شد\.
.P
هنگامی که Bundler برای اولین بار عرضه شد، فایل \fBGemfile\.lock\fR درون فایل \fB\.gitignore\fR پیش‌فرض به همراه gemهای تولیدشده قرار داشت\. اما با گذشت زمان، مشخص شد که این رویه دردسرهای ناشی از وابستگی‌های خراب را به مشارکت‌کنندگان جدید تحمیل می‌کند، در حالی که مشارکت‌کنندگان فعلی را احتمالاً از مشکل بی‌خبر می‌گذارد\. از آنجا که \fBbundle install\fR معمولاً نخستین گام برای مشارکت در پروژه است، دردسر وابستگی‌های ناقص مشارکت‌کنندگان جدید را دلسرد می‌کرد\. در نتیجه، ما راهنمای خود را برای توسعه‌دهندگان gem بازبینی کرده‌ایم و اکنون ثبت کردن فایل قفل را برای gemها نیز توصیه می‌کنیم\.
.SH "به‌روزرسانی محافظه‌کارانه (CONSERVATIVE UPDATING)"
هنگامی که تغییری در Gemfile(5) ایجاد می‌کنید و سپس \fBbundle install\fR را اجرا می‌نمایید، Bundler تنها gemهایی را که تغییر داده‌اید به‌روزرسانی خواهد کرد\.
.P
به عبارت دیگر، اگر gemی که شما آن را \fBتغییر نداده‌اید\fR پیش از اجرای \fBbundle install\fR کار می‌کرده است، همچنان به استفاده از دقیقاً همان نسخه‌های تمامی وابستگی‌هایی که پیش از به‌روزرسانی استفاده می‌کرد ادامه خواهد داد\.
.P
بیایید به یک مثال نگاه کنیم\. این Gemfile(5) اولیه شماست:
.IP "" 4
.nf
source 'https://rubygems\.org'

gem 'actionpack', '2\.3\.8'
gem 'activemerchant'
.fi
.IP "" 0
.P
در این حالت، هر دو بسته \fBactionpack\fR و \fBactivemerchant\fR به \fBactivesupport\fR وابسته هستند\. بسته \fBactionpack\fR به \fBactivesupport 2\.3\.8\fR و \fBrack ~> 1\.1\.0\fR وابسته است، در حالی که بسته \fBactivemerchant\fR به \fBactivesupport >= 2\.3\.2\fR، \fBbraintree >= 2\.0\.0\fR، و \fBbuilder >= 2\.0\.0\fR وابستگی دارد\.
.P
هنگامی که وابستگی‌ها برای نخستین بار حل‌وفصل می‌شوند، Bundler نسخه \fBactivesupport 2\.3\.8\fR را انتخاب می‌کند، که نیازهای هر دو gem موجود در Gemfile(5) شما را برآورده می‌سازد\.
.P
سپس، شما Gemfile(5) خود را بدین صورت تغییر می‌دهید:
.IP "" 4
.nf
source 'https://rubygems\.org'

gem 'actionpack', '3\.0\.0\.rc'
gem 'activemerchant'
.fi
.IP "" 0
.P
بسته \fBactionpack 3\.0\.0\.rc\fR شامل تعدادی وابستگی جدید است، و وابستگی \fBactivesupport\fR را به \fB= 3\.0\.0\.rc\fR و وابستگی \fBrack\fR را به \fB~> 1\.2\.1\fR به‌روزرسانی می‌کند\.
.P
وقتی \fBbundle install\fR را اجرا می‌کنید، Bundler متوجه می‌شود که شما بسته \fBactionpack\fR را تغییر داده‌اید، اما بسته \fBactivemerchant\fR دست‌نخورده باقی مانده است\. بنابراین بسته‌هایی را که در حال حاضر برای برآورده کردن نیازمندی‌های آن استفاده می‌شوند ارزیابی می‌کند:
.TP
\fBactivesupport 2\.3\.8\fR
همچنین برای برآورده کردن یک وابستگی در \fBactivemerchant\fR استفاده شده است، که در حال حاضر به‌روزرسانی نمی‌شود
.TP
\fBrack ~> 1\.1\.0\fR
در حال حاضر برای برآورده کردن وابستگی دیگری استفاده نمی‌شود
.P
از آنجا که شما صراحتاً به‌روزرسانی \fBactivemerchant\fR را درخواست نکرده‌اید، انتظار ندارید که پس از به‌روزرسانی \fBactionpack\fR ناگهان از کار بیفتد\. با این حال، برآورده کردن وابستگی جدید \fBactivesupport 3\.0\.0\.rc\fR در actionpack نیازمند به‌روزرسانی یکی از وابستگی‌های آن است\.
.P
اگرچه \fBactivemerchant\fR وابستگی بسیار منعطفی را تعریف کرده که از نظر تئوری با \fBactivesupport 3\.0\.0\.rc\fR همخوانی دارد، اما Bundler با بسته‌هایی در Gemfile(5) که تغییر نکرده‌اند همراه با وابستگی‌هایشان به عنوان یک واحد یکپارچه (اتمیک) برخورد می‌کند\. در این مورد، وابستگی \fBactivemerchant\fR به صورت \fBactivemerchant 1\.7\.1 + activesupport 2\.3\.8\fR در نظر گرفته می‌شود، بنابراین \fBbundle install\fR گزارش می‌دهد که نمی‌تواند \fBactionpack\fR را به‌روزرسانی کند\.
.P
برای به‌روزرسانی صریح \fBactionpack\fR، از جمله وابستگی‌های آن که سایر gemهای موجود در Gemfile(5) همچنان به آن‌ها وابسته‌اند، دستور \fBbundle update actionpack\fR را اجرا کنید (به \fBbundle update(1)\fR مراجعه نمایید)\.
.P
\fBخلاصه\fR: به‌طور کلی، پس از ایجاد تغییر در Gemfile(5)، ابتدا باید اجرای \fBbundle install\fR را امتحان کنید، که تضمین می‌کند هیچ gem دیگری در Gemfile(5) تحت تأثیر این تغییر قرار نخواهد گرفت\. اگر این کار نتیجه نداد، دستور bundle update(1) \fIbundle\-update\.1\.html\fR را اجرا کنید\.
.SH "همچنین ببینید (SEE ALSO)"
.IP "\(bu" 4
مستندات نصب Gem \fIhttps://guides\.rubygems\.org/rubygems\-basics/#installing\-gems\fR
.IP "\(bu" 4
مستندات امضای Rubygems \fIhttps://guides\.rubygems\.org/security\fR
.IP "" 0