.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "GEMFILE" "5" "سپتامبر 2025" ""
.SH "نام (NAME)"
gemfile \- قالبی برای توصیف وابستگی‌های جم برای برنامه‌های روبی
.SH "خلاصه (SYNOPSIS)"
یک \fBGemfile\fR وابستگی‌های جم (gem) مورد نیاز برای اجرای کد روبی مرتبط را توصیف می‌کند.
.P
فایل \fBGemfile\fR را در ریشه دایرکتوری حاوی کد مربوطه قرار دهید. برای نمونه، در یک برنامه Rails، فایل \fBGemfile\fR را در همان دایرکتوری حاوی \fBRakefile\fR بگذارید.
.SH "نحو (SYNTAX)"
یک \fBGemfile\fR به عنوان کد روبی ارزیابی می‌شود، در محیطی که تعدادی متد را برای توصیف نیازمندی‌های جم در دسترس قرار می‌دهد.
.SH "مخزن سراسری (GLOBAL SOURCE)"
در بالای فایل \fBGemfile\fR، یک سطر منفرد برای منبع \fBRubyGems\fR اضافه کنید که شامل جم‌های فهرست‌شده در \fBGemfile\fR باشد.
.IP "" 4
.nf
source "https://rubygems\.org"
.fi
.IP "" 0
.P
تنها می‌توانید یک منبع سراسری اضافه کنید. در Bundler 1\.13، افزودن چند منبع سراسری منسوخ شد. مقدار \fBsource\fR \fBMUST\fR (باید) یک مخزن معتبر RubyGems باشد.
.P
برای استفاده از بیش از یک منبع RubyGems، باید از بلوک \fI\fBsource\fR\fR استفاده کنید.
.P
یک منبع برای یافتن جم‌ها طبق اصول تشریح‌شده در \fIاولویت منبع (SOURCE PRIORITY)\fR بررسی می‌شود.
.P
\fBنکته درباره رفتار ویژگی منسوخ‌شده در Bundler 1\.13\fR: اگر یک جم در بیش از یک منبع سراسری یافت شود، Bundler پس از نصب جم هشداری چاپ می‌کند که مشخص می‌سازد از کدام منبع استفاده شده است، و سایر منابعی را که جم در آن‌ها موجود است فهرست می‌کند. با استفاده از گزینه \fI\fB:source\fR\fR یا بلوک \fBsource\fR، می‌توان منبع مشخصی را برای جم‌هایی انتخاب کرد که باید از مخزن غیر استاندارد استفاده کنند و این هشدار را بی‌اثر کرد.
.SS "اطلاعات احراز هویت (CREDENTIALS)"
برخی از منابع جم به نام کاربری و گذرواژه نیاز دارند. از دستور bundle config(1) \fIbundle\-config\.1\.html\fR برای تنظیم نام کاربری و گذرواژه برای هر منبعی که به آن نیاز دارد استفاده کنید. این دستور باید یک بار روی هر رایانه‌ای که Gemfile را نصب می‌کند اجرا شود، اما مانع از ذخیره اطلاعات احراز هویت به صورت متن خام در سیستم کنترل نسخه می‌شود.
.IP "" 4
.nf
bundle config gems\.example\.com user:password
.fi
.IP "" 0
.P
برای برخی منابع، مانند حساب شرکتی Gemfury، ممکن است قرار دادن اطلاعات ورود در Gemfile به عنوان بخشی از نشانی اینترنتی منبع ساده‌تر باشد.
.IP "" 4
.nf
source "https://user:password@gems\.example\.com"
.fi
.IP "" 0
.P
اطلاعات احراز هویت موجود در نشانی URL منبع نسبت به موارد تنظیم‌شده از طریق \fBconfig\fR اولویت خواهند داشت.
.SH "روبی (RUBY)"
اگر برنامه شما به نگارش یا موتور روبی خاصی نیاز دارد، نیازمندی‌های خود را با متد \fBruby\fR و آرگومان‌های زیر مشخص کنید. تمام پارامترها \fBOPTIONAL\fR (اختیاری) هستند مگر خلاف آن تصریح شده باشد.
.SS "نگارش (VERSION - الزامی)"
نگارش روبی که برنامه شما نیاز دارد. اگر برنامه شما به یک موتور جایگزین روبی مانند JRuby، TruffleRuby یا غیره نیاز دارد، این باید نگارش روبی باشد که موتور با آن سازگار است.
.IP "" 4
.nf
ruby "3\.1\.2"
.fi
.IP "" 0
.P
اگر مایلید نگارش روبی خود را از یک فایل نگارش (مانند \.ruby\-version) استخراج کنید، می‌توانید به جای آن از گزینه \fBfile\fR استفاده کنید.
.IP "" 4
.nf
ruby file: "\.ruby\-version"
.fi
.IP "" 0
.P
فایل نگارش باید با هر یک از قالب‌های زیر مطابقت داشته باشد:
.IP "\(bu" 4
\fB3\.1\.2\fR (\.ruby\-version)
.IP "\(bu" 4
\fBruby 3\.1\.2\fR (\.tool\-versions، خواندن: https://asdf\-vm\.com/manage/configuration\.html#tool\-versions)
.IP "" 0
.SS "موتور (ENGINE)"
هر برنامه \fImay\fR (می‌تواند) یک موتور روبی را مشخص کند. اگر موتور مشخص شود، نگارش موتور نیز \fImust\fR (باید) تعیین گردد.
.P
دقیقاً موتور چیست؟
.IP "\(bu" 4
موتور روبی پیاده‌سازی از زبان روبی است.
.IP "\(bu" 4
برای پیش‌زمینه: پیاده‌سازی مرجع یا اصلی زبان برنامه‌نویسی روبی با نام مفسر روبی ماتز \fIhttps://en\.wikipedia\.org/wiki/Ruby_MRI\fR یا به اختصار MRI شناخته می‌شود. این نام برگرفته از سازنده روبی یوکیهیرو ماتسوموتو، معروف به Matz است. MRI همچنین با عنوان CRuby شناخته می‌شود، زیرا به زبان C نوشته شده است. MRI پرکاربردترین موتور روبی است.
.IP "\(bu" 4
پیاده‌سازی‌های دیگری \fIhttps://www\.ruby\-lang\.org/en/about\fR از روبی وجود دارند. برخی از پیاده‌سازی‌های شناخته‌شده‌تر شامل JRuby \fIhttps://www\.jruby\.org\fR و TruffleRuby \fIhttps://www\.graalvm\.org/ruby\fR هستند. Rubinius پیاده‌سازی دیگری از روبی است که به خود زبان روبی نوشته شده است. JRuby پیاده‌سازی روبی روی JVM (سرنام Java Virtual Machine) است. TruffleRuby یک پیاده‌سازی روبی روی GraalVM است؛ جعبه‌ابزار زبانی که روی JVM ساخته شده است.
.IP "" 0
.SS "نگارش موتور (ENGINE VERSION)"
هر برنامه \fImay\fR (می‌تواند) نگارش موتور روبی را مشخص کند. اگر نگارش موتور مشخص شود، نام موتور نیز \fImust\fR (باید) تعیین شود. اگر موتور "ruby" باشد، نگارش موتور مشخص‌شده \fImust\fR (باید) با نگارش روبی مطابقت داشته باشد.
.IP "" 4
.nf
ruby "2\.6\.8", engine: "jruby", engine_version: "9\.3\.8\.0"
.fi
.IP "" 0
.SS "سطح پچ (PATCHLEVEL)"
هر برنامه \fImay\fR (می‌تواند) سطح پچ روبی را مشخص کند. تعیین سطح پچ از زمان عرضه Ruby 2\.1\.0 بی‌معنی بوده است زیرا سطح پچ اکنون به طور یکتا با ترکیبی از شماره نگارش‌های اصلی (major)، فرعی (minor) و جزئی (teeny) تعیین می‌شود.
.P
این گزینه در Bundler 1\.4\.0 برای Ruby 2\.0 یا قدیمی‌تر پیاده‌سازی شده بود.
.IP "" 4
.nf
ruby "3\.1\.2", patchlevel: "20"
.fi
.IP "" 0
.SH "جم‌ها (GEMS)"
نیازمندی‌های جم را با استفاده از متد \fBgem\fR و با آرگومان‌های زیر مشخص کنید. تمام پارامترها \fBOPTIONAL\fR (اختیاری) هستند مگر خلاف آن تصریح شده باشد.
.SS "نام (NAME - الزامی)"
برای هر نیازمندی جم، یک سطر منفرد \fIgem\fR بنویسید.
.IP "" 4
.nf
gem "nokogiri"
.fi
.IP "" 0
.SS "نگارش (VERSION)"
هر \fIgem\fR \fBMAY\fR (می‌تواند) یک یا چند مشخص‌کننده نگارش داشته باشد.
.IP "" 4
.nf
gem "nokogiri", ">= 1\.4\.2"
gem "RedCloth", ">= 4\.1\.0", "< 4\.2\.0"
.fi
.IP "" 0
.SS "بارگذاری به عنوان (REQUIRE AS)"
هر \fIgem\fR \fBMAY\fR (می‌تواند) فایل‌هایی را مشخص کند که باید هنگام بارگذاری خودکار از طریق \fBBundler\.require\fR استفاده شوند. می‌توانید آرایه‌ای از چند فایل، یا \fBtrue\fR را بفرستید اگر فایلی که می‌خواهید \fBrequire\fR شود همنام با \fIgem\fR است، یا \fBfalse\fR تا از بارگذاری خودکار هرگونه فایلی جلوگیری شود.
.IP "" 4
.nf
gem "redis", require: ["redis/connection/hiredis", "redis"]
gem "webmock", require: false
gem "byebug", require: true
.fi
.IP "" 0
.P
مقدار پیش‌فرض این آرگومان نام جم است. برای نمونه، این سطرها یکسان هستند:
.IP "" 4
.nf
gem "nokogiri"
gem "nokogiri", require: "nokogiri"
gem "nokogiri", require: true
.fi
.IP "" 0
.SS "گروه‌ها (GROUPS)"
هر \fIgem\fR \fBMAY\fR (می‌تواند) عضویت در یک یا چند گروه را مشخص کند. هر \fIgem\fR که عضویتی در هیچ گروهی مشخص نکند در گروه \fBdefault\fR قرار می‌گیرد.
.IP "" 4
.nf
gem "rspec", group: :test
gem "wirble", groups: [:development, :test]
.fi
.IP "" 0
.P
محیط اجرای Bundler به دو متد اصلی خود، یعنی \fBBundler\.setup\fR و \fBBundler\.require\fR اجازه می‌دهد تأثیر خود را به گروه‌های خاصی محدود کنند.
.IP "" 4
.nf
# متد setup جم‌ها را به load path روبی اضافه می‌کند
Bundler\.setup                    # پیش‌فرض برای همه گروه‌ها
require "bundler/setup"          # همانند Bundler\.setup
Bundler\.setup(:default)          # فقط برپاسازی گروه پیش‌فرض (_default_)
Bundler\.setup(:test)             # فقط برپاسازی گروه آزمون (_test_) (و نه _default_)
Bundler\.setup(:default, :test)   # برپاسازی گروه‌های _default_ و _test_، بدون موارد دیگر

# متد require تمام جم‌های گروه‌های مشخص‌شده را لود می‌کند
Bundler\.require                  # پیش‌فرض روی گروه _default_
Bundler\.require(:default)        # یکسان با قبلی
Bundler\.require(:default, :test) # فراخوانی گروه‌های _default_ و _test_
Bundler\.require(:test)           # فراخوانی گروه _test_
.fi
.IP "" 0
.P
رابط خط فرمان Bundler به شما اجازه می‌دهد فهرستی از گروه‌هایی که \fBbundle install\fR نباید نصب کند را با پیکربندی \fBwithout\fR مشخص کنید.
.P
برای تعیین چند گروه جهت نادیده گرفتن، فهرستی از گروه‌ها را با فاصله جدا کنید.
.IP "" 4
.nf
bundle config set \-\-local without test
bundle config set \-\-local without development test
.fi
.IP "" 0
.P
همچنین فراخوانی \fBBundler\.setup\fR بدون پارامتر، یا فراخوانی \fBrequire "bundler/setup"\fR تمام گروه‌ها را به جز آن‌هایی که از طریق \fB\-\-without\fR مستثنی کرده‌اید برپا می‌سازد (زیرا در دسترس نیستند).
.P
توجه داشته باشید که هنگام اجرای \fBbundle install\fR، باندلر تمام جم‌ها را دانلود و ارزیابی می‌کند تا یک فهرست واحد و استاندارد از همه جم‌های مورد نیاز و وابستگی‌های آن‌ها ایجاد کند. این بدان معناست که شما نمی‌توانید نگارش‌های متفاوتی از همان جم‌ها را در گروه‌های مختلف فهرست کنید. برای جزئیات بیشتر، درک Bundler را در \fIhttps://bundler\.io/rationale\.html\fR ببینید.
.SS "سکscoreها (PLATFORMS)"
اگر یک جم باید تنها در سکویی خاص یا مجموعه‌ای از سکوها استفاده شود، می‌توانید آن‌ها را مشخص کنید. سکوها اساساً مشابه گروه‌ها هستند، با این تفاوت که نیازی به استفاده از پرچم زمان نصب \fB\-\-without\fR برای استثنا کردن گروه‌های جم برای سایر سکوها ندارید.
.P
تعدادی سکو در \fBGemfile\fR وجود دارد:
.TP
\fBruby\fR
محیط C Ruby (MRI)، Rubinius، یا TruffleRuby، اما بدون Windows
.TP
\fBmri\fR
فقط C Ruby (MRI)، اما بدون Windows
.TP
\fBwindows\fR
محیط Windows C Ruby (MRI)، شامل نگارش‌های ۳۲ بیتی و ۶۴ بیتی RubyInstaller
.TP
\fBmswin\fR
محیط Windows C Ruby (MRI)، شامل نگارش‌های ۳۲ بیتی RubyInstaller
.TP
\fBmswin64\fR
محیط Windows C Ruby (MRI)، شامل نگارش‌های ۶۴ بیتی RubyInstaller
.TP
\fBrbx\fR
محیط Rubinius
.TP
\fBjruby\fR
محیط JRuby
.TP
\fBtruffleruby\fR
محیط TruffleRuby
.P
در سکوهای \fBruby\fR، \fBmri\fR، \fBmswin\fR، \fBmswin64\fR و \fBwindows\fR، علاوه بر این می‌توانید یک نگارش را با الحاق شماره‌های اصلی و فرعی نگارش بدون جداکننده مشخص کنید. برای نمونه، برای تعیین اینکه یک جم فقط باید در سکوی \fBruby\fR نگارش 3\.1 استفاده شود، از این الگو استفاده کنید:
.IP "" 4
.nf
ruby_31
.fi
.IP "" 0
.P
همانند گروه‌ها (در بالا)، می‌توانید یک یا چند سکو را مشخص کنید:
.IP "" 4
.nf
gem "weakling",   platforms: :jruby
gem "ruby\-debug", platforms: :mri_31
gem "nokogiri",   platforms: [:windows_31, :jruby]
.fi
.IP "" 0
.P
تمام عملیات مرتبط با گروه‌ها (\fBbundle install\fR \fIbundle\-install\.1\.html\fR، \fBBundler\.setup\fR، \fBBundler\.require\fR) دقیقاً همان‌گونه رفتار می‌کنند که گویی گروه‌هایی که با سکوی فعلی مطابقت ندارند صریحاً مستثنی شده‌اند.
.P
مقادیر سکوی زیر منسوخ شده‌اند و باید با \fBwindows\fR جایگزین شوند:
.IP "\(bu" 4
\fBmswin\fR، \fBmswin64\fR، \fBmingw32\fR، \fBx64_mingw\fR
.IP "" 0
.P
توجه داشته باشید اگرچه متأسفانه از همان اصطلاحات استفاده می‌شود، اما مقادیر این گزینه با مقادیری که \fBbundle lock \-\-add\-platform\fR می‌پذیرد متفاوت است. مقادیر این گزینه به "پیاده‌سازی روبی" نزدیک‌تر است در حالی که مقادیری که دستور \fBbundle lock \-\-add\-platform\fR درک می‌کند بیشتر به سیستم‌عامل و معماری سیستم‌های مختلفی مربوط است که lockfile شما در آن‌ها استفاده خواهد شد.
.SS "گزینه FORCE_RUBY_PLATFORM"
اگر همیشه می‌خواهید نسخه روبی خالص (pure ruby) یک جم به جای نسخه‌های وابسته به سکو انتخاب شود، می‌توانید از گزینه \fBforce_ruby_platform\fR استفاده کنید:
.IP "" 4
.nf
gem "ffi", force_ruby_platform: true
.fi
.IP "" 0
.P
این مورد می‌تواند در شرایط زیر کارآمد باشد (با این فرض که نسخه روبی خالص به خوبی کار می‌کند):
.IP "\(bu" 4
هنگامی که با نسخه وابسته به سکوی خاص به مشکل برخورده‌اید.
.IP "\(bu" 4
نسخه وابسته به سکو هنوز از روبی جدیدتر پشتیبانی نمی‌کند (و بنابراین دارای حد بالای \fBrequired_ruby_version\fR است)، اما همچنان می‌خواهید فایل‌های Gemfile{\.lock} شما تحت آن روبی حل وابستگی شوند.
.IP "" 0
.SS "منبع (SOURCE)"
می‌توانید با استفاده از گزینه ':source' یک مخزن RubyGems جایگزین را برای یک جم انتخاب کنید.
.IP "" 4
.nf
gem "some_internal_gem", source: "https://gems\.example\.com"
.fi
.IP "" 0
.P
این کار بارگذاری جم را از این منبع اجباری می‌کند و منبع سراسری تعریف‌شده در سطح بالای فایل را نادیده می‌گیرد. اگر جم در این منبع وجود نداشته باشد، نصب نخواهد شد.
.P
باندلر ابتدا با جستجو در منبع انتخاب‌شده برای جم والد، وابستگی‌های فرزند این جم را جستجو می‌کند، اما اگر آن‌ها در آنجا یافت نشوند، به منبع سراسری بازمی‌گردد.
.P
\fBنکته درباره رفتار ویژگی منسوخ‌شده در Bundler 1\.13\fR: انتخاب یک مخزن منبع مشخص به این شیوه، همچنین هشدار جم چندگانه تشریح‌شده در \fIمخزن سراسری (GLOBAL SOURCE)\fR را بی‌اثر می‌کند.
.P
استفاده از گزینه \fB:source\fR برای یک جم منفرد، همچنین آن منبع را به عنوان یک منبع سراسری بالقوه برای سایر جم‌هایی که منابع صریح را مشخص نکرده‌اند در دسترس قرار می‌دهد. بنابراین، هنگام افزودن جم‌ها با منابع صریح، توصیه می‌شود مطمئن شوید که سایر جم‌ها در Gemfile نیز از منابع صریح استفاده می‌کنند.
.SS "گیت (GIT)"
در صورت نیاز، می‌توانید مشخص کنید که یک جم در مخزن گیت خاصی با استفاده از پارامتر \fB:git\fR قرار دارد. دسترسی به مخزن از طریق چندین پروتکل امکان‌پذیر است:
.TP
\fBHTTP(S)\fR
gem "rails", git: "https://github\.com/rails/rails\.git"
.TP
\fBSSH\fR
gem "rails", git: "git@github\.com:rails/rails\.git"
.TP
\fBgit\fR
gem "rails", git: "git://github\.com/rails/rails\.git"
.P
در صورت استفاده از SSH، کاربری که از آن برای اجرای \fBbundle install\fR استفاده می‌کنید \fBMUST\fR (باید) کلیدهای مناسب را در \fB$HOME/\.ssh\fR خود داشته باشد.
.P
\fBیادداشت\fR: در صورت امکان باید از نشانی‌های اینترنتی \fBhttp://\fR و \fBgit://\fR اجتناب کرد. این پروتکل‌ها احراز هویت نشده هستند، بنابراین یک مهاجم میانی (man\-in\-the\-middle) می‌تواند کد مخرب تزریق کرده و سیستم شما را به خطر بیندازد. پروتکل‌های HTTPS و SSH به شدت ارجح هستند.
.P
گزینه‌های \fBgroup\fR، \fBplatforms\fR، و \fBrequire\fR در دسترس هستند و دقیقاً مشابه یک جم معمولی عمل می‌کنند.
.P
یک مخزن گیت \fBSHOULD\fR (باید ترجیحاً) حداقل یک فایل در ریشه دایرکتوری حاوی جم با پسوند \fB\.gemspec\fR داشته باشد. این فایل \fBMUST\fR (باید) حاوی یک مشخصات جم معتبر باشد، همان‌طور که دستور \fBgem build\fR انتظار دارد.
.P
اگر یک مخزن گیت فایل \fB\.gemspec\fR نداشته باشد، باندلر تلاش می‌کند تا یکی بسازد، اما این فایل فاقد هرگونه وابستگی، فایل اجرایی یا دستورالعمل‌های کامپایل افزونه C خواهد بود. در نتیجه، ممکن است نتواند به درستی با برنامه شما یکپارچه شود.
.P
اگر یک مخزن گیت دارای یک \fB\.gemspec\fR برای جمی باشد که به آن متصل کرده‌اید، تعیین نگارش (در صورت ارائه) بدین معناست که مخزن گیت تنها زمانی معتبر است که \fB\.gemspec\fR نگارشی مطابق با مشخص‌کننده نگارش تعیین کند. در غیر این صورت، باندلر هشداری چاپ می‌کند.
.IP "" 4
.nf
gem "rails", "2\.3\.8", git: "https://github\.com/rails/rails\.git"
# دستور bundle install با شکست مواجه می‌شود، زیرا .gemspec در
# شاخه master مخزن rails نگارش 3.0.0 را مشخص می‌کند
.fi
.IP "" 0
.P
اگر مخزن گیت فایل \fB\.gemspec\fR برای جمی که به آن متصل کرده‌اید \fBنداشته باشد\fR، \fBMUST\fR (باید) یک مشخص‌کننده نگارش ارائه شود. باندلر از این نگارش در فایل ساده \fB\.gemspec\fR که ایجاد می‌کند استفاده خواهد کرد.
.P
مخازن گیت از تعدادی گزینه اضافی پشتیبانی می‌کنند.
.TP
\fBbranch\fR، \fBtag\fR، و \fBref\fR
شما \fBMUST\fR (باید) حداکثر یکی از این گزینه‌ها را مشخص کنید. مقدار پیش‌فرض \fBbranch: "master"\fR است. برای نمونه:
.IP
gem "rails", git: "https://github\.com/rails/rails\.git", branch: "5\-0\-stable"
.IP
gem "rails", git: "https://github\.com/rails/rails\.git", tag: "v5\.0\.0"
.IP
gem "rails", git: "https://github\.com/rails/rails\.git", ref: "4aded"
.TP
\fBsubmodules\fR
برای مرجع، زیرماژول گیت \fIhttps://git\-scm\.com/book/en/v2/Git\-Tools\-Submodules\fR به شما اجازه می‌دهد مخزن گیت دیگری در زیرپوشه‌ای از مخزن خود داشته باشید. تعیین \fBsubmodules: true\fR باعث می‌شود باندلر هر زیرماژول موجود در مخزن گیت را باز کند.
.P
اگر یک مخزن گیت حاوی چندین فایل \fB\.gemspec\fR باشد، هر \fB\.gemspec\fR نشان‌دهنده جمی است که در همان مکان در سیستم فایل قرار دارد که \fB\.gemspec\fR قرار گرفته است.
.IP "" 4
.nf
|~rails                   [ریشه گیت]
| |\-rails\.gemspec         [جم rails اینجا قرار دارد]
|~actionpack
| |\-actionpack\.gemspec    [جم actionpack اینجا قرار دارد]
|~activesupport
| |\-activesupport\.gemspec [جم activesupport اینجا قرار دارد]
|\|\.\|\.\|\.
.fi
.IP "" 0
.P
برای نصب جمی که در مخزن گیت قرار دارد، باندلر به دایرکتوری حاوی gemspec می‌رود، دستور \fBgem build name\.gemspec\fR را اجرا می‌کند و سپس جم حاصل را نصب می‌نماید. دستور \fBgem build\fR که به صورت استاندارد همراه با Rubygems ارائه می‌شود، فایل \fB\.gemspec\fR را در چارچوب دایرکتوری که در آن قرار دارد ارزیابی می‌کند.
.SS "منبع گیت (GIT SOURCE)"
یک منبع سفارشی گیت را می‌توان از طریق متد \fBgit_source\fR تعریف کرد. نام منبع را به عنوان آرگومان، و بلوکی که یک آرگومان دریافت می‌کند و آن را در یک رشته برای بازگرداندن آدرس کامل مخزن درون‌یابی می‌کند، ارائه دهید:
.IP "" 4
.nf
git_source(:stash){ |repo_name| "https://stash\.corp\.acme\.pl/#{repo_name}\.git" }
gem 'rails', stash: 'forks/rails'
.fi
.IP "" 0
.P
علاوه بر این، اگر مایل به انتخاب شاخه خاصی هستید:
.IP "" 4
.nf
gem "rails", stash: "forks/rails", branch: "branch_name"
.fi
.IP "" 0
.SS "گیت‌هاب (GITHUB)"
\fBیادداشت\fR: تا قبل از Bundler 2\.0 باید از این شکل مختصر اجتناب شود، زیرا در حال حاضر به یک نشانی ناامن \fBgit://\fR گسترش می‌یابد. این امر به مهاجم میانی اجازه می‌دهد سیستم شما را به خطر بیندازد.
.P
اگر مخزن گیت مورد نظر شما روی GitHub میزبانی شده و عمومی است، می‌توانید از مختصرنویسی :github برای تعیین نام کاربری گیت‌هاب و نام مخزن (بدون پسوند "\.git")، که با اسلش از هم جدا شده‌اند، استفاده کنید. اگر هر دو نام کاربری و نام مخزن یکسان باشند، می‌توانید یکی را حذف کنید.
.IP "" 4
.nf
gem "rails", github: "rails/rails"
gem "rails", github: "rails"
.fi
.IP "" 0
.P
هر دو معادل هستند با
.IP "" 4
.nf
gem "rails", git: "https://github\.com/rails/rails\.git"
.fi
.IP "" 0
.P
از آنجا که متد \fBgithub\fR نوعی تخصیص از \fBgit_source\fR است، آرگومان نام‌دار \fB:branch\fR را می‌پذیرد.
.P
همچنین می‌توانید مستقیماً نشانی یک Pull Request را ارسال کنید:
.IP "" 4
.nf
gem "rails", github: "https://github\.com/rails/rails/pull/43753"
.fi
.IP "" 0
.P
که معادل است با:
.IP "" 4
.nf
gem "rails", github: "rails/rails", branch: "refs/pull/43753/head"
.fi
.IP "" 0
.SS "گیست (GIST)"
اگر مخزن گیت مد نظر به صورت GitHub Gist میزبانی شده و عمومی است، می‌توانید از مختصرنویسی :gist برای تعیین شناسه gist (بدون پسوند "\.git") استفاده کنید.
.IP "" 4
.nf
gem "the_hatch", gist: "4815162342"
.fi
.IP "" 0
.P
معادل است با:
.IP "" 4
.nf
gem "the_hatch", git: "https://gist\.github\.com/4815162342\.git"
.fi
.IP "" 0
.P
از آنجا که متد \fBgist\fR نوعی تخصیص از \fBgit_source\fR است، آرگومان نام‌دار \fB:branch\fR را می‌پذیرد.
.SS "بیت‌باکت (BITBUCKET)"
اگر مخزن گیت مد نظر روی Bitbucket میزبانی شده و عمومی است، می‌توانید از مختصرنویسی :bitbucket برای تعیین نام کاربری بیت‌باکت و نام مخزن (بدون پسوند "\.git") که با اسلش از هم جدا شده‌اند استفاده کنید. اگر هم نام کاربری و هم نام مخزن یکسان باشند، می‌توانید یکی را حذف کنید.
.IP "" 4
.nf
gem "rails", bitbucket: "rails/rails"
gem "rails", bitbucket: "rails"
.fi
.IP "" 0
.P
هر دو معادل هستند با
.IP "" 4
.nf
gem "rails", git: "https://rails@bitbucket\.org/rails/rails\.git"
.fi
.IP "" 0
.P
از آنجا که متد \fBbitbucket\fR نوعی تخصیص از \fBgit_source\fR است، آرگومان نام‌دار \fB:branch\fR را می‌پذیرد.
.SS "مسیر (PATH)"
می‌توانید مشخص کنید که یک جم در مکان خاصی روی سیستم فایل قرار دارد. مسیرهای نسبی نسبت به دایرکتوری حاوی \fBGemfile\fR حل می‌شوند.
.P
همانند ساختار گزینه \fB:git\fR، گزینه \fB:path\fR نیز مستلزم آن است که دایرکتوری مورد نظر یا حاوی یک \fB\.gemspec\fR برای جم باشد، یا اینکه نگارش صریحی را که باندلر باید استفاده کند مشخص نمایید.
.P
برخلاف \fB:git\fR، باندلر افزونه‌های C را برای جم‌هایی که به عنوان مسیر مشخص شده‌اند کامپایل نمی‌کند.
.IP "" 4
.nf
gem "rails", path: "vendor/rails"
.fi
.IP "" 0
.P
اگر می‌خواهید چندین جم محلی را مستقیماً از سیستم فایل استفاده کنید، می‌توانید یک گزینه سراسری \fBpath\fR را به مسیری که حاوی فایل‌های جم است تنظیم کنید. این کار فایل‌های gemspec را به طور خودکار از زیردایرکتوری‌ها بارگذاری می‌کند.
.IP "" 4
.nf
path 'components' do
  gem 'admin_ui'
  gem 'public_ui'
end
.fi
.IP "" 0
.SH "فرم بلوکی SOURCE، GIT، PATH، GROUP و PLATFORMS"
گزینه‌های \fB:source\fR، \fB:git\fR، \fB:path\fR، \fB:group\fR و \fB:platforms\fR ممکن است با استفاده از فرم بلوکی برای گروهی از جم‌ها اعمال شوند.
.IP "" 4
.nf
source "https://gems\.example\.com" do
  gem "some_internal_gem"
  gem "another_internal_gem"
end

git "https://github\.com/rails/rails\.git" do
  gem "activesupport"
  gem "actionpack"
end

platforms :ruby do
  gem "ruby\-debug"
  gem "sqlite3"
end

group :development, optional: true do
  gem "wirble"
  gem "faker"
end
.fi
.IP "" 0
.P
در مورد فرم بلوکی گروه، گزینه :optional را می‌توان تعیین کرد تا از نصب یک گروه جلوگیری شود مگر اینکه در گزینه \fB\-\-with\fR ارائه‌شده به دستور \fBbundle install\fR ذکر شده باشد.
.P
در مورد فرم بلوکی \fBgit\fR، گزینه‌های \fB:ref\fR، \fB:branch\fR، \fB:tag\fR و \fB:submodules\fR را می‌توان به متد \fBgit\fR ارسال کرد و تمام جم‌های موجود در بلوک آن گزینه‌ها را به ارث خواهند برد.
.P
وجود یک بلوک \fBsource\fR در یک Gemfile همچنین آن منبع را به عنوان یک منبع سراسری بالقوه برای سایر جم‌هایی که منابع صریح را مشخص نکرده‌اند در دسترس قرار می‌دهد. بنابراین، هنگام تعریف بلوک‌های منبع، توصیه می‌شود مطمئن شوید که سایر جم‌ها در Gemfile نیز از منابع صریح استفاده می‌کنند؛ چه از طریق بلوک‌های منبع یا دستورات \fB:source\fR روی تک‌تک جم‌ها.
.SH "دستور INSTALL_IF"
متد \fBinstall_if\fR اجازه می‌دهد تا جم‌ها بر اساس یک proc یا lambda نصب شوند. این ویژگی به ویژه برای جم‌های اختیاری که فقط در صورت نصب بودن نرم‌افزارهای خاص یا برآورده شدن برخی شرایط دیگر می‌توانند استفاده شوند، بسیار مفید است.
.IP "" 4
.nf
install_if \-> { RUBY_PLATFORM =~ /darwin/ } do
  gem "pasteboard"
end
.fi
.IP "" 0
.SH "فایل مشخصات جم (GEMSPEC)"
فایل \fB\.gemspec\fR \fIhttps://guides\.rubygems\.org/specification\-reference\fR جایی است که متادیتای جم خود را به Rubygems ارائه می‌دهید. برخی از ویژگی‌های ضروری Gemspec شامل نام، توضیحات، و صفحه خانگی جم شما هستند. این همچنین مکانی است که در آن وابستگی‌های مورد نیاز جم خود را برای اجرا مشخص می‌کنید.
.P
اگر می‌خواهید از Bundler برای کمک به نصب وابستگی‌های یک جم در حین توسعه استفاده کنید، از متد \fBgemspec\fR برای فراخوانی وابستگی‌های فهرست‌شده در فایل \fB\.gemspec\fR استفاده نمایید.
.P
متد \fBgemspec\fR هرگونه وابستگی زمان اجرا را به عنوان نیازمندی‌های جم در گروه پیش‌فرض (default) اضافه می‌کند. همچنین وابستگی‌های زمان توسعه را به عنوان نیازمندی‌های جم در گروه \fBdevelopment\fR می‌افزاید. سرانجام، یک نیازمندی جم روی پروژه شما (\fBpath: '\.'\fR) اضافه می‌کند. در پیوند با \fBBundler\.setup\fR، این به شما امکان می‌دهد فایل‌های پروژه را در کد آزمون خود به همان روشی فراخوانی (require) کنید که اگر پروژه به عنوان یک جم نصب شده بود عمل می‌کردید؛ نیازی به دستکاری دستی مسیر بارگذاری (load path) یا فراخوانی فایل‌های پروژه از طریق مسیرهای نسبی ندارید.
.P
متد \fBgemspec\fR از گزینه‌های اختیاری \fB:path\fR، \fB:glob\fR، \fB:name\fR و \fB:development_group\fR پشتیبانی می‌کند که کنترل می‌کنند باندلر کجا به دنبال \fB\.gemspec\fR بگردد، از چه الگویی (glob) برای یافتن gemspec استفاده کند (پیش‌فرض: \fB{,*,*/*}\.gemspec\fR)، از کدام \fB\.gemspec\fR نام‌گذاری‌شده استفاده نماید (اگر بیش از یکی وجود داشته باشد)، و وابستگی‌های توسعه در کدام گروه گنجانده شوند.
.P
هنگامی که یک وابستگی \fBgemspec\fR در هنگام حل وابستگی‌ها با تداخل نگارش مواجه می‌شود، نگارش محلی در حال توسعه همیشه انتخاب خواهد شد \-\- حتی اگر نگارش‌های راه دور وجود داشته باشند که با سایر نیازمندی‌های جم \fBgemspec\fR تطابق بهتری داشته باشند.
.SH "اولویت منبع (SOURCE PRIORITY)"
هنگام تلاش برای یافتن یک جم جهت برآورده کردن نیازمندی جم، باندلر از ترتیب اولویت زیر استفاده می‌کند:
.IP "1." 4
منبعی که صریحاً به جم متصل شده است (با استفاده از \fB:source\fR، \fB:path\fR، یا \fB:git\fR)
.IP "2." 4
برای جم‌های ضمنی (وابستگی‌های جم‌های صریح)، هر مخزن منبع، git، یا path که روی والد تعریف شده باشد. این باعث می‌شود باندلر جم ActiveSupport از مخزن گیت Rails را نسبت به موارد موجود در \fBrubygems\.org\fR در اولویت قرار دهد
.IP "3." 4
اگر هیچ‌یک از شرایط فوق برآورده نشود، از منبع سراسری استفاده خواهد شد. اگر چندین منبع سراسری مشخص شده باشند، اولویت‌بندی آن‌ها از آخر به اول خواهد بود، اما این کار از زمان Bundler 1\.13 منسوخ شده است، بنابراین Bundler هشداری چاپ می‌کند و در آینده با خطا متوقف خواهد شد.
.IP "" 0
.SH "فایل قفل (LOCKFILE)"
به طور پیش‌فرض، Bundler با افزودن \fB\.lock\fR به انتهای نام Gemfile یک فایل قفل (lockfile) ایجاد می‌کند. برای تغییر این مورد، از متد \fBlockfile\fR استفاده کنید:
.IP "" 4
.nf
lockfile "/path/to/lockfile\.lock"
.fi
.IP "" 0
.P
این زمانی مفید است که می‌خواهید برای هر نگارش روبی یا سکو از فایل‌های قفل متفاوتی استفاده کنید.
.P
برای جلوگیری از نوشتن فایل قفل، از مقدار \fBfalse\fR به عنوان آرگومان استفاده کنید:
.IP "" 4
.nf
lockfile false
.fi
.IP "" 0
.P
این برای توسعه کتابخانه و سایر شرایطی که انتظار می‌رود کد با طیف وسیعی از نگارش‌های وابستگی کار کند، مفید است.
.SS "اولویت فایل قفل (LOCKFILE PRECEDENCE)"
هنگام تعیین مسیر فایل قفل یا تصمیم‌گیری درباره ایجاد فایل قفل، اولویت‌های زیر اعمال می‌شود:
.IP "1." 4
گزینه \fB\-\-no\-lock\fR در \fBbundle install\fR (که ایجاد lockfile را غیرفعال می‌کند).
.IP "2." 4
گزینه \fB\-\-lockfile\fR در \fBbundle install\fR.
.IP "3." 4
متغیر محیطی \fBBUNDLE_LOCKFILE\fR.
.IP "4." 4
متد \fBlockfile\fR در Gemfile.
.IP "5." 4
رفتار پیش‌فرض اضافه کردن \fB\.lock\fR به انتهای نام Gemfile.
.IP "" 0