Update egit help for 0.8.0 from wiki
[egit.git] / org.eclipse.egit.doc / help / EGit / User_Guide / Working-with-remote-Repositories.html
blobc87562bf83493ed54c293ca34f62893c5336650b
1 <?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">
2 <html xmlns="http://www.w3.org/1999/xhtml">
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
5 <title>EGit User Guide - Working with remote Repositories</title>
6 <link type="text/css" rel="stylesheet" href="../../book.css"/>
7 </head>
8 <body>
9 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
10 <tr>
11 <th style="width: 100%" align="center" colspan="3">Working with remote Repositories</th>
12 </tr>
13 <tr>
14 <td style="width: 20%" align="left">
15 <a href="Starting-from-existing-Git-Repositories.html" title="Starting from existing Git Repositories">
16 <img alt="Previous" border="0" src="../../images/prev.gif"/>
17 </a>
18 </td>
19 <td style="width: 60%" align="center"></td>
20 <td style="width: 20%" align="right">
21 <a href="Inspecting-the-state-of-the-Repository.html" title="Inspecting the state of the Repository">
22 <img alt="Next" border="0" src="../../images/next.gif"/>
23 </a>
24 </td>
25 </tr>
26 <tr>
27 <td style="width: 20%" align="left" valign="top">Starting from existing Git Repositories</td>
28 <td style="width: 60%" align="center"></td>
29 <td style="width: 20%" align="right" valign="top">Inspecting the state of the Repository</td>
30 </tr>
31 </table><hr/>
32 <h1 id="Working_with_remote_Repositories">Working with remote Repositories</h1>
33 <h2 id="Cloning_Remote_Repositories">Cloning Remote Repositories</h2>
34 <p>Using the Git Clone Wizard you may clone remote repositories using different transport protocols. </p>
35 <p>The wizard can be started from the "Import Projects from Git" wizard using
37 <br/>
39 <b>Import... &gt; Git &gt; Projects from Git &gt; Next &gt; Clone...</b>
40 </p>
41 <p>or from the "Git Repositories View" (described elsewhere) using the
42 <b>Clone a Git Repository</b> toolbar button.
43 </p>
44 <h3 id="Repository_Selection">Repository Selection</h3>
45 <p>On the first page of the wizard enter the location of the remote repository: </p>
46 <p>
47 <img border="0" src="images/02-GitProtocol.png"/>
48 </p>
49 <ul>
50 <li>
51 <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.
52 <br/>Note that you can use the
53 <b>Local file...</b> button to browse for a local directory and that the URI field offers content assist by offering previously used values
54 </li>
55 <li>
56 <b>Host</b> - The name of the remote host or empty if cloning from the file system.
57 </li>
58 <li>
59 <b>Repository Path</b> - Path to the remote repository or on the file system.
60 </li>
61 <li>
62 <b>Protocol</b> - One of the protocols described below.
63 </li>
64 <li>
65 <b>Port</b> - Port number.
66 </li>
67 <li>
68 <b>User</b> - The user name used for authentication.
69 </li>
70 <li>
71 <b>Password</b> The password used for authentication.
72 </li>
73 </ul>
74 <p>The following protocols are supported: </p>
75 <ul>
76 <li>
77 <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.
78 </li>
79 <li>
80 <b>git+ssh</b> - Git over
81 <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.
82 </li>
83 <li>
84 <b>sftp</b> -
85 <a href="http://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol" target="egit_external">SSH File Transfer Protocol</a>
86 </li>
87 <li>
88 <b>http</b> -
89 <a href="http://tools.ietf.org/html/rfc2616" target="egit_external">Hypertext Transfer Protocol</a> can be tunneled through firewalls.
90 </li>
91 <li>
92 <b>https</b> -
93 <a href="http://tools.ietf.org/html/rfc2818" target="egit_external">Hypertext Transfer Protocol Secure</a> can be tunneled through firewalls.
94 </li>
95 <li>
96 <b>ftp</b> -
97 <a href="http://tools.ietf.org/html/rfc959" target="egit_external">File Transfer Protocol</a>
98 </li>
99 <li>
100 <b>file</b> - File system access to the repository.
101 </li>
102 </ul>
103 <h3 id="Branch_Selection">Branch Selection</h3>
104 <p>On the next page choose which branch should be cloned from the remote repository: </p>
106 <img border="0" src="images/05-branches.png"/>
107 </p>
108 <h3 id="Local_Destination">Local Destination</h3>
109 <p>On the next page define where you want to store the repository on the local file system and define some initial settings. </p>
111 <img border="0" src="images/06-LocalStorage.png"/>
112 </p>
113 <ul>
114 <li>
115 <b>Directory</b> - The directory which will contain the Git repository. It will be created by the wizard if it does not yet exist.
116 </li>
117 <li>
118 <b>Initial branch</b> - Choose here which local branch will be created and initially checked out.
119 </li>
120 <li>
121 <b>Remote name</b> - Define a name for the remote repository. The default is "origin".
122 </li>
123 </ul>
124 <h2 id="Git_References">Git References</h2>
125 <p>Git References are also known shortly as
126 <b>Refs</b>.
128 <br/>They comprise
129 </p>
130 <ul>
131 <li>branches </li>
132 <li>remote-tracking branches </li>
133 <li>tags </li>
134 </ul>
135 <p>They all are named with a path using '/' as path separator and are starting with "refs". </p>
136 <ul>
137 <li>Local branches start with "refs/heads/"</li>
138 <li>Remote tracking branches start with "refs/remotes/"</li>
139 <li>Tags start with "refs/tags/"</li>
140 </ul>
141 <p>Ref names can be abbreviated as long as the abbreviated form is unique.
143 <br/>E.g.
144 </p>
145 <ul>
146 <li>"master" is short for "refs/heads/master"</li>
147 <li>"origin/master" is short for "refs/remotes/origin/master"</li>
148 <li>"v1.0.1" is short for "refs/tags/v1.0.1"</li>
149 </ul>
150 <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
151 <a href="http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html" target="egit_external">git rev-parse</a>.
152 </p>
153 <h2 id="Pushing_to_other_Repositories">Pushing to other Repositories</h2>
154 <h3 id="Direct_Push">Direct Push</h3>
155 <p>The easiest way for pushing is to use
156 <a href="Managing-Repositories.html#Direct_Fetch_and_Push_Support">Direct Push Support</a> on a Push Specification of a Remote.
157 </p>
158 <h3 id="Push_Wizard">Push Wizard</h3>
159 <p>The other way is using the Push Wizard
161 <br/>
163 <b>Team &gt; Push...</b>
164 </p>
165 <h4 id="Push_URI">Push URI</h4>
166 <ul>
167 <li>If you already configured a Push Specification in the Repositories View you may also select it here using the drop-down list under
168 <b>Configured remote repositories</b>.
169 </li>
170 <li>Otherwise click
171 <b>Custom URI</b> and enter the URI of the upstream repository you want to push to.
172 </li>
173 </ul>
175 <img border="0" src="images/Egit-0.8-push-to-uri.png"/>
176 </p>
177 <h4 id="Push_Ref_Specifications">Push Ref Specifications</h4>
179 <br/>
180 Click
181 <b>Next</b>
183 <br/>
184 Click
185 <b>Add all branches spec</b>
186 </p>
188 <img border="0" src="images/Egit-0.8-push-wizard.png"/>
189 </p>
190 <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>
191 <p>Click
192 <b>Add all tags spec</b> to map local tags 1:1 to tags in the repository you want to push to.
193 </p>
194 <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>
195 <ul>
196 <li>enter source and destination ref or select already existing branches from the drop-down lists</li>
197 <li>click
198 <b>Add spec</b>
199 </li>
200 </ul>
201 <p>This will transfer the newly defined mapping to the list
202 <b>Specifications for push</b>
203 </p>
205 <b>Other common push specs:</b>
206 </p>
207 <ul>
208 <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
209 <i>joe</i>. This is useful if multiple users want to publish their local branches on personal branches in a jointly used public repository.
210 </li>
211 <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>
212 </ul>
213 <h4 id="Delete_Ref_Specifications">Delete Ref Specifications</h4>
214 <p>To delete a ref in the destination repository select the ref to be deleted from the drop-down list
215 <b>Remote ref to delete</b>
216 and click
217 <b>Add spec</b>. This will create a corresponding entry in the
218 <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.
219 </p>
221 <img border="0" src="images/Egit-0.8-push-ref-delete.png"/>
222 </p>
223 <h4 id="Conflicting_Push_Ref_Specifications">Conflicting Push Ref Specifications</h4>
224 <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
225 <b>Specifications for push</b>
226 </p>
228 <img border="0" src="images/Egit-0.8-push-conflicting-specs.png"/>
229 </p>
230 <h4 id="Push_Confirmation">Push Confirmation</h4>
231 <p>Click
232 <b>Next</b>
233 </p>
234 <p>This will open the Push Confirmation dialog showing a preview which changes will be pushed to the destination repository.
235 If this does not match your expectation click
236 <b>Back</b> and correct your push specs accordingly.
237 </p>
238 <ul>
239 <li>For ref updates the range of commits to be pushed will be shown in the format <tt>
240 <b>&lt;SHA1-from&gt;..&lt;SHA1-to&gt;</b></tt> e.g. <tt>
241 <b>d97f5a2e..adfdbfd2</b></tt> means all commits between <tt>
242 <b>d97f5a2e</b></tt> and <tt>
243 <b>adfdbfd2</b></tt> will be pushed.
244 </li>
245 <li>For refs which do not yet exist in the destination repository <tt>
246 <b>&#91;new branch&#93;</b></tt> or <tt>
247 <b>&#91;new tag&#93;</b></tt> is displayed.
248 </li>
249 <li>For refs which will be delete <tt>
250 <b>&#91;deleted&#93;</b></tt> is shown.
251 </li>
252 </ul>
254 <img border="0" src="images/Egit-0.8-push-confirmation.png"/>
255 </p>
256 <ul>
257 <li>Select the
258 <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.
259 </li>
260 <li>Select the
261 <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.
262 </li>
263 </ul>
264 <h4 id="Push_Result_Report">Push Result Report</h4>
265 <p>Click
266 <b>Finish</b>
267 </p>
268 <p>Depending on the options you have chosen a push result report dialog is shown</p>
270 <img border="0" src="images/Egit-0.8-push-result.png"/>
271 </p>
272 <p>Click
273 <b>Ok</b> to close the dialog.
274 </p>
275 <h3 id="Example:_Pushing_a_Local_Repository_to_GitHub">Example: Pushing a Local Repository to GitHub</h3>
276 <h4 id="Create_Local_Repository">Create Local Repository</h4>
277 <ul>
278 <li>follow
279 <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)
280 </li>
281 </ul>
282 <h4 id="Create_Repository_at_GitHub">Create Repository at GitHub</h4>
283 <ul>
284 <li>create a new repository at GitHub</li>
285 </ul>
287 <img border="0" src="images/Egit-0.6-001-CreateRepoAtGithub.png"/>
288 </p>
289 <ul>
290 <li>you get a fresh clone URL for this new repository</li>
291 </ul>
293 <img border="0" src="images/Egit-0.6-002-CloneUrl.png"/>
294 </p>
295 <h4 id="Eclipse_SSH_Configuration">Eclipse SSH Configuration</h4>
296 <ul>
297 <li>Click
298 <b>Window &gt; 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)
299 </li>
300 </ul>
302 <img border="0" src="images/Egit-0.6-003-SshPreferences.png"/>
303 </p>
304 <ul>
305 <li>if you don't have SSH keys yet you may generate them on the second tab
306 <b>Key Management</b> of this dialog, use a good pass phrase to protect your private key, for more details see
307 <a href="http://help.github.com/working-with-key-passphrases/" target="egit_external">"working with key passphrases"</a>
308 </li>
309 </ul>
310 <h4 id="Push_Upstream">Push Upstream</h4>
311 <ul>
312 <li>Select your new Eclipse project and click
313 <b>Team &gt; Push...</b>.
314 </li>
315 <li>Enter
316 <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>.
317 </li>
318 </ul>
320 <img border="0" src="images/Egit-0.6-004-PushDialog.png"/>
321 </p>
322 <ul>
323 <li>Click
324 <b>Next</b> and on first connection accept GitHub's host key.
325 </li>
326 </ul>
328 <img border="0" src="images/Egit-0.6-005-AcceptHostKey.png"/>
329 </p>
330 <ul>
331 <li>Enter your SSH key's passphrase.</li>
332 </ul>
334 <img border="0" src="images/Egit-0.6-006-PassPhrase.png"/>
335 </p>
336 <ul>
337 <li>Click
338 <b>Add all branches spec</b> to map your local branch names 1:1 to the same branch names in the destination repository.
339 </li>
340 </ul>
342 <img border="0" src="images/Egit-0.6-007-PushRefSpecifications.png"/>
343 </p>
344 <ul>
345 <li>Click
346 <b>Next</b>. The push confirmation dialog will show a preview of the changes that will be pushed to the destination repository.
347 </li>
348 <li>Click
349 <b>Finish</b> to confirm that you want to push these changes.
350 </li>
351 </ul>
353 <img border="0" src="images/Egit-0.6-008-PushConfirmation.png"/>
354 </p>
355 <ul>
356 <li>The next dialog reports the result of the push operation.</li>
357 </ul>
359 <img border="0" src="images/Egit-0.6-009-PushResult.png"/>
360 </p>
361 <ul>
362 <li>Point your browser at your GitHub repository to see that your new repository content has arrived</li>
363 </ul>
365 <img border="0" src="images/Egit-0.6-010-PushResultOnGithub.png"/>
366 </p>
367 <h2 id="Fetching_from_other_Repositories">Fetching from other Repositories</h2>
368 <h3 id="Direct_Fetch">Direct Fetch</h3>
369 <p>The easiest way for fetching is to use
370 <a href="Managing-Repositories.html#Direct_Fetch_and_Push_Support">Direct Fetch Support</a> on a Fetch Specification of a Remote.
371 </p>
372 <h3 id="Fetch_Wizard">Fetch Wizard</h3>
373 <p>The other way is using the Fetch Wizard
375 <br/>
377 <b>Team &gt; Fetch...</b>
378 </p>
379 <ul>
380 <li>If you already configured a Fetch Specification in the Repositories View you may also select it here using the drop-down list under
381 <b>Configured remote repositories</b>.
382 </li>
383 </ul>
385 <img border="0" src="images/Egit-0.8-fetch-from-fetch-spec.png"/>
386 </p>
387 <ul>
388 <li>Otherwise click
389 <b>Custom URI</b> and enter the URI of the upstream repository you want to fetch changes from.
390 </li>
391 </ul>
393 <img border="0" src="images/Egit-0.8-fetch-from-uri.png"/>
394 </p>
395 <h4 id="Fetch_Ref_Specifications">Fetch Ref Specifications</h4>
396 <p>Click
397 <b>Next</b>
399 <br/>
400 Click
401 <b>Add all branches spec</b>
402 </p>
404 <img border="0" src="images/Egit-0.8-fetch-spec.png"/>
405 </p>
406 <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>
407 <ul>
408 <li>Click in the edit field
409 <b>Destination Ref</b> and replace the path segment
410 <i>choose_remote_name</i> with a symbolic name for the upstream repository you are going to fetch from.
411 </li>
412 <li>The default remote name for the repository your repository has been cloned from is <tt>
413 <b>origin</b></tt>. The master of this remote maps by default from <tt>
414 <b>refs/heads/master</b></tt> to <tt>
415 <b>refs/remotes/origin/master</b></tt>.
416 </li>
417 <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>
418 <b>refs/heads/*</b></tt> to the following tracking branches <tt>
419 <b>refs/remotes/joe/*</b></tt>.
420 </li>
421 <li>Deselect
422 <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.
423 </li>
424 <li>Click
425 <b>Force Update all Refs</b> to set the force update option on all specs
426 </li>
427 <li>Click
428 <b>Remove all specs</b> to remove all specs from the list
429 <b>Specifications for fetch</b>
430 </li>
431 </ul>
432 <ul>
433 <li>Click
434 <b>Add all tags spec</b> to map tags tags in the repository you want to fetch from 1:1 to local tags.
435 </li>
436 </ul>
437 <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>
438 <ul>
439 <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>
440 <li>click
441 <b>Add spec</b>
442 </li>
443 </ul>
444 <p>This will transfer the newly defined mapping to the list
445 <b>Specifications for fetch</b>
446 </p>
447 <h4 id="Fetch_Result_Report">Fetch Result Report</h4>
448 <p>Click
449 <b>Finish</b>
450 </p>
452 <img border="0" src="images/Egit-0.8-fetch-result.png"/>
453 </p>
454 <p>A fetch result dialog is shown.</p>
455 <ul>
456 <li>For ref updates the range of commits which have been fetched will be shown in the format <tt>
457 <b>&lt;SHA1-from&gt;..&lt;SHA1-to&gt;</b></tt> e.g. <tt>
458 <b>d97f5a2e..adfdbfd2</b></tt> means all commits between <tt>
459 <b>d97f5a2e</b></tt> and <tt>
460 <b>adfdbfd2</b></tt> have been fetched.
461 </li>
462 <li>For refs which didn't exist before in the local repository <tt>
463 <b>&#91;new branch&#93;</b></tt> or <tt>
464 <b>&#91;new tag&#93;</b></tt> is displayed.
465 </li>
466 <li>For refs which have been deleted <tt>
467 <b>&#91;deleted&#93;</b></tt> is shown.
468 </li>
469 </ul>
470 <h2 id="Pulling_New_Changes_from_Upstream_Repositories">Pulling New Changes from Upstream Repositories</h2>
471 <p>This is not yet fully available. </p>
472 <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>
473 <ul>
474 <li>
475 <a href="Working-with-remote-Repositories.html#Fetching_from_other_Repositories">Fetch changes</a> from upstream repository
476 </li>
477 <li>
478 <a href="Managing-Repositories.html#Check-out_of_Branches_and_Tags">Checkout the branch</a> you want to pull the upstream changes into
479 </li>
480 <li>
481 <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
482 </li>
483 </ul>
484 <p>Available alternatives currently include: </p>
485 <ul>
486 <li>run
487 <b>git pull</b> from outside eclipse (but
488 <a href="http://marc.info/?l=git&amp;m=123924844219075" target="egit_external">beware on Windows</a>)
489 </li>
490 <li>if you did no local change or want to discard your local changes, use
491 <b>Team &gt; Reset...</b>
492 </li>
493 </ul><hr/>
494 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
495 <tr>
496 <td style="width: 20%" align="left">
497 <a href="Starting-from-existing-Git-Repositories.html" title="Starting from existing Git Repositories">
498 <img alt="Previous" border="0" src="../../images/prev.gif"/>
499 </a>
500 </td>
501 <td style="width: 60%" align="center">
502 <a href="User-Guide.html" title="EGit User Guide">
503 <img alt="EGit User Guide" border="0" src="../../images/home.gif"/>
504 </a>
505 </td>
506 <td style="width: 20%" align="right">
507 <a href="Inspecting-the-state-of-the-Repository.html" title="Inspecting the state of the Repository">
508 <img alt="Next" border="0" src="../../images/next.gif"/>
509 </a>
510 </td>
511 </tr>
512 <tr>
513 <td style="width: 20%" align="left" valign="top">Starting from existing Git Repositories</td>
514 <td style="width: 60%" align="center"></td>
515 <td style="width: 20%" align="right" valign="top">Inspecting the state of the Repository</td>
516 </tr>
517 </table>
518 </body>
519 </html>