1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
<!DOCTYPE html>
<html>
<head>
<title>Bundler: The best way to manage a Ruby application's gems</title>
<meta content='text/html; charset=UTF-8' http-equiv='Content-Type'>
<meta content='276VSYOko8B8vIu1i8i5qbj7_ql5PXo0dU69XQy-SL' name='globalsign-domain-verification'>
<link href='/images/favicon.png' rel='shortcut icon' type='image/png'>
<link href="/stylesheets/application.css" media="screen" rel="stylesheet" type="text/css" />
</head>
<body>
<div id='body'>
<div id='header'>
<a class="image" href="/"><img width="725" alt="The best way to manage your application's dependencies" src="/images/gembundler.png" /></a>
</div>
<div id='container'>
<div id='contents'>
<div id='intro'>
Bundler manages an <strong>application's dependencies</strong> through its
entire life across many machines systematically and repeatably.
</div>
<h2>I am interested in</h2>
<div class='contents'>
<ul class='bullet'>
<a href="https://github.com/bundler/bundler/blob/1-0-stable/ISSUES.md">Troubleshooting</a>
<a href="/v1.0/rationale.html">Understanding Bundler</a>
<a href="./man/gemfile.5.html">Gemfile Manual</a>
<a href="./man/bundle.1.html">CLI Manual</a>
</ul>
</div>
<h2 id='getting-started'>
Getting Started
</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Getting started with bundler is easy
</div>
<pre class="highlight plaintext">$ gem install bundler
</pre>
</div>
<div class='bullet'>
<div class='description'>
Specify your dependencies in a Gemfile in your project's root
</div>
<pre class="highlight ruby"><span class="n">source</span> <span class="s2">"http://rubygems.org"</span>
<span class="n">gem</span> <span class="s2">"nokogiri"</span>
<span class="n">gem</span> <span class="s2">"rack"</span><span class="p">,</span> <span class="s2">"~>1.1"</span>
<span class="n">gem</span> <span class="s2">"rspec"</span><span class="p">,</span> <span class="ss">:require</span> <span class="o">=></span> <span class="s2">"spec"</span></pre>
<a href="/v1.0/gemfile.html">Learn More: Gemfiles</a>
</div>
<div class='bullet'>
<div class='description'>
Install all of the required gems from your specified sources
</div>
<pre class="highlight plaintext">$ bundle install
$ git add Gemfile Gemfile.lock</pre>
<a href="/v1.0/bundle_install.html">Learn More: bundle install</a>
<div class='notes'>
Make sure to add Gemfile.lock to your repository. This will
ensure that other developers on your app, as well as your
deployment environment, use exactly the same third-party code
as you just installed.
</div>
</div>
<div class='bullet'>
<div class='description'>
Inside your app, load up the bundled environment
</div>
<pre class="highlight ruby"><span class="nb">require</span> <span class="s2">"rubygems"</span>
<span class="nb">require</span> <span class="s2">"bundler/setup"</span>

