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
|
<!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'>
<h2>Recommended Workflow with Version Control</h2>
<div class='contents'>
<div class='bullet' id='recommended_workflow'>
<div class='description'>
<p>
In general, when working with an application managed with bundler, you
should use the following workflow:
</p>
<p>
After you create your <code>Gemfile</code> for the first time, run
<pre class="highlight plaintext">$ bundle install</pre>
</p>
<p>
Check the resulting <code>Gemfile.lock</code> into version control
<pre class="highlight plaintext">$ git add Gemfile.lock</pre>
</p>
<p>
When checking out this repository on another development machine, run
<pre class="highlight plaintext">$ bundle install</pre>
</p>
<p>
When checking out this repository on a deployment machine, run
<pre class="highlight plaintext">$ bundle install --deployment</pre>
</p>
<p>
After changing the <code>Gemfile</code> to reflect a new or update
dependency, run
<pre class="highlight plaintext">$ bundle install</pre>
</p>
<p>
Make sure to check the updated <code>Gemfile.lock</code> into version
control
<pre class="highlight plaintext">$ git add Gemfile.lock</pre>
</p>
<p>
If <code>bundle install</code> reports a conflict, manually update the
specific gems that you changed in the <code>Gemfile</code>
<pre class="highlight plaintext">$ bundle update rails thin</pre>
</p>
<p>
If you want to update all the gems to the latest possible versions that
still match the gems listed in the <code>Gemfile</code>, run
<pre class="highlight plaintext">$ bundle update
</pre>
</p>
</div>
</div>
</div>
<h2>A Thorough Bundler Workflow</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Getting started with bundler is easy! Open a terminal window and run this command:
</div>
<pre class="highlight plaintext">$ gem install bundler</pre>
<div class='notes'>
<li>
When you first create a Rails application, it already comes with a
<code>Gemfile</code>. For another kind of application (such as Sinatra), run:
<pre class="highlight plaintext">$ bundle init
</pre>
</li>
<li>
The <code>bundle init</code> command creates a simple <code>Gemfile</code> which you
can edit.
</li>
</div>
</div>
<div class='bullet'>
<div class='description'>
Specify your dependencies in the root of your application, called the <code>Gemfile</code>.
It looks something like this:
</div>
<pre class="highlight ruby"><span class="n">source</span> <span class="s1">'https://rubygems.org'</span>
<span class="n">gem</span> <span class="s1">'nokogiri'</span>
<span class="n">gem</span> <span class="s1">'rack'</span><span class="p">,</span> <span class="s1">'~>1.1'</span>
<span class="n">gem</span> <span class="s1">'rspec'</span><span class="p">,</span> <span class="ss">:require</span> <span class="o">=></span> <span class="s1">'spec'</span>
</pre>
<div class='notes'>
This <code>Gemfile</code> says a few things. First, it says that bundler should
look for gems declared in the <code>Gemfile</code> at <code>http://rubygems.org</code>.
You can declare multiple Rubygems sources, and bundler will look for gems in the order
you declared the sources.
</div>
<a href="/v1.5/gemfile.html">Learn More: Gemfiles</a>
</div>
<div class='bullet'>
<div class='description'>
<p>
After declaring your first set of dependencies, you tell bundler to go get them:
<pre class="highlight plaintext">$ bundle install # <code>bundle</code> is a shortcut for <code>bundle install</code>
</pre>
</p>
<p>
Bundler will connect to <code>rubygems.org</code> (and any other sources that you declared),
and find a list of all of the required gems that meet the requirements you specified.
Because all of the gems in your <code>Gemfile</code> have dependencies of their own
(and some of those have their own dependencies), running <code>bundle install</code> on the
<code>Gemfile</code> above will install quite a few gems.
<pre class="highlight plaintext"> $ bundle install
 Fetching gem metadata from https://rubygems.org/
 Resolving dependencies...
 Using rake (0.8.7)
 Using abstract (1.0.0)
 Installing activesupport (3.0.0.rc)
 Using builder (2.1.2)
 Using i18n (0.4.1)
 Installing activemodel (3.0.0.rc)
 Using erubis (2.6.6)
 Using rack (1.2.1)
 Installing rack-mount (0.6.9)
 Using rack-test (0.5.4)
 Using tzinfo (0.3.22)
 Installing actionpack (3.0.0.rc)
 Using mime-types (1.16)
 Using polyglot (0.3.1)
 Using treetop (1.4.8)
 Using mail (2.2.5)
 Installing actionmailer (3.0.0.rc)
 Using arel (0.4.0)
 Installing activerecord (3.0.0.rc)
 Installing activeresource (3.0.0.rc)
 Using bundler (1.0.0.rc.3)
 Installing nokogiri (1.4.3.1) with native extensions
 Installing rack-cache (0.5.2)
 Installing thor (0.14.0)
 Installing railties (3.0.0.rc)
 Installing rails (3.0.0.rc)
 Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
