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
|
<!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'>
<link href='/images/favicon.png' rel='shortcut icon' type='image/png'>
<link href="/stylesheets/application.css" media="screen" rel="stylesheet" type="text/css" />
<link href="/stylesheets/sunburst.css" media="screen" rel="stylesheet" type="text/css" />
</head>
<body>
<div id='body'>
<div id='contents'>
<div id='header'>
<a href="/"><img width="725" alt="The best way to manage your application's dependencies" src="/images/gembundler.png" />
</a>
</div>
<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="sunburst">gem <span class="String"><span class="String">'</span>nokogiri<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>git</span> => <span class="String"><span class="String">'</span>git://github.com/tenderlove/nokogiri.git<span class="String">'</span></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="sunburst">gem <span class="String"><span class="String">'</span>deep_merge<span class="String">'</span></span>, <span class="String"><span class="String">'</span>1.0<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>git</span> => <span class="String"><span class="String">'</span>git://github.com/peritor/deep_merge.git<span class="String">'</span></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="sunburst">git <span class="String"><span class="String">'</span>git://github.com/rails/rails.git<span class="String">'</span></span> <span class="Keyword">do</span>
 gem <span class="String"><span class="String">'</span>railties<span class="String">'</span></span>
 gem <span class="String"><span class="String">'</span>action_pack<span class="String">'</span></span>
 gem <span class="String"><span class="String">'</span>active_model<span class="String">'</span></span>
<span class="Keyword">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="sunburst"><span class="Constant"><span class="Constant">:</span>git</span> => <span class="String"><span class="String">'</span>git://github.com/rails/rails.git<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>ref</span> => <span class="String"><span class="String">'</span>4aded<span class="String">'</span></span>
<span class="Constant"><span class="Constant">:</span>git</span> => <span class="String"><span class="String">'</span>git://github.com/rails/rails.git<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>branch</span> => <span class="String"><span class="String">'</span>2-3-stable<span class="String">'</span></span>
<span class="Constant"><span class="Constant">:</span>git</span> => <span class="String"><span class="String">'</span>git://github.com/rails/rails.git<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>tag</span> => <span class="String"><span class="String">'</span>v2.3.5<span class="String">'</span></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="sunburst">gem <span class="String"><span class="String">'</span>nokogiri<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>git</span> => <span class="String"><span class="String">'</span>git://github.com/tenderlove/nokogiri.git<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>ref</span> => <span class="String"><span class="String">'</span>0eec4<span class="String">'</span></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="sunburst">gem <span class="String"><span class="String">'</span>nokogiri<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>github</span> => <span class="String"><span class="String">'</span>tenderlove/nokogiri<span class="String">'</span></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="sunburst">gem <span class="String"><span class="String">'</span>rails<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>github</span> => <span class="String"><span class="String">'</span>rails<span class="String">'</span></span>
</pre>
</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='sunburst'>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='sunburst'>bundle config local.rack ~/Work/git/rack</pre>
<div class='description'>
and setup the git repo pointing to a branch:
</div>
<pre class="sunburst">gem <span class="String"><span class="String">'</span>rack<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>github</span> => <span class="String"><span class="String">'</span>rack/rack<span class="String">'</span></span>, <span class="Constant"><span class="Constant">:</span>branch</span> => <span class="String"><span class="String">'</span>master<span class="String">'</span></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='sunburst'>bundle config disable_local_branch_check true</pre>
</div>
</div>
</div>
</div>
<div id='footer'>
<img src="/images/emocow.png" />
<img src="/images/panda.jpg" />
<div class='spacer'></div>
<div id='navigation'>
<p>
<b><a href="/v1.3/commands.html">commands</a></b>
<a href="/v1.3/bundle_install.html">install</a>
/
<a href="/v1.3/bundle_update.html">update</a>
/
<a href="/v1.3/bundle_exec.html">exec</a>
/
<a href="/v1.3/bundle_config.html">config</a>
/
<a href="/v1.3/bundle_package.html">package</a>
</p>
<p>
<b>usage</b>
<a href="/v1.3/gemfile.html">gemfile</a>
/
<a href="/v1.3/git.html">git</a>
/
<a href="/v1.3/groups.html">groups</a>
/
<a href="/v1.3/bundler_setup.html">setup</a>
/
<a href="/v1.3/deploying.html">deploying</a>
</p>
<p>
<b>frameworks</b>
<a href="/v1.3/bundler_setup.html">ruby</a>
/
<a href="/v1.3/rubygems.html">rubygems</a>
/
<a href="/v1.3/rubymotion.html">rubymotion</a>
/
<a href="/v1.3/sinatra.html">sinatra</a>
/
<a href="/v1.3/rails3.html">rails 3</a>
</p>
</div>
<div class='spacer'></div>
<img src="/images/bundler-small.png" />
</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>
<a href='http://github.com/carlhuda/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 class="current" href="/">v1.3</a>
</div>
<script>
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-557621-9']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>
|