<span class="c1"># require your gems as usual</span>
<span class="nb">require</span> <span class="s2">"nokogiri"</span></pre>
<a href="/v1.0/bundler_setup.html">Learn More: Bundler.setup</a>
</div>
<div class='bullet'>
<div class='description'>
Run an executable that comes with a gem in your bundle
</div>
<pre class="highlight plaintext">$ bundle exec rspec spec/models</pre>
<div class='notes'>
<p>
In some cases, running executables without <code>bundle exec</code>
may work, if the executable happens to be installed in your system
and does not pull in any gems that conflict with your bundle.
</p>
<p>
However, this is unreliable and is the source of considerable pain.
Even if it looks like it works, it may not work in the future or
on another machine.
</p>
</div>
<div class='description'>
If you want a way to get a shortcut to gems in your bundle
</div>
<pre class="highlight plaintext">$ bundle install --binstubs
$ bin/rspec spec/models</pre>
<div class='notes'>
The executables installed into <code>bin</code> are scoped to the
bundle and will always work
</div>
<a href="./man/bundle-exec.1.html">Learn More: Executables</a>
</div>
</div>
<h2 id='using-bundler-with-rails'>
Using Bundler with Rails
</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Bundler works out of the box with Rails 3. Once you
understand the basics of using bundler, you know
everything you need to know.
<a href="/v1.0/rails3.html">Using Bundler with Rails 3</a>
</div>
</div>
<div class='bullet'>
<div class='description'>
Bundler works with Rails 2.3 with a small change
to boot.rb and adding a preinitializer.rb.
<a href="/v1.0/rails23.html">Using Bundler with Rails 2.3</a>
</div>
</div>
</div>
<h2 id='checking-out-application-with-a-gemfile-for-development'>
Checking Out an Application With a Gemfile for Development
</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Install the required gems
</div>
<pre class="highlight plaintext">$ bundle install</pre>
<a href="/v1.0/bundle_install.html">Learn More: bundle install</a>
<div class='notes'>
If your system stores its gems in a root-owned location (this
is the default for Mac OSX), bundler will ask you for your
password, so it can install the gems there.
</div>
</div>
</div>
<h2 id='updating-your-dependencies'>
Updating Your Dependencies
</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Make a change to your Gemfile
</div>
<pre class="highlight ruby"><span class="c1"># change</span>
<span class="n">gem</span> <span class="s2">"nokogiri"</span><span class="p">,</span> <span class="s2">"1.4.2"</span>
<span class="c1"># to</span>
<span class="n">gem</span> <span class="s2">"nokogiri"</span><span class="p">,</span> <span class="s2">"1.4.3"</span></pre>
</div>
<div class='bullet'>
<div class='description'>
Install the new gems
</div>
<pre class="highlight plaintext">$ bundle install</pre>
<div class='notes'>
<p>
After making a change to your <code>Gemfile</code>, the next
<code>bundle install</code> will try to update the gems in
your snapshot (<code>Gemfile.lock</code>) without forcing an
update to any of the other gems in your Gemfile.
</p>
<p>
This will usually work for simple dependencies, like
<code>nokogiri</code> or <code>sqlite3</code>. On the
other hand, updating Rails will usually require an update
to some other component, because of the amount of dependencies
it has.
</p>
</div>
</div>
<div class='bullet'>
<div class='description'>
If bundler reports a conflict, tell bundler to explicitly update
the gem, but none of the other top-level dependencies (the ones
in your <code>Gemfile</code>)
</div>
<pre class="highlight plaintext">$ bundle update rails</pre>
<a href="./man/bundle-update.1.html">Learn More: bundle update</a>
</div>
<div class='bullet'>
<div class='description'>
In some rare cases, bundler will be unable to update the dependency
without updating the top-level dependencies as well. In this case,
tell bundler to update <strong>all</strong> dependencies
</div>
<pre class="highlight plaintext">$ bundle update
</pre>
</div>
</div>
<h2 id='deploying-your-application'>
Deploying Your Application
</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
On production servers, you can enable deployment mode:
</div>
<pre class="highlight plaintext">$ bundle install --deployment</pre>
<div class='notes'>
Do <b>not</b> use this flag on development machines. The
<code>--deployment</code> flag turns on defaults that are appropriate for
a deployment environment. Gems are installed to
<code>vendor/bundle</code> and the <code>Gemfile.lock</code> must be
checked in and up to date before Bundler is run.
</div>
<a href="/v1.0/deploying.html">Learn More: deploying</a>
</div>
</div>
<h2 id='digging-further'>
Digging Further
</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Store all of the required gems in your application. All future installs will get gems
from this cache, bypassing rubygems.org
</div>
<pre class="highlight plaintext">$ bundle package</pre>
<a href="/v1.0/bundle_package.html">Learn More: bundle package</a>
</div>
<div class='bullet'>
<div class='description'>
Put dependencies in a group, so they can be ignored at install time or required
together in your application
</div>
<pre class="highlight ruby"><span class="n">group</span> <span class="ss">:development</span> <span class="k">do</span>
 <span class="n">gem</span> <span class="s2">"wirble"</span>
<span class="k">end</span></pre>
<a href="/v1.0/groups.html">Learn more: Groups</a>
</div>
<div class='bullet'>
<div class='description'>
Use a gem that is stored in git and has a <code>.gemspec</code> at its root.
Bundler will make the executables available to <code>bundle exec</code> and
compile C extensions
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s2">"nokogiri"</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span>
 <span class="s2">"https://github.com/tenderlove/nokogiri.git"</span></pre>
<a href="/v1.0/git.html">Learn more: Git</a>
</div>
<div class='bullet'>
<div class='description'>
Use a gem that you are actively developing on your file system
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s2">"nokogiri"</span><span class="p">,</span> <span class="ss">:path</span> <span class="o">=></span> <span class="s2">"~/Code/nokogiri"</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
Install gems to an alternate location. By default, bundler installs your
gems to the system location
</div>
<pre class="highlight plaintext">$ bundle install --path vendor</pre>
<div class='notes'>
When installing to a path, bundler completely isolates your gems
from the system, guaranteeing you a clear set of dependencies.
</div>
<a href="/v1.0/bundle_install.html">Learn More: bundle install</a>
</div>
</div>
</div>
</div>
</div>
<div id='footer'>
<img src="/images/emocow.png" />
<img src="/images/panda.jpg" />
<div class='spacer'></div>
<div id='credits'>
<p>
Many thanks to Bundler's <a href="/contributors.html">contributors</a>
and <a href="/sponsors.html">sponsors</a>
</p>
</div>
<div class='spacer'></div>
<img src="/images/bundler-small.png" />
</div>
<a href='http://github.com/bundler/bundler/' id='github'>
<img alt='Fork me on GitHub' src='http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png'>
</a>
<div id='prod-versions'>
Docs:
<a href="/v0.9/">v0.9</a>
<a class="current" href="/v1.0/">v1.0</a>
<a href="/v1.1/">v1.1</a>
<a href="/v1.2/">v1.2</a>
<a href="/v1.3/">v1.3</a>
<a href="/v1.5/index.html">v1.5</a>
<a href="/">v1.6</a>
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-39559982-1', 'bundler.io');
ga('send', 'pageview');
</script>
</body>
</html>
|