</pre>
</p>
<p>
If any of the needed gems are already installed, Bundler will use them. After installing
any needed gems to your system, bundler writes a snapshot of all of the gems and
versions that it installed to <code>Gemfile.lock</code>.
<div class='notes'>
<li>
If <code>bundle install</code> reports a conflict between your <code>Gemfile</code> and
<code>Gemfile.lock</code>, run:
<pre class="highlight plaintext">$ bundle update sinatra
</pre>
</li>
<li>
This will update just the Sinatra gem, as well as any of its dependencies.
</li>
<p>
<li>
To update all of the gems in your <code>Gemfile</code> to the latest possible versions, run:
<pre class="highlight plaintext">$ bundle update
</pre>
</li>
</p>
<li>
Whenever your <code>Gemfile.lock</code> changes, always check it in to version control.
It keeps a history of the exact versions of all third-party code that you used to successfully
run your application.
</li>
<li>
The <code>git add Gemfile*</code> command adds the Gemfile and Gemfile.lock to your repository. This ensures that
other developers on your app, as well as your deployment environment, will all use the same
third-party code that you are using now.
</li>
</div>
</p>
</div>
</div>
<div class='buttons'>
<a href="/v1.5/bundle_install.html">Learn More: bundle install</a>
<a href="/v1.5/bundle_update.html">Learn More: bundle update</a>
</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="s1">'rubygems'</span>
<span class="nb">require</span> <span class="s1">'bundler/setup'</span>

<span class="c1"># require your gems as usual</span>
<span class="nb">require</span> <span class="s1">'nokogiri'</span></pre>
<a href="/v1.5/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>
<div class='bullet'>
<div class='description'>
Finally, 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="/v1.5/man/bundle-exec.1.html">Learn More: Executables</a>
</div>
</div>
</div>
<div id='sidebar'>
<h2>Would you like to</h2>
<ul>
<li><a href="/#getting-started">Get started</a></li>
<li><a href="/issues.html">Report a bug</a></li>
<li><a href="/v1.6/whats_new.html">See what's new</a></li>
<li><a href="/v1.6/man/bundle.1.html">Read documentation</a></li>
<li><a href="/#get-involved">Discuss and Contribute</a></li>
<li><a href="/v1.6/faq.html">View FAQs</a></li>
</ul>
<div class='shirts'>
<div class='content'>
<p>
Bundler is developed entirely by a team of volunteers.
<a href="http://www.gittip.com/bundler">Support their work</a>
and help make Bundler better for everyone.
</p>
<p>
<script data-gittip-username='bundler' src='//gttp.co/v1.js'></script>
<br>
<br>
</p>
</div>
</div>
<h2>Bundler Commands</h2>
<ul>
<li><a href="/v1.6/bundle_install.html">bundle install</a></li>
<li><a href="/v1.6/bundle_update.html">bundle update</a></li>
<div class='buttons'>
<a href="/v1.6/commands.html">View all commands</a>
</div>
</ul>
<h2>Help With</h2>
<ul>
<li><a href="/v1.6/gemfile.html">Gemfiles</a></li>
<li><a href="/v1.6/groups.html">Groups</a></li>
<li><a href="/v1.6/git.html">Gems from git</a></li>
<li><a href="/v1.6/bundler_setup.html">Bundler.setup</a></li>
<li><a href="/v1.6/deploying.html">Deploying</a></li>
<li><a href="/v1.6/bundler_sharing.html">Sharing</a></li>
<li><a href="/v1.6/updating_gems.html">Updating Gems</a></li>
<li><a href="/compatibility.html">Compatible versions</a></li>
</ul>
<h2>Use Bundler with</h2>
<ul>
<li><a href="/v1.6/rails3.html">Rails 3</a></li>
<li><a href="/v1.6/rails23.html">Rails 2.3</a></li>
<li><a href="/v1.6/sinatra.html">Sinatra</a></li>
<li><a href="/v1.6/rubygems.html">Rubygems</a></li>
<li><a href="/v1.6/rubymotion.html">RubyMotion</a></li>
</ul>
<div class='shirts'>
<div class='content'>
<a class="image" onclick="ga('send', 'devswag');" href="http://www.devswag.com/collections/bundler"><img src="/images/bundler-shirt.png" />
</a>
<p>
<a onclick="ga('send', 'devswag');" href="http://www.devswag.com/collections/bundler">Buy Bundler Shirts & Stickers!</a>
</p>
</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 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 class="current" 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>
|
