blob: fd971d6013dc853487cd0885ed1e127dc6347b8b (
plain) (
blame)
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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
|
<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>EGit User Guide - Working with remote Repositories</title>
<link type="text/css" rel="stylesheet" href="../../book.css"/>
</head>
<body>
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<th style="width: 100%" align="center" colspan="3">Working with remote Repositories</th>
</tr>
<tr>
<td style="width: 20%" align="left">
<a href="Starting-from-existing-Git-Repositories.html" title="Starting from existing Git Repositories">
<img alt="Previous" border="0" src="../../images/prev.gif"/>
</a>
</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right">
<a href="Inspecting-the-state-of-the-Repository.html" title="Inspecting the state of the Repository">
<img alt="Next" border="0" src="../../images/next.gif"/>
</a>
</td>
</tr>
<tr>
<td style="width: 20%" align="left" valign="top">Starting from existing Git Repositories</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top">Inspecting the state of the Repository</td>
</tr>
</table><hr/>
<h1 id="Working_with_remote_Repositories">Working with remote Repositories</h1>
<h2 id="Cloning_Remote_Repositories">Cloning Remote Repositories</h2>
<p>Using the Git Clone Wizard you may clone remote repositories using different transport protocols. </p>
<p>The wizard can be started from the "Import Projects from Git" wizard using
<br/>
<b>Import... > Git > Projects from Git > Next > Clone...</b>
</p>
<p>or from the "Git Repositories View" (described elsewhere) using the
<b>Clone a Git Repository</b> toolbar button.
</p>
<h3 id="Repository_Selection">Repository Selection</h3>
<p>On the first page of the wizard enter the location of the remote repository: </p>
<p>
<img border="0" src="images/02-GitProtocol.png"/>
</p>
<ul>
<li>
<b>URI</b> - The complete URI of the remote repository or the path on the file system. This field is automatically synchronized with the other fields.
<br/>Note that you can use the
<b>Local file...</b> button to browse for a local directory and that the URI field offers content assist by offering previously used values
</li>
<li>
<b>Host</b> - The name of the remote host or empty if cloning from the file system.
</li>
<li>
<b>Repository Path</b> - Path to the remote repository or on the file system.
</li>
<li>
<b>Protocol</b> - One of the protocols described below.
</li>
<li>
<b>Port</b> - Port number.
</li>
<li>
<b>User</b> - The user name used for authentication.
</li>
<li>
<b>Password</b> The password used for authentication.
</li>
</ul>
<p>The following protocols are supported: </p>
<ul>
<li>
<b>git</b> - The most efficient built-in git protocol (default port 9418). This protocol doesn't provide authentication. Typically used for anonymous read access to the repository.
</li>
<li>
<b>git+ssh</b> - Git over
<a href="http://tools.ietf.org/html/rfc4251" target="egit_external">secure shell (SSH)</a> protocol. Typically used for authenticated write access to the repository.
</li>
<li>
<b>sftp</b> -
<a href="http://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol" target="egit_external">SSH File Transfer Protocol</a>
</li>
<li>
<b>http</b> -
<a href="http://tools.ietf.org/html/rfc2616" target="egit_external">Hypertext Transfer Protocol</a> can be tunneled through firewalls.
</li>
<li>
<b>https</b> -
<a href="http://tools.ietf.org/html/rfc2818" target="egit_external">Hypertext Transfer Protocol Secure</a> can be tunneled through firewalls.
</li>
<li>
<b>ftp</b> -
<a href="http://tools.ietf.org/html/rfc959" target="egit_external">File Transfer Protocol</a>
</li>
<li>
<b>file</b> - File system access to the repository.
</li>
</ul>
<h3 id="Branch_Selection">Branch Selection</h3>
<p>On the next page choose which branch should be cloned from the remote repository: </p>
<p>
<img border="0" src="images/05-branches.png"/>
</p>
<h3 id="Local_Destination">Local Destination</h3>
<p>On the next page define where you want to store the repository on the local file system and define some initial settings. </p>
<p>
<img border="0" src="images/06-LocalStorage.png"/>
</p>
<ul>
<li>
<b>Directory</b> - The directory which will contain the Git repository. It will be created by the wizard if it does not yet exist.
</li>
<li>
<b>Initial branch</b> - Choose here which local branch will be created and initially checked out.
</li>
<li>
<b>Remote name</b> - Define a name for the remote repository. The default is "origin".
</li>
</ul>
<h2 id="Git_References">Git References</h2>
<p>Git References are also known shortly as
<b>Refs</b>.
<br/>They comprise
</p>
<ul>
<li>branches </li>
<li>remote-tracking branches </li>
<li>tags </li>
</ul>
<p>They all are named with a path using '/' as path separator and are starting with "refs". </p>
<ul>
<li>Local branches start with "refs/heads/"</li>
<li>Remote tracking branches start with "refs/remotes/"</li>
<li>Tags start with "refs/tags/"</li>
</ul>
<p>Ref names can be abbreviated as long as the abbreviated form is unique.
<br/>E.g.
</p>
<ul>
<li>"master" is short for "refs/heads/master"</li>
<li>"origin/master" is short for "refs/remotes/origin/master"</li>
<li>"v1.0.1" is short for "refs/tags/v1.0.1"</li>
</ul>
<p>For a complete list for Ref names and the order of precedence if multiple references have the same shorthand form see the section "Specifying Revisions" section of
<a href="http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html" target="egit_external">git rev-parse</a>.
</p>
<h2 id="Pushing_to_other_Repositories">Pushing to other Repositories</h2>
<h3 id="Direct_Push">Direct Push</h3>
<p>The easiest way for pushing is to use
<a href="Managing-Repositories.html#Direct_Fetch_and_Push_Support">Direct Push Support</a> on a Push Specification of a Remote.
</p>
<h3 id="Push_Wizard">Push Wizard</h3>
<p>The other way is using the Push Wizard
<br/>
<b>Team > Push...</b>
</p>
<h4 id="Push_URI">Push URI</h4>
<ul>
<li>If you already configured a Push Specification in the Repositories View you may also select it here using the drop-down list under
<b>Configured remote repositories</b>.
</li>
<li>Otherwise click
<b>Custom URI</b> and enter the URI of the upstream repository you want to push to.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.8-push-to-uri.png"/>
</p>
<h4 id="Push_Ref_Specifications">Push Ref Specifications</h4>
<p>
<br/>
Click
<b>Next</b>
<br/>
Click
<b>Add all branches spec</b>
</p>
<p>
<img border="0" src="images/Egit-0.8-push-wizard.png"/>
</p>
<p>This is a convenient way to declare that you want to map your local branch names to the same branch names on the upstream repository you want to push changes to. </p>
<p>Click
<b>Add all tags spec</b> to map local tags 1:1 to tags in the repository you want to push to.
</p>
<p>If you want to map local branches to those in the upstream repository in a different way you may define more detailed mapping specifications in the following way</p>
<ul>
<li>enter source and destination ref or select already existing branches from the drop-down lists</li>
<li>click
<b>Add spec</b>
</li>
</ul>
<p>This will transfer the newly defined mapping to the list
<b>Specifications for push</b>
</p>
<p>
<b>Other common push specs:</b>
</p>
<ul>
<li>You may e.g. map <tt>refs/heads/*</tt> to <tt>refs/heads/joe/*</tt> if you want to name the branches you push to according to your nickname
<i>joe</i>. This is useful if multiple users want to publish their local branches on personal branches in a jointly used public repository.
</li>
<li>Another usual mapping is to map the source ref <tt>HEAD</tt> to the destination <tt>refs/heads/master</tt>. This means you want to map your current <tt>HEAD</tt> (which might currently point e.g. to any local topic branch) to the upstream master branch.</li>
</ul>
<h4 id="Delete_Ref_Specifications">Delete Ref Specifications</h4>
<p>To delete a ref in the destination repository select the ref to be deleted from the drop-down list
<b>Remote ref to delete</b>
and click
<b>Add spec</b>. This will create a corresponding entry in the
<b>Specifications for push</b> list. Alternatively you may type in the specification for the refs to be deleted, this may also use wildcards. Pushing Delete Ref Specifications will delete the matching Refs in the destination repository.
</p>
<p>
<img border="0" src="images/Egit-0.8-push-ref-delete.png"/>
</p>
<h4 id="Conflicting_Push_Ref_Specifications">Conflicting Push Ref Specifications</h4>
<p>If you add multiple conflicting Push Ref Specifications they will be marked in red, solve this by removing or editing the conflicting specs. It is also possible to edit the specs in-place in the list
<b>Specifications for push</b>
</p>
<p>
<img border="0" src="images/Egit-0.8-push-conflicting-specs.png"/>
</p>
<h4 id="Push_Confirmation">Push Confirmation</h4>
<p>Click
<b>Next</b>
</p>
<p>This will open the Push Confirmation dialog showing a preview which changes will be pushed to the destination repository.
If this does not match your expectation click
<b>Back</b> and correct your push specs accordingly.
</p>
<ul>
<li>For ref updates the range of commits to be pushed will be shown in the format <tt>
<b><SHA1-from>..<SHA1-to></b></tt> e.g. <tt>
<b>d97f5a2e..adfdbfd2</b></tt> means all commits between <tt>
<b>d97f5a2e</b></tt> and <tt>
<b>adfdbfd2</b></tt> will be pushed.
</li>
<li>For refs which do not yet exist in the destination repository <tt>
<b>[new branch]</b></tt> or <tt>
<b>[new tag]</b></tt> is displayed.
</li>
<li>For refs which will be delete <tt>
<b>[deleted]</b></tt> is shown.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.8-push-confirmation.png"/>
</p>
<ul>
<li>Select the
<b>Push only if remote refs don't change in the mean time</b> check box if you want to be sure that what you see in this preview is also what you get when pushing these changes out.
</li>
<li>Select the
<b>Show final report dialog only when it differs from this confirmation report</b> check box if you only want to get a report after executing the push if the result differs from this preview.
</li>
</ul>
<h4 id="Push_Result_Report">Push Result Report</h4>
<p>Click
<b>Finish</b>
</p>
<p>Depending on the options you have chosen a push result report dialog is shown</p>
<p>
<img border="0" src="images/Egit-0.8-push-result.png"/>
</p>
<p>Click
<b>Ok</b> to close the dialog.
</p>
<h3 id="Example:_Pushing_a_Local_Repository_to_GitHub">Example: Pushing a Local Repository to GitHub</h3>
<h4 id="Create_Local_Repository">Create Local Repository</h4>
<ul>
<li>follow
<a href="http://wiki.eclipse.org/EGit/User_Guide/Getting_Started" title="EGit/User Guide/Getting Started" target="egit_external">EGit/User Guide/Getting Started</a> to create a new local repository (with your content instead of the demo project)
</li>
</ul>
<h4 id="Create_Repository_at_GitHub">Create Repository at GitHub</h4>
<ul>
<li>create a new repository at GitHub</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-001-CreateRepoAtGithub.png"/>
</p>
<ul>
<li>you get a fresh clone URL for this new repository</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-002-CloneUrl.png"/>
</p>
<h4 id="Eclipse_SSH_Configuration">Eclipse SSH Configuration</h4>
<ul>
<li>Click
<b>Window > Preferences</b> and ensure that your SSH2 home is configured correctly (usually this is <tt>~/.ssh</tt>) and contains your SSH2 keys (upload your public key to your GitHub account settings)
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-003-SshPreferences.png"/>
</p>
<ul>
<li>if you don't have SSH keys yet you may generate them on the second tab
<b>Key Management</b> of this dialog, use a good pass phrase to protect your private key, for more details see
<a href="http://help.github.com/working-with-key-passphrases/" target="egit_external">"working with key passphrases"</a>
</li>
</ul>
<h4 id="Push_Upstream">Push Upstream</h4>
<ul>
<li>Select your new Eclipse project and click
<b>Team > Push...</b>.
</li>
<li>Enter
<b>Your GitHub Clone URL</b> and your GitHub password (with the free github accounts do not enter a password but leave this field blank), leave the user as <tt>git</tt>.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-004-PushDialog.png"/>
</p>
<ul>
<li>Click
<b>Next</b> and on first connection accept GitHub's host key.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-005-AcceptHostKey.png"/>
</p>
<ul>
<li>Enter your SSH key's passphrase.</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-006-PassPhrase.png"/>
</p>
<ul>
<li>Click
<b>Add all branches spec</b> to map your local branch names 1:1 to the same branch names in the destination repository.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-007-PushRefSpecifications.png"/>
</p>
<ul>
<li>Click
<b>Next</b>. The push confirmation dialog will show a preview of the changes that will be pushed to the destination repository.
</li>
<li>Click
<b>Finish</b> to confirm that you want to push these changes.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-008-PushConfirmation.png"/>
</p>
<ul>
<li>The next dialog reports the result of the push operation.</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-009-PushResult.png"/>
</p>
<ul>
<li>Point your browser at your GitHub repository to see that your new repository content has arrived</li>
</ul>
<p>
<img border="0" src="images/Egit-0.6-010-PushResultOnGithub.png"/>
</p>
<h2 id="Fetching_from_other_Repositories">Fetching from other Repositories</h2>
<h3 id="Direct_Fetch">Direct Fetch</h3>
<p>The easiest way for fetching is to use
<a href="Managing-Repositories.html#Direct_Fetch_and_Push_Support">Direct Fetch Support</a> on a Fetch Specification of a Remote.
</p>
<h3 id="Fetch_Wizard">Fetch Wizard</h3>
<p>The other way is using the Fetch Wizard
<br/>
<b>Team > Fetch...</b>
</p>
<ul>
<li>If you already configured a Fetch Specification in the Repositories View you may also select it here using the drop-down list under
<b>Configured remote repositories</b>.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.8-fetch-from-fetch-spec.png"/>
</p>
<ul>
<li>Otherwise click
<b>Custom URI</b> and enter the URI of the upstream repository you want to fetch changes from.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.8-fetch-from-uri.png"/>
</p>
<h4 id="Fetch_Ref_Specifications">Fetch Ref Specifications</h4>
<p>Click
<b>Next</b>
<br/>
Click
<b>Add all branches spec</b>
</p>
<p>
<img border="0" src="images/Egit-0.8-fetch-spec.png"/>
</p>
<p>This is a convenient way to declare that you want to map the branch names in the upstream repository you want to fetch changes from 1:1 to the same local branch names. </p>
<ul>
<li>Click in the edit field
<b>Destination Ref</b> and replace the path segment
<i>choose_remote_name</i> with a symbolic name for the upstream repository you are going to fetch from.
</li>
<li>The default remote name for the repository your repository has been cloned from is <tt>
<b>origin</b></tt>. The master of this remote maps by default from <tt>
<b>refs/heads/master</b></tt> to <tt>
<b>refs/remotes/origin/master</b></tt>.
</li>
<li>If you e.g. want to additionally track branches from Joe's repository in your local repository you would map the branch in his repository <tt>
<b>refs/heads/*</b></tt> to the following tracking branches <tt>
<b>refs/remotes/joe/*</b></tt>.
</li>
<li>Deselect
<b>Force Update</b> if you want to allow fast-forward updates only, select this option if you also want to allow non-fast-forward changes.
</li>
<li>Click
<b>Force Update all Refs</b> to set the force update option on all specs
</li>
<li>Click
<b>Remove all specs</b> to remove all specs from the list
<b>Specifications for fetch</b>
</li>
</ul>
<ul>
<li>Click
<b>Add all tags spec</b> to map tags tags in the repository you want to fetch from 1:1 to local tags.
</li>
</ul>
<p>If you want to map branches or tags in the upstream repository to local branches in a different way you may define more detailed mapping specifications in the following way</p>
<ul>
<li>enter source (ref in source repository) and destination ref (tracking branch or tag in local repository) or select already existing branches from the drop-down lists</li>
<li>click
<b>Add spec</b>
</li>
</ul>
<p>This will transfer the newly defined mapping to the list
<b>Specifications for fetch</b>
</p>
<h4 id="Fetch_Result_Report">Fetch Result Report</h4>
<p>Click
<b>Finish</b>
</p>
<p>
<img border="0" src="images/Egit-0.8-fetch-result.png"/>
</p>
<p>A fetch result dialog is shown.</p>
<ul>
<li>For ref updates the range of commits which have been fetched will be shown in the format <tt>
<b><SHA1-from>..<SHA1-to></b></tt> e.g. <tt>
<b>d97f5a2e..adfdbfd2</b></tt> means all commits between <tt>
<b>d97f5a2e</b></tt> and <tt>
<b>adfdbfd2</b></tt> have been fetched.
</li>
<li>For refs which didn't exist before in the local repository <tt>
<b>[new branch]</b></tt> or <tt>
<b>[new tag]</b></tt> is displayed.
</li>
<li>For refs which have been deleted <tt>
<b>[deleted]</b></tt> is shown.
</li>
</ul>
<h2 id="Pulling_New_Changes_from_Upstream_Repositories">Pulling New Changes from Upstream Repositories</h2>
<p>This is not yet fully available. </p>
<p>In cases where fast-forward merges are sufficient (full merge is not yet implemented) you may run pull in EGit in the following way:</p>
<ul>
<li>
<a href="Working-with-remote-Repositories.html#Fetching_from_other_Repositories">Fetch changes</a> from upstream repository
</li>
<li>
<a href="Managing-Repositories.html#Check-out_of_Branches_and_Tags">Checkout the branch</a> you want to pull the upstream changes into
</li>
<li>
<a href="Merging.html#Merging_a_branch_or_a_tag_into_the_current_branch">Merge</a> the branch or tag you want to integrate into your current branch
</li>
</ul>
<p>Available alternatives currently include: </p>
<ul>
<li>run
<b>git pull</b> from outside eclipse (but
<a href="http://marc.info/?l=git&m=123924844219075" target="egit_external">beware on Windows</a>)
</li>
<li>if you did no local change or want to discard your local changes, use
<b>Team > Reset...</b>
</li>
</ul><hr/>
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<td style="width: 20%" align="left">
<a href="Starting-from-existing-Git-Repositories.html" title="Starting from existing Git Repositories">
<img alt="Previous" border="0" src="../../images/prev.gif"/>
</a>
</td>
<td style="width: 60%" align="center">
<a href="User-Guide.html" title="EGit User Guide">
<img alt="EGit User Guide" border="0" src="../../images/home.gif"/>
</a>
</td>
<td style="width: 20%" align="right">
<a href="Inspecting-the-state-of-the-Repository.html" title="Inspecting the state of the Repository">
<img alt="Next" border="0" src="../../images/next.gif"/>
</a>
</td>
</tr>
<tr>
<td style="width: 20%" align="left" valign="top">Starting from existing Git Repositories</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top">Inspecting the state of the Repository</td>
</tr>
</table>
</body>
</html>
|
