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
|
<!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>Gems from git repositories</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Bundler adds the ability to use gems directly from git repositories. Setting
them up is as easy as adding a gem to your Gemfile. Using the very latest
version of a gem (or even a fork) is just as easy as using an official
release.
</div>
<div class='description'>
Because Rubygems lacks the ability to handle gems from git, any gems
installed from a git repository will not show up in <code>gem list</code>.
They will, however, be available after running <code>Bundler.setup</code>.
</div>
</div>
<div class='bullet'>
<div class='description'>
Specify that a gem should come from a git
repository with a .gemspec at its root
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/tenderlove/nokogiri.git'</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
If there is no .gemspec at the root of
a git repository, you must specify a version
that bundler should use when resolving
dependencies
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'deep_merge'</span><span class="p">,</span> <span class="s1">'1.0'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/peritor/deep_merge.git'</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
Specify that a git repository containing
multiple .gemspec files should be treated
as a gem source
</div>
<pre class="highlight ruby"><span class="n">git</span> <span class="s1">'https://github.com/rails/rails.git'</span> <span class="k">do</span>
 <span class="n">gem</span> <span class="s1">'railties'</span>
 <span class="n">gem</span> <span class="s1">'action_pack'</span>
 <span class="n">gem</span> <span class="s1">'active_model'</span>
<span class="k">end</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
Specify that a git repository should use
a particular ref, branch, or tag
</div>
<pre class="highlight ruby"><span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/rails/rails.git'</span><span class="p">,</span> <span class="ss">:ref</span> <span class="o">=></span> <span class="s1">'4aded'</span>
<span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/rails/rails.git'</span><span class="p">,</span> <span class="ss">:branch</span> <span class="o">=></span> <span class="s1">'2-3-stable'</span>
<span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/rails/rails.git'</span><span class="p">,</span> <span class="ss">:tag</span> <span class="o">=></span> <span class="s1">'v2.3.5'</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
Specifying a ref, branch, or tag for a
git repository specified inline works
exactly the same way
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/tenderlove/nokogiri.git'</span><span class="p">,</span> <span class="ss">:ref</span> <span class="o">=></span> <span class="s1">'0eec4'</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
Bundler can use HTTP(S), SSH, or git
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/tenderlove/nokogiri.git'</span>
<span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'git@github.com:tenderlove/nokogiri.git'</span>
<span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'git://github.com/tenderlove/nokogiri.git'</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
If you are getting your gems from a public GitHub repository,
you can use the shorthand
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="ss">:github</span> <span class="o">=></span> <span class="s1">'tenderlove/nokogiri'</span></pre>
<div class='description'>
If the repository name is the same as the GitHub account hosting it,
you can omit it
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="ss">:github</span> <span class="o">=></span> <span class="s1">'rails'</span></pre>
<div class='description'>
<b>NB:</b> This shorthand is insecure in versions of Bundler prior to 2.0! Use HTTPS instead
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=></span> <span class="s1">'https://github.com/rails/rails'</span></pre>
<div class='description'>
Alternatively, you can specify a full commit hash
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="ss">:github</span> <span class="o">=></span> <span class="s1">'rails'</span><span class="p">,</span> <span class="ss">:ref</span> <span class="o">=></span> <span class="s1">'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56'</span>
</pre>
</div>
</div>
<h2>Security</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
<code>http://</code> and <code>git://</code> URLs are insecure, and should
be avoided if at all possible. These protocols are unauthenticated, so a
man-in-the-middle attacker can tamper with the code and compromise your system.
Note that the <code>:github</code> shortcut translates to a <code>git://</code>
URL in pre-2.0 versions.
</div>
</div>
</div>
<h2 id='local'>Local Git Repos</h2>
<div class='contents'>
<div class='bullet'>
<div class='description'>
Bundler also allows you to work against a git repository locally
instead of using the remote version. This can be achieved by setting
up a local override:
</div>
<pre class="highlight plaintext">bundle config local.GEM_NAME /path/to/local/git/repository
</pre>
</div>
<div class='bullet'>
<div class='description'>
For example, in order to use a local Rack repository, a developer could call:
</div>
<pre class="highlight plaintext">bundle config local.rack ~/Work/git/rack</pre>
<div class='description'>
and setup the git repo pointing to a branch:
</div>
<pre class="highlight ruby"><span class="n">gem</span> <span class="s1">'rack'</span><span class="p">,</span> <span class="ss">:github</span> <span class="o">=></span> <span class="s1">'rack/rack'</span><span class="p">,</span> <span class="ss">:branch</span> <span class="o">=></span> <span class="s1">'master'</span>
</pre>
</div>
<div class='bullet'>
<div class='description'>
<p>
Now instead of checking out the remote git repository, the local
override will be used. Similar to a path source, every time the local
git repository change, changes will be automatically picked up by
Bundler. This means a commit in the local git repo will update the
revision in the <code>Gemfile.lock</code> to the local git repo revision. This
requires the same attention as git submodules. Before pushing to
the remote, you need to ensure the local override was pushed, otherwise
you may point to a commit that only exists in your local machine.
</p>
<p>
Bundler does many checks to ensure a developer won't work with
invalid references. Particularly, we force a developer to specify
a branch in the <code>Gemfile</code> in order to use this feature. If the branch
specified in the <code>Gemfile</code> and the current branch in the local git
repository do not match, Bundler will abort. This ensures that
a developer is always working against the correct branches, and prevents
accidental locking to a different branch.
</p>
<p>
Finally, Bundler also ensures that the current revision in the
<code>Gemfile.lock</code> exists in the local git repository. By doing this, Bundler
forces you to fetch the latest changes in the remotes.
</p>
</div>
</div>
<div class='bullet'>
<div class='description'>
<p>If you do not want bundler to make these branch checks, you can override it by setting this option:</p>
</div>
<pre class="highlight plaintext">bundle config disable_local_branch_check true</pre>
</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>
|
