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
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
|
<?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 - Tasks</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">Tasks</th>
</tr>
<tr>
<td style="width: 20%" align="left">
<a href="Concepts.html" title="Concepts">
<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="Reference.html" title="Reference">
<img alt="Next" border="0" src="../../images/next.gif"/>
</a>
</td>
</tr>
<tr>
<td style="width: 20%" align="left" valign="top">Concepts</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top">Reference</td>
</tr>
</table><hr/>
<h1 id="Tasks">Tasks</h1>
<h2 id="Creating_Repositories">Creating Repositories</h2>
<h3 id="Creating_a_new_empty_Git_Repository">Creating a new empty Git Repository</h3>
<p>You can create a project first and share it afterwards. The Share Project Wizard supports creation of Git repositories (see
<a href="http://wiki.eclipse.org/EGit/User_Guide/Sharing#Adding_a_project_to_version_control" title="EGit/User Guide/Sharing#Adding_a_project_to_version_control" target="egit_external">Adding a project to version control</a>).
</p>
<p>You can also create a new empty Git Repository from the Git Repositories View (see
<a href="Creating_a_Repository" title="EGit/User_Guide#Creating_a_Repository">Creating a Repository</a>).
</p>
<h3 id="Creating_a_Git_Repository_for_multiple_Projects">Creating a Git Repository for multiple Projects</h3>
<p>You may first create multiple projects under a common directory and then create a common repository for all projects in one go: </p>
<ul>
<li>create the Eclipse projects e.g. a, b, c under a common directory e.g. <span style="font-family:monospace;">/repos/examples/</span> </li>
<li>select all projects a, b, c - from context menu click
<b>Team > Share Project > Git</b>
</li>
<li>press
<b>Next</b>
</li>
<li>select all projects a, b, c </li>
<li>the wizard automatically moves up the default repository location to the parent folder <span style="font-family:monospace;">/repos/examples/</span> since multiple projects have been selected </li>
<li>click
<b>Create Repository</b> and
<b>Finish</b>
</li>
</ul>
<p>
<br/>
</p>
<h2 id="Starting_from_existing_Git_Repositories">Starting from existing Git Repositories</h2>
<p>In order to work with the content of a Git repository in the Eclipse workbench, the contained files and folders must be imported as projects. In principle, this import can be done using the generic "New Project" or "Import..." wizards, since the working directory of a Git Repository is just a normal directory in the local file system. However, the newly created projects would still have to be shared manually with Git. The "Import Projects from Git" wizards integrates project import and sharing and also offers some extra convenience.</p>
<h3 id="Starting_the_import_wizard">Starting the import wizard</h3>
<p>To start the wizard click
<b>Import > Git > Projects from Git</b>
</p>
<p>If you started in a clean workspace, the first page will display an empty list:</p>
<p>
<img border="0" src="images/Egit-0.9-import-projects-select-repository.png"/>
</p>
<p>Before you can continue, you need to add one or several Git repositories to the list.
If you have already repositories in the list, this step is optional.</p>
<h3 id="Cloning_or_adding_Repositories">Cloning or adding Repositories</h3>
<p>There are two ways to add Git repositories to the list:</p>
<ol>
<li>Clone a remote repository</li>
<li>Add an existing repository from your local file system</li>
</ol>
<h4 id="Cloning_a_Repository">Cloning a Repository</h4>
<p>The first option is used if you start with a remote repository. The clone operation will copy that repository to your local file system. To start the Clone Wizard click
<b>Clone...</b>. The Clone Wizard is described in more detail in
<a href="Cloning_Remote_Repositories" title="EGit/User_Guide#Cloning_Remote_Repositories">Cloning Remote Repositories</a>. Upon successful completion of the clone operation, the newly cloned repository appears in the list automatically.
</p>
<h4 id="Adding_a_Repository">Adding a Repository</h4>
<p>The second option is useful if you already have a repository in your local file system, for example because you have cloned it earlier, you created it from scratch or you copied it from somewhere else. Click
<b>Add...</b>; and select a directory in the local file system. Press
<b>Search</b> to trigger a scan for Git repositories contained in this directory. If Git repositories are found, they will be listed and you can select repositories to add :
</p>
<p>
<img border="0" src="images/Egit-0.9-import-projects-add-dialog.png"/>
</p>
<p>After successful completion, the repository list should contain some repositories:</p>
<p>
<img border="0" src="images/Egit-0.9-import-projects-filled-list.png"/>
</p>
<h3 id="Selecting_a_Repository_from_the_List">Selecting a Repository from the List</h3>
<p>You can now select a repository and click
<b>Next</b>. On the following wizard page, you will have to decide:
</p>
<ul>
<li>How to do the import</li>
<li>How to share the imported projects</li>
<li>Optionally you may limit the scope of the wizard</li>
</ul>
<p>
<img border="0" src="images/Egit-0.9-import-projects-select-wizard.png"/>
</p>
<h3 id="Method_for_importing_Projects">Method for importing Projects</h3>
<h4 id="Import_Existing_Projects">Import Existing Projects</h4>
<p>If this radio button is selected, the wizard will scan the local file system for <tt>.project</tt> files and display the projects found for being imported. This is the most comfortable solution and should be used if <tt>.project</tt> files are checked into the Repository.</p>
<h5 id="Limiting_the_Scope_for_Project_Import">Limiting the Scope for Project Import</h5>
<p>In this case, the directory tree at the bottom is active. You can limit the search for <tt>.project</tt> files by selecting a folder in this tree, otherwise the complete working directory of the repository will be scanned. On the next page, a list of the found projects (if any) will be shown. This is very similar to the generic
<b>Import Existing Projects</b> wizard, but has some additional filtering capabilities:
</p>
<p>
<img border="0" src="images/Egit-0.9-import-projects-select-projects.png"/>
</p>
<h4 id="Use_the_New_Projects_Wizard">Use the New Projects Wizard</h4>
<p>When this option is chosen, the generic "New Project" wizard will open. After completion of the "New Project" wizard, the "Import Projects from Git" wizard will resume and assist with sharing the projects you just created.</p>
<p>In this case, the directory tree at the bottom is inactive, as the selection is not relevant for the "New Project" wizard.</p>
<h4 id="Import_as_General_Project">Import as General Project</h4>
<p>This option can be helpful when there are neither <tt>.project</tt> files available nor a suitable "New Project" wizard applies to the content of the Git Repository. If chosen, the wizard will generate a <tt>.project</tt> file and point the project to a folder of the Repository's working directory. The result is a "General Project".</p>
<p>By default, the newly generated project will point to the working directory of the Repository. By selecting some folder from the directory tree at the bottom, you can have the project generated for that folder.</p>
<p>Click
<b>Next</b> to open a simple dialog for entering a name and a directory for the new project:
</p>
<p>
<img border="0" src="images/Egit-0.9-import-projects-general-project.png"/>
</p>
<p>By default the suggested project name matches the name of the directory.</p>
<h3 id="Method_for_Sharing_Imported_Projects">Method for Sharing Imported Projects</h3>
<p>The newly created projects (if any) must be shared with the correct Git Repository in order to enable the Git Team Provider. The following sharing options are provided:</p>
<h4 id="Try_to_Share_Newly_Created_Projects_Automatically">Try to Share Newly Created Projects Automatically</h4>
<p>This is the recommended option: the wizard will automatically detect newly created projects and find the corresponding Repository automatically. No user interaction is required. If automatic sharing fails, the projects will simply remain unshared. You can share them any time later manually.</p>
<h4 id="Share_New_Projects_Interactively">Share New Projects Interactively</h4>
<p>This might be useful for special circumstances where the automatic detection fails. Note that this will block the UI until the project import is completed.</p>
<p>A page will be shown with the newly created projects and the corresponding repositories. Using the check boxes, you can decide which projects to share:</p>
<p>
<img border="0" src="images/Egit-0.9-import-projects-share-manually.png"/>
</p>
<h4 id="Do_Not_Share_New_Projects">Do Not Share New Projects</h4>
<p>This may be helpful if for some reason you want to share projects manually.
<br/>
<br/>
</p>
<h2 id="Working_with_remote_Repositories">Working with remote Repositories</h2>
<h3 id="Cloning_Remote_Repositories">Cloning Remote Repositories</h3>
<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 in
<a href="Managing_Repositories" title="EGit/User_Guide#Managing_Repositories">Managing Repositories</a>) using the
<b>Clone a Git Repository</b> toolbar button or view menu.
</p>
<h4 id="Repository_Selection">Repository Selection</h4>
<p>On the first page of the wizard enter the location of the remote repository: </p>
<p>
<img border="0" src="images/Egit-0.9-clone-wizard-url-page.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>
<li>
<b>Store in Secure Store</b> Whether the password is saved in the Eclipse secure store.
</li>
</ul>
<p>The following protocols are supported: </p>
<ul>
<li>
<b>file</b> - File system access to the repository.
</li>
<li>
<b>ftp</b> -
<a href="http://tools.ietf.org/html/rfc959" target="egit_external">File Transfer Protocol</a>
</li>
<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>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>sftp</b> -
<a href="http://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol" target="egit_external">SSH File Transfer Protocol</a>
</li>
<li>
<b>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>
</ul>
<p>
<b>New:</b> Support for authentication via HTTP or HTTPS protocol is introduced with EGit 0.10.
<br/>
<b>Note:</b> If you are behind a firewall you may need to configure your proxy settings (
<b>Preferences > General > Network Connections</b>). Many HTTP proxies are configured to block URLs containing a username (and/or password) like e.g.
<a href="http://fred:topsecret@egit.eclipse.org/egit.git" target="egit_external">http://fred:topsecret@egit.eclipse.org/egit.git</a> hence it's recommended to use the
<i>user</i>,
<i>password</i> fields at the bottom of the wizard page, the credentials will be transmitted as HTTP headers.
</p>
<h4 id="Branch_Selection">Branch Selection</h4>
<p>On the next page choose which branches shall be cloned from the remote repository: </p>
<p>
<img border="0" src="images/Egit-0.9-clone-wizard-branch-page.png"/>
</p>
<h4 id="Local_Destination">Local Destination</h4>
<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/Egit-0.9-clone-wizard-destination-page.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>
<p>
<br/>
</p>
<h3 id="Pushing_to_other_Repositories">Pushing to other Repositories</h3>
<h4 id="Direct_Push">Direct Push</h4>
<p>The easiest way for pushing is to use
<a href="Tasks.html#Direct_Fetch_and_Push_Support">Direct Push Support</a> on a Push Specification of a Remote.
</p>
<h4 id="Push_Wizard">Push Wizard</h4>
<p>The other way is using the Push Wizard
<br/>
<b>Team > Push...</b>
</p>
<h5 id="Push_URI">Push URI</h5>
<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.9-push-wizard-destination-page.png"/>
</p>
<h5 id="Push_Ref_Specifications">Push Ref Specifications</h5>
<p>Click
<b>Next</b>
<br/>
If this is the first time you connect to this repository via ssh you will have to accept the host key of the remote repository
</p>
<p>
<img border="0" src="images/Egit-0.9-push-wizard-accept-hostkey.png"/>
</p>
<p>If your ssh key is protected by a passphrase (which is recommended) you have to enter it here </p>
<p>
<img border="0" src="images/Egit-0.9-push-wizard-ssh-passphrase.png"/>
</p>
<p>Click
<b>Add all branches spec</b>
</p>
<p>
<img border="0" src="images/Egit-0.9-push-wizard-refspec-allbranches.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>
<h5 id="Delete_Ref_Specifications">Delete Ref Specifications</h5>
<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.9-push-wizard-delete-refspec.png"/>
</p>
<h5 id="Conflicting_Push_Ref_Specifications">Conflicting Push Ref Specifications</h5>
<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.9-push-wizard-refspec-conflict.png"/>
</p>
<h5 id="Push_Confirmation">Push Confirmation</h5>
<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.9-push-wizard-confirm-push.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>
<h5 id="Push_Result_Report">Push Result Report</h5>
<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.9-push-wizard-push-result.png"/>
</p>
<p>In the box at the bottom the push confirmation message from the remote server is displayed.
In case of any errors you will find the error message from the remote server here. To see the message for
a given list entry simply select it in the list.</p>
<p>Click
<b>Ok</b> to close the dialog.
<br/>
<br/>
</p>
<h3 id="Fetching_from_other_Repositories">Fetching from other Repositories</h3>
<h4 id="Direct_Fetch">Direct Fetch</h4>
<p>The easiest way for fetching is to use
<a href="Tasks.html#Direct_Fetch_and_Push_Support">Direct Fetch Support</a> on a Fetch Specification of a Remote.
</p>
<h4 id="Fetch_Wizard">Fetch Wizard</h4>
<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.9-fetch-wizard-source-page.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.9-fetch-wizard-source-url-page.png"/>
</p>
<h5 id="Fetch_Ref_Specifications">Fetch Ref Specifications</h5>
<p>Click
<b>Next</b>
<br/>
Click
<b>Add all branches spec</b>
</p>
<p>
<img border="0" src="images/Egit-0.9-fetch-wizard-refspec.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>
<h5 id="Fetch_Result_Report">Fetch Result Report</h5>
<p>Click
<b>Finish</b>
</p>
<p>
<img border="0" src="images/Egit-0.9-fetch-wizard-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>
<p>
<br/>
</p>
<h3 id="Pulling_New_Changes_from_Upstream_Repositories">Pulling New Changes from Upstream Repositories</h3>
<p>Pull is available since EGit 0.10:</p>
<ul>
<li>click
<b>Team > Pull</b> to pull new changes from the upstream branch your local branch is tracking
</li>
<li>whenever you create a local branch based on a remote tracking branch EGit configures a tracking relationship so that subsequent pulls will fetch and merge the changes from the tracked upstream branch.</li>
<li>
<b>pull --rebase</b> is not yet supported by EGit
</li>
<li>ad-hoc selection of the upstream branch to pull from is not yet supported by EGit</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>
<p>
<br/>
<br/>
</p>
<h2 id="Inspecting_the_state_of_the_Repository">Inspecting the state of the Repository</h2>
<h3 id="Label_Decorations">Label Decorations</h3>
<p>Label decorations show Git specific information on resources under Git version control. They appear in all views showing model objects, like Package Explorer, Project Explorer, Navigator, Hierarchy View. </p>
<p>The Git label decorations can be switched on globally in the Preference Menu (
<b>Window > Preferences</b>) under
<b>General > Appearance > Label Decorations</b>.
</p>
<p>More detailed settings can be done in the Preferences under
<b>Team > Git > Label Decorations</b>.
</p>
<p>There are two different types of label decorations: text decorations and icon decorations. </p>
<h4 id="Text_Decorations">Text Decorations</h4>
<p>Text decorations appear on the left or right side of the text label. They can be configured on the Preferences dialog under
<b>Team > Git > Label Decorations</b> on the tab
<b>Text Decorations</b>. For example, the default for a dirty resource is a <tt>
<b>></b></tt> on the left side of its name.
</p>
<p>These are the default settings: </p>
<p>
<img border="0" src="images/01-TextDecorations.png"/>
</p>
<p>For files and folders there are the variables <tt>"name"</tt>, <tt>"dirty"</tt> and <tt>"staged"</tt>. <tt>"Dirty"</tt> and <tt>"staged"</tt> are flags; if they are true, the text after the colon is displayed.</p>
<p>For projects there are the additional variables <tt>"repository"</tt> and <tt>"branch"</tt>. The <tt>"repository"</tt> variable displays the name of the repository.</p>
<p>The <tt>"branch"</tt> variable displays the name of the currently checked out branch. If no branch is checked out, the decoration shows the shortened name of the commit (first seven characters followed by ellipsis). If tags and/or remote branches are pointing to this commit, a "best guess" heuristic is applied to also show this information: tags take precedence over remote branches, if several tags apply, the newest one is displayed; if there are several remote branches or tags have no modification date, then alphabetic sorting is applied and the last one is shown. Example: the checked out commit <tt>
<b>e49f576...</b></tt> refers to tag <tt>
<b>v.0.7.1</b></tt> of repository <tt>
<b>egit</b></tt>:
<br/>
</p>
<p>
<img border="0" src="images/03-ExampleDecoration.png"/>
</p>
<h4 id="Icon_Decorations">Icon Decorations</h4>
<p>Icon decorations appear on the lower right corner of the icon displayed in front of the label. They can be configured on the Preferences dialog under
<b>Team > Git > Label Decorations</b> on the tab
<b>Icon Decorations</b>.
</p>
<p>These are the default decorations: </p>
<p>
<img border="0" src="images/02-IconDecorations.png"/>
</p>
<ul>
<li>
<b>dirty (folder)</b> - At least one file below the folder is dirty; that means that it has changes in the working tree that are neither in the index nor in the repository.
</li>
<li>
<b>tracked</b> - The resource is known to the Git repository and hence under version control.
</li>
<li>
<b>untracked</b> - The resource is not known to the Git repository and will not be version controlled until it is explicitly added.
</li>
<li>
<b>ignored</b> - The resource is ignored by the Git team provider. The preference settings under
<b>Team > Ignored Resources</b>, "derived" flag and settings from <tt>.gitignore</tt> files are taken into account.
</li>
<li>
<b>dirty</b> - The resource has changes in the working tree that are neither in the index nor in the repository.
</li>
<li>
<b>staged</b> - The resource has changes which have been added to the index. Note that adding changes to the index is currently possible only in the commit dialog via the context menu of a resource.
</li>
<li>
<b>partially-staged</b> - The resource has changes which are added to the index and additional changes in the working tree that neither reached the index nor have been committed to the repository.
</li>
<li>
<b>added</b> - The resource has not yet reached any commit in the repository but has been freshly added to the Git repository in order to be tracked in future.
</li>
<li>
<b>removed</b> - The resource is staged for removal from the Git repository.
</li>
<li>
<b>conflict</b> - A merge conflict exists for the file.
</li>
<li>
<b>assume-valid</b> - The resource has the "assume unchanged" flag. This means that Git stops checking the working tree files for possible modifications, so you need to manually unset the bit to tell Git when you change the working tree file. Also see
<a href="Reference.html#Menu_Actions">Assume unchanged action</a>.
</li>
</ul>
<h3 id="Commit_Dialog">Commit Dialog</h3>
<p>A summary of the status of all modified tracked files is displayed on the commit dialog. By double clicking a file the changes to be committed will be displayed in a compare dialog. As EGit currently always commits the content of the working tree (corresponding to git commit -a on the command line) the compare dialog will compare the working tree with the last commit.
<br/>
<br/>
</p>
<h3 id="Comparing_Content">Comparing Content</h3>
<p>In daily work you will often want to see the changes between your last commit, the index, and the current working tree. </p>
<p>
<img border="0" src="images/03-CompareWith.png"/>
</p>
<p>Currently a compare dialog can only be opened for a single selected file. </p>
<h4 id="Compare_working_tree_with_last_commit">Compare working tree with last commit</h4>
<p>The difference between a file in the current working directory and in the last commit in the current branch can be viewed from the context menu "Compare With" -> "HEAD revision". This feature is also available in the Commit dialog. Double clicking on an entry in the Commit dialog opens a compare dialog. </p>
<h4 id="Comparing_Working_Tree_with_Index">Comparing Working Tree with Index</h4>
<p>The difference between a file in the current working directory and in the index can be viewed from the context menu
<b>Compare With > Git Index</b>.
</p>
<h4 id="Comparing_Working_Tree_with_Any_Commit">Comparing Working Tree with Any Commit</h4>
<ul>
<li>Select a file in the package explorer </li>
<li>from the context menu select
<b>Show in > History</b> or
<b>Compare With > History...</b>
</li>
<li>in the commit graph select a commit </li>
<li>from the context menu select
<b>Compare with working tree</b>
</li>
<li>this will open a compare dialog showing the changes between the selected commit and the current working tree</li>
</ul>
<h4 id="Comparing_Two_Commits_with_Each_Other">Comparing Two Commits with Each Other</h4>
<ul>
<li>Select a file in the package explorer </li>
<li>from the context menu select
<b>Show in > History</b> or
<b>Compare With > History...</b>
</li>
<li>in the commit graph select two commits </li>
<li>from the context menu select
<b>Compare with each other</b>
</li>
<li>this will open a compare dialog showing the changes between the two selected commits</li>
</ul>
<h4 id="Comparing_Index_with_HEAD_or_Any_Other_Commit">Comparing Index with HEAD or Any Other Commit</h4>
<p>This feature is not implemented yet.</p>
<p>
<br/>
</p>
<h3 id="Comparing_with_Branches_.28Synchronize.29">Comparing with Branches (Synchronize)</h3>
<p>The difference between two branches can be viewed from project's context menu
<b>Team > Synchronize</b>. If the git repository contains multiple Eclipse projects it is enough to select one project, the
<b>Synchronization view</b> will include all other projects. It is critical to have all important files/projects imported into Eclipse because the
<b>Synchronization view</b> can only dispatch and show files that are known as a resource in Eclipse any other files will
<b>never</b> appear in the
<b>Synchronization view</b>.
</p>
<p>After launching
<b>Synchronize</b> action the
<b>Synchronization dialog</b> will appear.
</p>
<p>
<img border="0" src="images/Synchronize-dialog.jpg"/>
</p>
<p>Here you can select two branches that should be compared. By checking "include local uncommited changed files" you can include locally made changes and currently staged files in comparison (currently this is not supported by ChangeSet implementation).</p>
<p>It is also possible to compare multiple repositories at once. In this case for each repository the
<b>Synchronize dialog</b> will appear and you could select a different configuration for each repository.
</p>
<h3 id="Quickdiff">Quickdiff</h3>
<p>Instead of using a compare editor you can enable quick diff support and see the changes within the text editor.
<br/>This feature can be enabled via the
<b>General > Editors > Text Editors > Quick Diff</b> preference page:
</p>
<p>
<img border="0" src="images/04-QuickDiffPreferences.png"/>
</p>
<p>The difference annotation will then be displayed on the left hand side of the editor: </p>
<p>
<img border="0" src="images/05-QuickDiffInEditor.png"/>
</p>
<p>If you move your mouse over the annotation you see the content of the version you are comparing to: </p>
<p>
<img border="0" src="images/06-QuickDiffInEditorPopup.png"/>
</p>
<p>Per default, the comparison is against the HEAD. You can determine the version you are comparing to, the so-called quickdiff baseline, from the context menu of a commit in the history view (
<b>Show in > History</b>). There are three menu entries:
</p>
<ul>
<li>
<b>Quick Diff -> Reset baseline to first parent of HEAD</b> - Compare against the first commit before HEAD.
</li>
<li>
<b>Quick Diff -> Reset baseline to HEAD</b> - Compare against HEAD.
</li>
<li>
<b>Quick Diff -> Set as baseline</b> - Compare against the selected commit
</li>
</ul>
<p>
<br/>
</p>
<h3 id="View_Diff_for_a_Commit">View Diff for a Commit</h3>
<p>To display the diff for a given commit </p>
<ul>
<li>from context menu in package explorer select
<b>Team > Show in Resource History</b>
</li>
<li>select the commit you want to inspect </li>
<li>the history view will display the diff in the lower left pane</li>
<li>selecting a file in the lower right pane will scroll to the corresponding file section of the diff</li>
</ul>
<p>
<img border="0" src="images/EGit-0.7-ViewDiffInResourceHistory.png"/>
</p>
<p>
<br/>
</p>
<h2 id="Committing_Changes">Committing Changes</h2>
<p>Modifications to a project under git version control are persisted in the git history through commits. Starting from the state checked out from the git repository modify your project until you have reached a state you are satisfied with and then commit all these changes into the repository as one single commit. Each commit represents a well defined snapshot of all the files stored in the repository. </p>
<h3 id="Modifying_the_content">Modifying the content</h3>
<p>To modify a project which is already shared with Git modify or delete files either within Eclipse or directly in the file system. There is no need to tell Git in advance about these operations. New files which should be version-controlled have to be explicitly put under Git version control :</p>
<ul>
<li>click
<b>Team > Add</b> in the file's context menu
</li>
</ul>
<p>Alternatively you may display untracked files in the Commit dialog and check the
<b>Show untracked Files</b> checkbox to select them for inclusion into the commit.
</p>
<p>Label decorators e.g. in the Package Explorer View show </p>
<ul>
<li>untracked files which are not yet under git version control (marked with "?")</li>
<li>files which have been added (marked with "+") </li>
<li>modified files (marked with ">" in front of the filename)</li>
</ul>
<p>For details see
<a href="Tasks.html#Label_Decorations">Label Decorations</a>.
</p>
<p>Here is an example in the Package Explorer for</p>
<ul>
<li>a committed file</li>
<li>a file modified in the working tree but not yet staged for the next commit</li>
<li>a modified file which modifications have been staged for the next commit</li>
<li>a file which has been newly staged for first-time inclusion with the next commit</li>
<li>a file which is not under git version control </li>
</ul>
<p>
<img border="0" src="images/Egit-0.9-label-decorators.png"/>
</p>
<h3 id="Committing">Committing</h3>
<p>To commit a change click
<b>Team > Commit...</b> in the context menu of a resource in the project.
</p>
<p>Git tracks all changes made to the entire repository capturing the modifications of all version-controlled files in that repository not regarding if these files reside in the same Eclipse project or not. </p>
<p>Once you have triggered the commit the
<b>Commit Dialog</b> will pop-up
</p>
<p>
<img border="0" src="images/Egit-0.9-commit-dialog.png"/>
</p>
<h4 id="Commit_Message">Commit Message</h4>
<p>In the Commit Dialog you specify the commit message describing the change. </p>
<p>It is good practice to start the message with a short first line summarizing the change followed by a blank line and then the message body. In order to ensure that also git command line tools can format these messages nicely the lines shouldn't be formatted too wide (this is indicated by a grey vertical line). The commit message text is checked for errors by the Eclipse spell checker. The spell checker can be configured via the Eclipse
<b>Preferences > General > Editors > Text Editors > Spelling</b>. Click
<b>Ctrl - 1</b> to open quick fixes which may help to fix the spelling errors.
</p>
<p>
<img border="0" src="images/Egit-0.9-commit-dialog-spell-quickfix.png"/>
</p>
<p>
<b>Footer Tags</b>
<br/>
In the last paragraph of the commit message optional footer tags may follow :
</p>
<pre style="width: 40em;">
Bug: 3176
Change-Id: I267b97ecccb5251cec54cec90207e075ab50503e
Reported-by: Joe Developer <joe@dev.org>
Signed-off-by: William Shakespeare <will.from@the.past>
</pre>
<p>The semantics of these tags are project or tool specific</p>
<ul>
<li>If there is an entry in a bug tracking system for the change to be committed it is a good idea to add it here as a bug tag</li>
<li>
<a href="http://code.google.com/p/gerrit/" target="egit_external">Gerrit Code Review</a> uses the
<i>Change-Id:</i> footer to correlate different patchsets of a change evolving during the review process towards the finally accepted patch. To generate a Gerrit Change-Id click
<b>Compute Change-Id for Gerrit Code Review</b>; the ID will be generated on commit, until then a null Change-Id is shown as a placeholder.
</li>
<li>The
<i>Signed-off-by:</i> footer is used by many projects to create a formal track record of declarations that the signing author contributed the changes under the project's license and IP rules. This way the IP provenance of a project's evolving code base can be captured on a technical level. See e.g. the
<a href="http://elinux.org/Developer_Certificate_Of_Origin" target="egit_external">Developer Certificate Of Origin</a> used by the Linux kernel project.
</li>
</ul>
<p>Additionally this dialog controls which of the changes will be included in the commit. If you clear the checkbox in front of a file, the changes to this file will not be included in the commit. The local file in your eclipse workspace will still contain the modifications giving you the chance to commit these changes with a subsequent commit. This feature is often used to separate modifications done to a set of files into different commits. </p>
<p>
<b>One example:</b> Imagine since the last commit you have fixed a bug in A.java and you have added a new method to B.java. These two modifications are logically independent from each other hence you may want to commit them in two independant commits. In this case you initate the commit, deselect B.java from the set of committed files and specify a commit message describing only the bugfix in A.java. After a succesfull first commit you just call commit again and the upcoming dialog will present you the remaining changes in B.java. Now you specify a commit message describing the addition of the method and finish the second commit.
</p>
<p>New files you added to the project which have not been explicitly added to version control (see "Modifying the content") will be listed in the commit dialog if you select the checkbox "Show untracked Files". If you select the checkbox in front of these files in the list they will be added to the repository and committed once you press the commit button. Files which are excluded by the team ignore list or a <tt>.gitignore</tt> file or which are derived (e.g. the bin folder in java projects) will not be shown here. If you have no other changes in your repository than such untracked files the checkbox
<b>Show untracked Files</b> is selected by default.
</p>
<h4 id="Amending_Commits">Amending Commits</h4>
<p>If you recognize that you missed something when committing a change you may fix this : open the commit dialog again and specify that the current commit shall "amend" the previous commit in the current branch. The new commit will then replace the previous one. This feature is often used to correct wrong commits before they are published to other repositories. </p>
<p>
<b>Note:</b> do not amend commits if they have already been published to a shared repository since this may disturb others if they already based their changes on the published change.
</p>
<p>
<b>Amend example:</b>
<br/>Imagine you have committed a change to a file containing a typo
</p>
<p>
<img border="0" src="images/EGit-Typo.png"/>
</p>
<p>After committing the change you detect a typo. In order to correct this typo and the corresponding commit you just fix the typo in the source file </p>
<p>
<img border="0" src="images/EGit-Corrected.png"/>
</p>
<p>then open the Commit Dialog again and select the option
<b>Amend previous commit</b>.
</p>
<p>
<img border="0" src="images/Egit-0.9-commit-dialog-amend.png"/>
</p>
<p>The commit message of your previous commit (the one you want to replace) is filled into the "Commit Message" field. This gives you the chance not only to correct errors in the content of the version-controlled files but to also correct errors (e.g. typos) in the commit message describing your change. </p>
<p>As an alternative to amending you could just commit the corrected version as a subsequent commit. But the first commit containing the typo is of no use to anybody and in order not to clutter the history of your project with unneeded commits you may decide to amend the commit. </p>
<p>Be aware that amending commits which are already published to other repositories may cause trouble. Once you have pushed a commit to a remote repository or your local repository was cloned by somebody else you should be very careful whith amending commits. In this case publishing a second commit which corrects the first one is probably a better solution. Otherwise inform all others that you amended a published commit so that they can react accordingly.</p>
<h2 id="Reverting_Changes">Reverting Changes</h2>
<h3 id="Reverting_changes_in_the_working_tree">Reverting changes in the working tree</h3>
<h4 id="Replace_with_File_in_Git_Index">Replace with File in Git Index</h4>
<p>Changes which are not yet committed and not yet staged can be reverted for a set of selected files.
Select the file(s) in the Package Explorer or an analogous view and click
<b>Replace With > File in Git Index</b>.
</p>
<h4 id="Replace_with_HEAD">Replace with HEAD</h4>
<p>This feature is currently not available on single file level. You can use
<b>Reset to</b> with option
<b>hard</b> to forcefully reset the entire working tree of your repository back to the state of the HEAD commit (See "Resetting your current HEAD" below). This operation will revert all changes in the working tree and the index. You can't do it on a selected set of files using EGit yet.
</p>
<h3 id="Resetting_your_current_HEAD">Resetting your current HEAD</h3>
<p>Git offers the possibility to reset the HEAD of the current branch to any other commit. It optionally resets the index and the working tree to match that commit. Note that this action affects all files and folders in the enitre repository.</p>
<p>You have the option to do a hard reset, a mixed reset and a soft reset.</p>
<ul>
<li>
<b>soft</b> - the HEAD points now to the new commit, the index and the working tree are unchanged
</li>
<li>
<b>mixed</b> - the HEAD points now to the new commit, the index is updated, the working tree is unchanged
</li>
<li>
<b>hard</b> - the HEAD points now to the new commit, the index and the working tree are updated
</li>
</ul>
<h4 id="Reset_to_specific_branch_or_tag">Reset to specific branch or tag</h4>
<p>Select
<b>Team -> Reset...</b> on a project. This opens a dialog where you can select a branch or a tag.
</p>
<h4 id="Reset_to_a_specific_commit">Reset to a specific commit</h4>
<p>Select a commit in the History view and open the context menu. Here you find the entries
<b>Hard reset</b>,
<b>Mixed reset</b> and
<b>Soft reset</b>.
</p>
<h4 id="Revert_all_local_and_staged_changes">Revert all local and staged changes</h4>
<p>This can be done as a special case of reset. If you reset to the current HEAD (normally the last commit on your branch) with the option
<b>hard</b> you overwrite the working tree and the index with the content of the HEAD. You can do this in three ways:
</p>
<ul>
<li>Select
<b>Team > Reset...</b> on a project. In the dialog select HEAD or your current branch and switch the radio button to
<b>hard</b>.
</li>
<li>Right click and select
<b>Reset...</b> on any branch or tag in the Repositories view. This opens a dialog which lets you decide on the reset type. Choose
<b>hard</b> here.
</li>
<li>Open the context menu on the HEAD commit in the history view and select
<b>Hard Reset</b>.
</li>
</ul>
<p>
<br/>
</p>
<h2 id="Branching">Branching</h2>
<h3 id="Branching_in_the_Repositories_View">Branching in the Repositories View</h3>
<p>The Repositories View
<a href="Tasks.html#Branch_and_Tag_Support">supports</a> the following branching actions:
</p>
<ul>
<li>
<a href="Tasks.html#Check-out_of_Branches_and_Tags">Checkout branches</a>
</li>
<li>
<a href="Tasks.html#Creation_and_Deletion_of_Branches">Creation and deletion of branches</a>
</li>
<li>
<a href="Tasks.html#Determining_the_Checked-out_Branch">Determining the checked out branch</a>
</li>
</ul>
<h3 id="Branching_Dialog">Branching Dialog</h3>
<p>To open the branching dialog click
<br/>
<b>Team > Branch...</b>
</p>
<p>
<img border="0" src="images/Egit-0.8-branch-dialog.png"/>
</p>
<h4 id="Creating_a_New_Local_Branch">Creating a New Local Branch</h4>
<ul>
<li>Select the branch your new branch should be based on</li>
<li>Click
<b>New Branch</b>
</li>
<li>Enter the branch name and click
<b>OK</b>
</li>
</ul>
<p>
<b>Note:</b> If you create a local branch based on a remote tracking branch a tracking relationship will be configured automatically. When this local branch is checked out a subsequent
<b>Pull</b> operation will pull new changes into the local branch from the remote tracking branch configured to be tracked by this local branch. You may view and edit this configuration in the
<a href="Tasks.html#Repository_Configuration">repository configuration</a>.
</p>
<h4 id="Renaming_an_Existing_Branch">Renaming an Existing Branch</h4>
<ul>
<li>Select the branch you want to rename</li>
<li>Click
<b>Rename</b>
</li>
<li>Enter the new branch name and click
<b>OK</b>
</li>
</ul>
<h4 id="Checking_out_a_Branch">Checking out a Branch</h4>
<ul>
<li>Select the branch you want to check out</li>
<li>Click
<b>Checkout</b>
</li>
</ul>
<p>
<br/>
</p>
<h3 id="Branching_in_the_History_View">Branching in the History View</h3>
<p>In history view a new branch can be created based on a given commit: select a commit in the history view and execute
<b>Create Branch...</b> on the context menu. A dialog for branch creation appears:
</p>
<p>
<img border="0" src="images/CreateBranch.png"/>
</p>
<p>
<br/>
</p>
<h2 id="Merging">Merging</h2>
<p>A merge incorporates changes from named commits (since the time their histories diverged from the current branch) into the current branch. </p>
<h3 id="Merging_a_branch_or_a_tag_into_the_current_branch">Merging a branch or a tag into the current branch</h3>
<p>You have two places where you can trigger the merge:</p>
<ul>
<li>from the team menu</li>
<li>from the Git Repositories View</li>
</ul>
<h4 id="Starting_merge_from_the_team_menu">Starting merge from the team menu</h4>
<p>In the Package Explorer or Navigator, open the context menu on a project node.
Select
<b>Team > Merge...</b>
</p>
<p>Now the merge dialog opens:</p>
<p>
<img border="0" src="images/MergeDialog.png"/>
</p>
<p>On the dialog, select a branch or a tag you want to merge with your current branch. </p>
<h4 id="Starting_merge_from_the_Git_Repositories_View">Starting merge from the Git Repositories View</h4>
<p>You can trigger a merge from any branch and tag node and from the repository node if you have checked out a local branch. See
<a href="Tasks.html#Merging_a_Branch_or_a_Tag">Merging a Branch or a Tag</a> for further details.
</p>
<h4 id="Possible_merge_results">Possible merge results</h4>
<p>After pressing the Merge button, the following scenarios can occur:</p>
<ul>
<li>
<i>Already up to date</i>: Your current branch points to a commit that has the selected branch or tag as predecessor. In this case nothing is changed.
</li>
<li>
<i>Fast-forward</i>: Your current branch points to a commit that is a predecessor of the selected branch or tag. In this case your branch is moved and points to the selected branch or tag; this new HEAD is checked out to the working tree. Fast-forward is very common when working with remote repositories: When a remote tracking branch is updated, the merge with the corresponding branch generally is a fast-forward. You can perform a pull by fetching the remote branch (e.g. origin/master) and merging it into the corresponding local branch (e.g. master).
</li>
<li>
<i>Real merge</i>: When neither of the conditions above apply egit triggers a merge of the commits. There are two possible outcomes: If no conflicts occur the current branch will point to a newly created merge commit; if conflicts occur the conflicting files will be marked with label decorators (see
<a href="Tasks.html#Resolving_a_merge_conflict">Resolving a merge conflict</a> for further actions in case of merge conflicts).
</li>
</ul>
<h5 id="Merge_Result_dialog">Merge Result dialog</h5>
<p>The result of a merge is summarized in a dialog:</p>
<p>
<img border="0" src="images/MergeResultMerged.png"/>
</p>
<p>On the first line you see the result of the merge. The possible results are "Already-up-to-date", "Fast-forward", "Merged", "Conflicting" or "Failed". A possible reason for "Failed" may be that there are conflicting changes in the working directory.</p>
<p>On the second line you see the new HEAD commit in case of a successful merge (Already-up-to-date, Fast-forward or Merged).</p>
<p>In the table you see the commits which were merged.</p>
<h3 id="Resolving_a_merge_conflict">Resolving a merge conflict</h3>
<p>A merge can result in conflicts which require user action. This is the case when the content of files cannot be merged automatically. These conflicts are marked with a label decoration in the navigation tree. The merge conflicts in the content of files are presented with textual conflict markers (see
<a href="http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented" target="egit_external">http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented</a> for more details).
</p>
<p>
<img border="0" src="images/Egit-0.10-merge-conflict.png"/>
</p>
<h4 id="Using_Merge_Tool">Using Merge Tool</h4>
<ul>
<li>select the top level resource showing the red conflict label decorator</li>
<li>click
<b>Team > Merge Tool</b>
</li>
<li>select the merge mode
<i>Use HEAD (the last local version) of conflicting files" and click '''OK</i>'
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.10-select-merge-mode.png"/>
</p>
<ul>
<li>the merge editor opens showing the working tree version in the left pane and the version to be merged in the right pane</li>
</ul>
<p>
<img border="0" src="images/Egit-0.10-merge-tool.png"/>
</p>
<ul>
<li>edit the working tree version until you are happy with it</li>
<li>
<b>Team > Add</b> the merged resource to mark the conflict as resolved
</li>
<li>commit the merge commit via
<b>Team > Commit</b>
</li>
</ul>
<h4 id="Manual_conflict_resolution">Manual conflict resolution</h4>
<p>To resolve a conflict you have to do the following steps:</p>
<ul>
<li>Navigate to the conflicting resource</li>
<li>Edit the content of the conflicting resource</li>
<li>Tell EGit that the conflict is resolved with
<b>Team > Add</b>
</li>
<li>Commit the conflict resolution with
<b>Team > Commit</b>
</li>
</ul>
<h4 id="Finding_conflicting_files">Finding conflicting files</h4>
<p>A repository which contains conflicting files has the textual label decorator "|Conflicts" attached to the repository name. Conflicting resources and folders containing such conflicting resources get a conflict label decoration.</p>
<p>
<img border="0" src="images/Conflicts.png"/>
</p>
<h4 id="Editing_conflicting_files">Editing conflicting files</h4>
<p>In the file content, the area where a pair of conflicting changes happened is marked with markers <<<<<<<, =======, and >>>>>>>. The part before the ======= is typically your side, and the part afterwards is typically their side (see
<a href="http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented" target="egit_external">http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented</a> for more details).
</p>
<p>Open the file in an editor, edit the content and save the editor.</p>
<p>Note that this step is not mandatory. EGit does not check the content to decide if a conflict is resolved. The next step is the relevant one.</p>
<h4 id="Adding_conflict_resolution_to_the_git_index">Adding conflict resolution to the git index</h4>
<p>Once you are finished with editing a file select
<b>Team > Add</b> to add the conflict resolution to the git index. You can do it on a folder or the whole project to resolve all conflicts at once.
</p>
<p>When you have resolved all conflicts the textual repository label decoration changes to "Merged". There are no conflict markers anymore.</p>
<p>
<img border="0" src="images/ResolvedConflicts.png"/>
</p>
<h4 id="Committing_a_merge">Committing a merge</h4>
<p>When the repository is in state "Merged" (as is indicated with the textual label decorator "|Conflicts" attached to the repository name) the merge can finally be committed.</p>
<p>Select
<b>Team > Commit...</b> anywhere in the navigation tree. The commit dialog opens with a slightly different look compared to a normal commit:
</p>
<ul>
<li>The Commit message area is prefilled with a standard merge commit message.</li>
<li>It is not possible to amend a previous commit.</li>
<li>It is not possible to add untracked files.</li>
<li>it is not possible to uncheck the checkboxes. This guarantees that all resolved conflicts are committed.</li>
</ul>
<p>After pressing the "Commit" Button the merge is completed.</p>
<h3 id="Aborting_Merge">Aborting Merge</h3>
<p>If a merge resulted in conflicts you can abort the merge with a hard reset to the current branch. This can be done in state "Conflicts" and in state "Merged", i.e. before and after you have resolved the conflicts. </p>
<p>The hard reset can be done from the team menu, the Git Repositories View or the History View. See [
<a href="Tasks.html#Revert_all_local_and_staged_changes">Revert all local and staged changes</a> for more details.
</p>
<p>
<br/>
</p>
<h2 id="Rebasing">Rebasing</h2>
<h3 id="Rebase_Introduction">Rebase Introduction</h3>
<p>Rebase applies a chain of commits onto a given commit. A typical scenario is the development of some feature on a "topic" branch which was created from a "master" branch at some point in time. When "master" is updated with changes e.g. from other developers while "topic" is still under development, it may become necessary to incorporate these changes into "topic".
<br/>
</p>
<p>Let's assume we start development on "topic" by creating the "topic" branch from master. At this point, both "master" and "topic" point to commit "E". When the first commit ("A") is added to "topic", the commit history of the repository looks like this:
<br/>
</p>
<pre> A topic
/
D---E master
</pre>
<p>
Now, let's assume that there were some more commits on "topic" and as well some more commits on "master" (for example, "master" may track some remote repository and there were some changes in that remote repository that have been pulled into "master"):
<br/>
</p>
<pre> A---B---C topic
/
D---E---F---G master
</pre>
<p>
Now, in order to incorporate the changes in "master" into "topic", a Rebase of "topic" onto "master" would produce
<br/>
</p>
<pre> A'--B'--C' topic
/
D---E---F---G master
</pre>
<p>
<br/> Technically, the sequence of commits that are contained in "topic" but not in "master" are applied (that is, cherry-picked) on top of "master" one by one.
<br/>
</p>
<p>Note that the commits A, B, C are neither lost nor changed, instead a new chain of commits A', B', C' with the same changes and commit messages as the original commits (but different commit IDs) will be created. The old commits A, B, C are still around in the object database but not visible anymore as they are no longer reachable from any branch. A', B', C' are different from the old ones as they now also contain changes F and G.</p>
<h3 id="Rebase.2C_A_Simple_Example">Rebase, A Simple Example</h3>
<p>Let's have a look at some simple example: we have a text file "FamousWords.txt" which initially might have some content like </p>
<pre>Chapter 1
Once upon a time...
Chapter 2
To be or not to be
</pre>
<p>
Now, in "topic", two commits are created, the first one adding a French translation to Chapter 2, and another one adding a German translation: </p>
<p>After first change in "topic":
<br/>
</p>
<pre>Chapter 1
Once upon a time...
Chapter 2
To be or not to be
Ètre ou non ètre pas
</pre>
<p>
After second change in "topic":
<br/>
</p>
<pre>Chapter 1
Once upon a time...
Chapter 2
To be or not to be
Ètre ou non ètre pas
Sein oder nicht sein
</pre>
<p>
At the same time, the file was changed in "master" by adding two commits adding French and German translations to Chapter 1:
<br/>
</p>
<pre>Chapter 1
Once upon a time...
Il était une fois
Es war einmal
Chapter 2
To be or not to be
</pre>
<p>
The commit history looks like this: </p>
<p>
<img border="0" src="images/EGit-0.10-MergeDemoHistory.png"/>
</p>
<p>Now, if "topic" is rebased onto "master", the two changes in topic are applied in the same sequence as they were applied during the evolution of "topic". </p>
<p>The result is a merged version of "FamousWords.txt":
<br/>
</p>
<pre>Chapter 1
Once upon a time...
Il était une fois
Es war einmal
Chapter 2
To be or not to be
Ètre ou non ètre pas
Sein oder nicht sein
</pre>
<p>and a commit history with the commit history of "topic" on top of the current "master":
<br/>
</p>
<p>
<img border="0" src="images/EGit-0.10-MergeDemoHistoryAfterRebase.png"/>
</p>
<h3 id="The_Real_World:_Rebase_Conflicts">The Real World: Rebase Conflicts</h3>
<p>Up to now, we have assumed that the changes in "topic" can be auto-merged into "master". In the real world, however, it may happend that you encounter conflicts during rebase. Now, if a commit that is to be cherry-picked contains changes that conflict with changes in "master", the rebase operation is interrupted after applying the conflicting change; the conflicts are visualized in the usual way (with conflict markers) and the user gets a chance to decide whether to</p>
<ul>
<li>resolve these conflicts manually,</li>
<li>skip the current commit, or </li>
<li>abort the rebase completely</li>
</ul>
<p>If
<b>Resolve Conflicts</b> is chosen, and the conflicts have been resolved manually, the changes must be "Added", and then rebase can be resumed, i.e. the next commit in the chain will be applied.
</p>
<p>If
<b>Skip</b> was chosen, the conflicting changes will be reverted and the next commit in the chain will be applied.
</p>
<p>If
<b>Abort</b> was chosen, the rebase operation will be completely rolled back, returning the Repository into its original state before the rebase was started.
This process is repeated until the last commit was applied successfully or skipped. Finally, the "topic" branch will be changed to point to the last commit.
</p>
<p>To understand "Skip" better, let's look back to the introduction above. If we assume that commit "B" causes some conflicts with the current "master", the user might decide to simply skip "B"; the new commit history after the rebase would then look like this:</p>
<pre> A'--C' topic
/
D---E---F---G master
</pre>
<h3 id="Starting_Rebase">Starting Rebase</h3>
<p>Rebase is available in the Git Repositories View. On Repository nodes,
<b>Rebase...</b> opens a dialog asking the user to select a branch that is not checked out; the currently checked out branch will then be rebased onto the selected branch. On "Branch" nodes (both Local and Remote Tracking branches, but not on the currently checked out branch),
<b>Rebase</b> immediately rebases the currently checked out branch onto the selected branch:
</p>
<p>
<img border="0" src="images/EGit-0.10-StartRebaseFromRepoView.png"/>
</p>
<h3 id="Rebase_Confirmation_Dialog">Rebase Confirmation Dialog</h3>
<p>If Rebase was successful, a confirmation dialog will be displayed; this dialog can be suppressed by ticking a checkbox; a preference on the Git preference page allows to make the dialogs appear again. If the dialog is suppressed, an "Information" message is written to the Eclipse log instead.</p>
<h3 id="Rebase_Conflicts">Rebase Conflicts</h3>
<p>If a conflict occurs during rebase, a dialog is shown giving some information about the commit that caused the conflict. By selecting a radio button, you can decide whether to</p>
<ul>
<li>Start the Merge Tool to resolve the conflicts manually</li>
<li>Skip the current commit</li>
<li>Abort the rebase altogether</li>
<li>Do nothing (return to the workbench), this is equivalent to hitting "Escape":</li>
</ul>
<p>
<img border="0" src="images/EGit-0.10-RebaseConflictDialog.png"/>
</p>
<p>Unless "Skip" or "Abort" was chosen in the dialog, the conflicts must be resolved manually by editing the conflicting files. When done with editing, the files must be declared as being resolved by "Adding" them to the index.</p>
<p>After all conflicts have been resolved, Rebase can be resumed by right-clicking on the Repository node in the Git Repositories View and selecting Rebase > Continue.</p>
<p>The "Skip" and "Abort" options are also available from the Git Repositories View by right-clicking on the Repository node and selecting Rebase > Skip and Rebase > Abort, respectively.</p>
<p>The Merge Tool can also be started from the corresponding entry in the Team menu.</p>
<h3 id="Aborting_Rebase">Aborting Rebase</h3>
<p>As long as the Repository is in "Rebasing" state, the user can always abort the rebase in the Git Repositories View using the menu action "Rebase > Abort" which is available on the Repository node.</p>
<h3 id="Rebase_Limitation">Rebase Limitation</h3>
<p>In EGit 0.10 rebase is not yet able to handle all possible version graphs. If the graph is too complicated rebase will abort with an error message. As a workaround until these more complex graphs are also supported by EGit's rebase you may instead use native git from the command line.</p>
<h2 id="Cherry_Picking">Cherry Picking</h2>
<h3 id="Cherry-pick_Introduction">Cherry-pick Introduction</h3>
<p>A given commit
<i>C'' on branch ''stable-1.0</i> contains a set of changes you would like to integrate in your current development on branch
<i>master</i>.
</p>
<pre> A--B--C--D stable-1.0
/
D---E---F---G master HEAD
</pre>
<p>Cherry-pick the commit
<i>C'' to create a new commit ''C' '' on top of the head commit of the currently checked out branch ''master</i>.
<i>C' '' will then contain the changes performed in ''C</i> applied onto the HEAD of the currently checked out branch
<i>master</i>.
</p>
<pre> A--B--C--D stable-1.0
/
D---E---F---G--C' master HEAD
</pre>
<h3 id="Cherry-pick_Example">Cherry-pick Example</h3>
<p>You are currently working on branch "feature2" (HEAD). There is a commit "feature 1" in another branch.
<br/>
You want to integrate the changes performed by commit "feature 1" into your current development on branch "feature 2".
</p>
<ul>
<li>In the History View select commit "feature 1" and click
<b>Cherry-pick</b>:
</li>
</ul>
<p>
<img border="0" src="images/CherryPick1.png"/>
</p>
<ul>
<li>As result you get a new commit "feature 1" at the tip of your current branch "feature" containing the changes of "feature 1":</li>
</ul>
<p>
<img border="0" src="images/CherryPick2.png"/>
</p>
<ul>
<li>Cherry-picking can encounter conflicts. In this case conflict markers are rendered into the affected sources:</li>
</ul>
<p>
<img border="0" src="images/CherryPick3.png"/>
</p>
<ul>
<li>Resolve the conflicts by editing the corresponding sources as described in
<a href="Tasks.html#Resolving_a_merge_conflict">Resolving a merge conflict</a>
</li>
<li>
<b>Team > Add</b> the files you edited to mark the conflicts resolved
</li>
<li>Commit the changes using
<b>Team > Commit</b>
</li>
</ul>
<p>
<br/>
</p>
<h2 id="Tagging">Tagging</h2>
<h3 id="Creating_a_Tag">Creating a Tag</h3>
<ul>
<li>Select
<b>Team > Tag...</b> from the project context menu.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.8-tag-create.png"/>
</p>
<ul>
<li>Enter the tag name</li>
<li>Enter the tag message</li>
<li>Optionally select the commit you want to tag (default is HEAD)</li>
<li>Click
<b>OK</b> to create the annotated tag
</li>
</ul>
<p>Tags can also be created in the history view: select a commit and execute
<b>Create Tag...</b> in the context menu. The tag will be created on the selected commit:
</p>
<p>
<img border="0" src="images/TagCreation.png"/>
</p>
<h3 id="Replacing_an_Existing_Tag">Replacing an Existing Tag</h3>
<p>What to do if you tagged the wrong commit or ended up with some sort of typo ?</p>
<ul>
<li>If you didn't yet push this out just replace the tag and you are done.</li>
<li>
<b>If it's already published you shouldn't replace the tag</b> but use a new name since otherwise you have to tell everybody who got the old tag to replace it manually with your updated one. This is because, Git does not (and it should not) change tags behind users back. So if somebody already got the old tag, doing a git pull on your tree shouldn't just make them overwrite the old one.
</li>
</ul>
<p>So if your old tag wasn't yet pushed you may correct it in the following way :</p>
<ul>
<li>Select
<b>Team > Tag...</b> from the project context menu.
</li>
</ul>
<p>
<img border="0" src="images/Egit-0.8-tag-replace.png"/>
</p>
<ul>
<li>Select the tag you want to replace from the list of existing tags</li>
<li>or start typing any part of the tag you look for into the Tag Name field, this will filter the list of existing tags to those tags which contain the string you are typing, then select the tag you want to replace</li>
<li>Mark the checkbox
<b>Force replace existing tag</b>
</li>
<li>Change the tag and press
<b>OK</b>
</li>
</ul>
<h3 id="Light-weight_and_Signed_Tags">Light-weight and Signed Tags</h3>
<p>Light-weight and signed tags are not yet supported by EGit, use command line <tt>
<b>git tag</b></tt> or <tt>
<b>git tag -s</b></tt> instead.
</p>
<p>
<br/>
</p>
<h2 id="Patches">Patches</h2>
<h3 id="Creating_Patches">Creating Patches</h3>
<p>"A patch is a piece of software designed to fix problems with, or update a computer program or its supporting data" (
<a href="http://en.wikipedia.org/wiki/Patch_(software)" target="egit_external">wikipedia</a>). A patch file contains a description of changes of a set of resources which can be automatically applied to another eclipse workspace or git repository.
</p>
<p>The patch formats used by eclipse (
<b>Team > Apply Patch</b>) and by git (<tt>
<b>git apply</b></tt> or <tt>
<b>git am</b></tt> on the command line) are different. It is possible to create both types of a patch in EGit.
</p>
<h4 id="Create_a_Patch_from_a_Commit">Create a Patch from a Commit</h4>
<p>This is the most common use case for a distributed versioning system. A developer commits a change on a local feature or bugfix branch and wants to export this change into a patch file.</p>
<p>It can be done from the history view:</p>
<p>
<img border="0" src="images/Egit-0.0-create-patch-menu.png"/>
</p>
<p>The patch file will contain the difference between the commit and its parent in the history view. Note that the filter of the history view applies also for patch creation.</p>
<h4 id="Patch_Wizard">Patch Wizard</h4>
<p>The Wizard consists of two pages. Page one lets you select the location of the patch:</p>
<p>
<img border="0" src="images/Egit-0.0-create-patch-dialog.png"/>
</p>
<p>The name of the patch file is created from the first line of the commit message.</p>
<p>On the second page you can change the patch format. </p>
<p>Currently there is one check box:
<b>Export in git patch format</b>.
</p>
<ul>
<li>If you do not check it (this is the default) the patch can be applied with the eclipse
<b>Apply Patch...</b> wizard. The paths are relative to the eclipse projects and do not contain prefixes (like <tt>
<b>git format-patch --no-prefix</b></tt> on the git command line).
</li>
<li>If you check it the patch will look like the result of <tt>
<b>git format-patch --no-stat</b></tt> on the git command line.
</li>
</ul>
<h3 id="Applying_Patches">Applying Patches</h3>
<p>Currently it s not possible to apply patches in git format. It is possible to apply patches using the standard eclipse format using
<b>Team > Apply Patch...</b>.
</p>
<p>
<br/>
</p>
<h2 id="Managing_Repositories">Managing Repositories</h2>
<p>The "Git Repositories View" is the primary UI element to facilitate working with multiple Repositories simultaneously (i.e. within one Eclipse Workspace).</p>
<p>This view can be opened using the menu path
<br/>
<b>Windows > Show View > Other... > Git > Git Repositories</b>
</p>
<p>It is also part of the "Git Repository Exploring" perspective available using menu path
<br/>
<b>Window > Open Perspective > Other... > Git Repository Exploring</b>
</p>
<p>If you already have projects in your workspace which are shared with a Git Repository, you can use
<br/>
<b>Show In... > Git Repositories</b> or
<b>Team > Show in Repositories View</b>
</p>
<p>on any resource to open the view.</p>
<h3 id="Adding_Repositories_to_the_Git_Repositories_View">Adding Repositories to the Git Repositories View</h3>
<p>Initially, the Git Repositories View is empty. In order to add Repositories to it, there are several options:</p>
<ol>
<li>Adding a Repository from the Local File System manually</li>
<li>Cloning a Repository and having the cloned Repository added to the view automatically</li>
<li>Creating a Repository on the Local File System</li>
<li>Adding a Repository by pasting a Git Repository path to the view</li>
</ol>
<h4 id="Adding_a_Repository_manually">Adding a Repository manually</h4>
<p>You can add a Repository from your local file system to the Git Repositories View without cloning it. This can be helpful if you are setting up a new Eclipse workspace and want to re-use your Git Repositories. Use the
<b>Add an existing Git Repository</b> button from the view's toolbar:
</p>
<p>
<img border="0" src="images/RepoMgrAddRepositoryIcon.png"/>
</p>
<p>A dialog will appear prompting you for a directory of your local file system. After selecting the correct directory, you can hit the
<b>Search</b> button to see a list of Git Repositories in this directory. You can then select some or all found Repositories and add them to the view using
<b>OK</b>:
</p>
<p>
<img border="0" src="images/RepoMgrSearchDialog.png"/>
</p>
<h4 id="Cloning_a_Repository_2">Cloning a Repository</h4>
<p>In order to clone a Repository, refer to
<a href="Tasks.html#Cloning_a_Repository">Cloning remote Repositories</a>. After a successful clone operation, the newly cloned Repository should appear in the Git Repositories View automatically.
</p>
<p>You can also use the
<b>Clone a Git Repository</b> button from the view's toolbar to start the Clone wizard:
</p>
<p>
<img border="0" src="images/RepoMgrCloneRepositoryIcon.png"/>
</p>
<p>Please refer to
<a href="Tasks.html#Cloning_a_Repository">Cloning remote Repositories</a> about how to use the wizard.
</p>
<h4 id="Creating_a_Repository">Creating a Repository</h4>
<p>You can create a new, empty repository on the local file system. This is useful if you later on want to create one or more new projects below this repository. Another usecase is to create a new bare repository where you can push to. Use the
<b>Create a new Git Repository</b> button from the view's toolbar:
</p>
<p>
<img border="0" src="images/RepoMgrCreateRepositoryIcon.png"/>
</p>
<p>A dialog will appear which lets you choose a directory:</p>
<p>
<img border="0" src="images/RepoMgrCreateRepositoryDialog.png"/>
</p>
<p>If you select the checkbox
<b>Create as Bare Repository</b> the new repository will not have a working directory. You then can only add content by pushing changes from another repository.
</p>
<h4 id="Adding_a_Repository_using_Copy_and_Paste">Adding a Repository using Copy and Paste</h4>
<p>As a shortcut, it is also possible to paste the local file system path of a Git repository from the clipboard into this view. In order to do so, copy the path of a Git repository (the full path of its <code>.git</code> folder) to the clipboard, then open the context menu on the view panel:</p>
<p>
<img border="0" src="images/RepoMgrPasteRepositoryPath.png"/>
</p>
<p>or click
<b>Edit > Paste</b> from the main menu (or the corresponding keyboard shortcut). If the clipboard content is not suitable, an error popup will be displayed, otherwise the added Repository should appear automatically.
</p>
<p>After the view has been populated with some repositories, it should look like this:</p>
<p>
<img border="0" src="images/RepoMgrViewWithRepos.png"/>
</p>
<h3 id="Removing_Repositories">Removing Repositories</h3>
<h4 id="Removing_a_Repository_from_the_Repositories_View">Removing a Repository from the Repositories View</h4>
<p>In order to remove a repository from the Repositories View select a repository and click "Remove Repository" </p>
<p>
<img border="0" src="images/Egit-0.10-RemoveRepository.png"/>
</p>
<h4 id="Deleting_a_Repository">Deleting a Repository</h4>
<p>In order to delete a repository, select it in the Repositories View and click "Delete Repository".</p>
<p>
<img border="0" src="images/Egit-0.10-DeleteRepository.png"/>
</p>
<p>Then confirm that you want to delete the repository</p>
<p>
<img border="0" src="images/Egit-0.10-ConfirmRepositoryDeletion.png"/>
</p>
<p>and decide if you want to delete projects contained in the repository from the Eclipse workspace.</p>
<p>
<img border="0" src="images/Egit-0.10-ConfirmProjectRemoval.png"/>
</p>
<p>
<br/>
</p>
<h3 id="Structure_of_the_Git_Repositories_View">Structure of the Git Repositories View</h3>
<p>The following screenshot shows the topmost two levels of the Git Repositories View:</p>
<p>
<img border="0" src="images/RepoMgrTopLevelNodes.png"/>
</p>
<p>The root node represents the Repository itself. The node text indicates the name of the Repository and its location in the local file system. The "Branches" and "Tags" nodes allow browsing and manipulation of tags and branches. The "Symbolic References" node lists other references which are not branches or tags, most notably the "HEAD" symbolic reference.</p>
<p>The "Working directory" node displays the location and structure of the working directory on the local file system (only in case of a development, or non-bare Repository, for bare Repositories, this node is always a leaf).</p>
<p>Finally, the "Remotes" node allows browsing and manipulating the remote configurations used for Fetch and Push.</p>
<h3 id="Functions_of_the_Git_Repositories_View">Functions of the Git Repositories View</h3>
<h4 id="Project_Import">Project Import</h4>
<p>In order to work with the contents of a Git Repository, its files and folders must be imported into the Eclipse workspace in the form of projects. While the Git Clone wizard allows to do such imports directly after cloning, the Git Repositories View allows to trigger project imports independently of the clone operation.</p>
<p>The "Import Projects..." context menu is available on the "Repository" node as well as on any "Folder" node within the "Working Directory" node and the "Working Directory" node itself:</p>
<p>
<img border="0" src="images/RepoMgrImportNodes.png"/>
</p>
<p>The rationale for offering the
<b>Import Projects...</b> action on several nodes is that some of the wizards used for importing projects can take the file system directory into account, for example the
<b>Import Existing Projects</b> wizard. If the import is started from the "Repository" or the "Working Directory" node, the working directory of the repository is set as context, otherwise the directory corresponding to the currently selected "Folder" node.
</p>
<p>The details of project import are discussed in
<a href="Tasks.html#Use_the_New_Projects_Wizard">Use the New Projects Wizard</a>.
</p>
<h4 id="Branch_and_Tag_Support">Branch and Tag Support</h4>
<p>The "Branches" node allows to create, browse, checkout and delete local and remote branches. The "Tags" node allows for browsing and checking out of tags. Both the "Branches" node and the "Tags" node allow for merging the branch or tag into the currently checked out branch and also for synchronizing with the currently checked out branch.</p>
<p>For better readability, branches are organized in two sub-nodes for local and remote branches, respectively, and only the shortened names are displayed, e.g. instead of <tt>"refs/heads/master"</tt> you would find an entry <tt>"master"</tt> under the "Local Branches" node, instead of <tt>"refs/remotes/origin/master"</tt> the shortened name <tt>"origin/master"</tt> is displayed under the "Remote Branches" node. Similarly, tag names are shortened by omitting the <tt>"refs/tags/"</tt> prefix:</p>
<p>
<img border="0" src="images/RepoMgrBranchesAndTags.png"/>
</p>
<h5 id="Check-out_of_Branches_and_Tags">Check-out of Branches and Tags</h5>
<p>Branches and tags can be checked out by either double-clicking on the respective node or by selecting the corresponding context menu entry.</p>
<h5 id="Creation_and_Deletion_of_Branches">Creation and Deletion of Branches</h5>
<p>Local branches can be created using a simple wizard. After selecting the corresponding context menu entry (available on the "Branches", the "Local Branches", and on any "Branch" and "Tag" node), you are asked to enter a source branch and a name for the new branch. Depending on whether you have called the wizard from a "Branch" or "Tag" node or not, the source branch drop-down will be pre-selected with either the selected branch, the selected tag or the currently checked-out branch:</p>
<p>
<img border="0" src="images/RepoMgrCreateBranch.png"/>
</p>
<p>You can change the source branch using the drop-down. By default, the newly created branch will be checked out after creation. Deselect the corresponding checkbox on the wizard if you don't want this to happen.</p>
<p>Branch deletion is done using the corresponding context menu entry.</p>
<h5 id="Merging_a_Branch_or_a_Tag">Merging a Branch or a Tag</h5>
<p>You can trigger a merge from any branch and tag node and from the repository node if you have checked out a local branch. See
<a href="Tasks.html#Merging">Merging</a> for further details of the merging features.
</p>
<ul>
<li>When you select any branch node other than the currently checked out branch or any tag node, use
<b>Merge</b> to directly trigger a merge into the currently checked out branch.
</li>
</ul>
<ul>
<li>When you select the repository node or the currently checked out branch, use
<b>Merge...</b> to open the merge dialog. The merge dialog is described at
<a href="Tasks.html#Merging_a_branch_or_a_tag_into_the_current_branch">Merging a branch or a tag into the current branch</a>.
</li>
</ul>
<h5 id="Synchronizing_with_a_Branch_or_a_Tag">Synchronizing with a Branch or a Tag</h5>
<p>You can perform a comparison of the changes in your HEAD with the changes done in any other branch or tag. Right click and select
<b>Synchronize...</b> on any branch or tag. Then the eclipse synchronize view opens which contains a representation of the changes that are contained in your HEAD but not on the other branch or tag (outgoing change) or vice versa (incoming change). Please refer to the documentation of the synchronize feature for further details.
</p>
<h5 id="Determining_the_Checked-out_Branch">Determining the Checked-out Branch</h5>
<p>There are two ways to determine which branch or tag is currently checked out: the checked out branch/tag node is decorated with a little check mark and the "HEAD" entry under the "Symbolic References" node shows the (full) name of the checked out branch:</p>
<p>
<img border="0" src="images/RepoMgrCheckedOutBranch.png"/>
</p>
<h5 id="Resetting_to_a_Branch_or_a_Tag">Resetting to a Branch or a Tag</h5>
<p>Right click and select
<b>Reset...</b> on any branch or tag. This opens a dialog which lets you decide on the reset type. See
<a href="Tasks.html#Resetting_your_current_HEAD">Resetting you current HEAD</a> for further details.
</p>
<h5 id=".22Detached.22_HEAD">"Detached" HEAD</h5>
<p>If HEAD is "detached", i.e. is not pointing to the tip of a local branch but to a commit or tag, then none or several "checked-out" markers may appear in the tree, since any number of remote branch or tags may point to the currently checked out commit. The state you are in while your HEAD is detached is not recorded by any branch (which is natural --- you are not on any branch).</p>
<h4 id="Browsing_the_Working_Directory">Browsing the Working Directory</h4>
<p>The "Working Directory" node visualizes the local file system structure of the Git Repository. It is also possible to open a text editor on the files:</p>
<p>
<img border="0" src="images/RepoMgrOpenTextEditor.png"/>
</p>
<p>Also, on all file and folder nodes as well as on the "Repository" node, an option is offered to copy the (file-system specific) path to the clipboard. This is sometimes useful when the path is needed, for example to open a directory using a file browser or to copy and paste Repositories between view instances (see above about how to add Repositories to the view). The
<b>Copy to Clipboard</b> action is also available using
<b>Edit > Copy</b> (or the corresponding keyboard shortcut).
</p>
<h4 id="Repository_Configuration">Repository Configuration</h4>
<p>Integration with the generic "Properties" view in Eclipse allows to view and edit the Git Configuration (global and repository-specific configuration). If the "Properties" view is open, it is updated automatically when a "Repository" node is selected. For convenience, an
<b>Open Properties view</b> action is provided in the context menu:
</p>
<p>
<img border="0" src="images/RepoMgrPropertiesView.png"/>
</p>
<p>With a drop down box (left red box in the screen shot) you can switch between the display of the Repository Configutarion, the Global Configuration and a view which aggregates both. If the view displays the Repository Configutarion or the Global Configuration you can open an editor dialog with the
<b>Edit</b> button (right red box in the screen shot). The editor dialog has the same functionality as the preference page
<b>Team > Git > Configuration</b>.
</p>
<h4 id="Remote_Repositories">Remote Repositories</h4>
<p>The "Remotes" node allows for browsing and editing Remote configurations. Each Remote configuration has a name and either a Push Specification, a Fetch Specification, or both. If a "Remote Configuration" node or any of its children is selected, the
<b>Properties</b> view will show a summary of the Remote configuration. In this example: there is a Remote configuration named "origin" which only has a Fetch Specification, but no Push Specification:
</p>
<p>
<img border="0" src="images/RepoMgrRemoteConfig.png"/>
</p>
<p>Menu actions are provided to add, configure, and remove Remote configurations and Fetch and Push Specifications. </p>
<h5 id="Direct_Fetch_and_Push_Support">Direct Fetch and Push Support</h5>
<p>It is possible to execute fetch and push directly (i.e. without a wizard) on the respective "Fetch" and "Push" nodes:</p>
<p>
<img border="0" src="images/RepoMgrSimpleFetch.png"/>
</p>
<p>Note that the fetch or push operation will be executed immediately in an asynchronous job; on completion you will get a confirmation pop-up displaying the fetch result.</p>
<p>The "Fetch" node contains a so called fetch specification and the "Push" node contains a so called push specification.</p>
<p>A default fetch specification is created when the repository is cloned. You can edit the fetch specification with the menu entry
<b>Configure Fetch...</b>. This opens a wizard. On the first page you can edit the Fetch URI. Ob the second page you can determine the fetch ref specifications, see
<a href="Tasks.html#Fetch_Ref_Specifications">Fetch Ref Specifications</a>.
</p>
<p>You can create or edit a push specification with the menu entry
<b>Configure Push...</b>. This opens a wizard. On the first page you can edit the Push URIs. If a fetch is specified the fetch URI is automatically included into the push specification and no additional Push URI is needed. On the second page you can determine the push ref specifications, see
<a href="Tasks.html#Push_Ref_Specifications">Push Ref Specifications</a>.
</p>
<h5 id="Adding_a_Remote_Configuration">Adding a Remote Configuration</h5>
<p>This is done using a context menu action on the "Remotes" node. A wizard is started asking for the name of the new configuration and whether to configure Fetch, Push, or both:</p>
<p>
<img border="0" src="images/RepoMgrNewRemote.png"/>
</p>
<p>If the
<b>Configure Fetch</b> checkbox was selected, the next wizard page will ask for the URI of the Repository to fetch from:
</p>
<p>
<img border="0" src="images/Egit-0.9-repo-view-createRemoteWizardFetch.png"/>
</p>
<p>Click
<b>Change...</b> to open a dialog that allows you to select a URI.
The next step is to define the Remote Specification for the fetch URI. See
<a href="Tasks.html#Fetch_Ref_Specifications">Fetch Ref Specifications</a> about the details.
</p>
<p>If the
<b>Configure Push</b> checkbox was selected, the next wizard page will ask for the URIs of the repositories to push to. This is actually a list, as you can push to multiple repositories at once. Click
<b>Add....</b> to add URIs to the list using the same dialog as above. You can remove URIs by marking them in the list and hitting
<b>Remove</b>.
This step is completely optional if there is already a fetch URI defined. In this case, the fetch URI will also be used for push. If at least one push URI is defined in this steps, it will override the fetch URI. In this example, there is already a fetch URI, so the
<b>Next</b> button is enabled, even though there is no Push URI in the list:
</p>
<p>
<img border="0" src="images/Egit-0.9-repo-view-createRemoteWizardPush.png"/>
</p>
<p>The next step is to define the Remote Specification for the push URIs. See
<a href="Tasks.html#Push_Ref_Specifications">Push Ref Specifications</a> about the details.
</p>
<p>Upon completion, the new Remote configuration will be visible:</p>
<p>
<img border="0" src="images/RepoMgrRemoteCreated.png"/>
</p>
<h5 id="Changing_Remote_Configurations">Changing Remote Configurations</h5>
<p>It is also possible to add, remove, or change Fetch/Push Specifications for an existing Remote configuration using the context menu.</p>
<h3 id="Refresh">Refresh</h3>
<p>The view is auto-refreshed periodically. The
<b>Refresh</b> button in the toolbar allows to trigger an immediate refresh:
</p>
<p>
<img border="0" src="images/RepoMgrRefresh.png"/>
</p>
<h3 id="Link_with_Selection">Link with Selection</h3>
<p>If the
<b>Link with selection</b> toggle is enabled, the file or folder corresponding to the current workbench selection will be displayed automatically:
</p>
<p>
<img border="0" src="images/RepoMgrLinkWithSelection.png"/>
</p>
<h3 id="Link_with_Editor">Link with Editor</h3>
<p>If the
<b>Link with editor</b> toggle is enabled, the file or folder corresponding to the currently active editor will be displayed automatically:
</p>
<p>
<img border="0" src="images/RepoMgrLinkWithEditor.png"/>
</p>
<h3 id="Hierarchical_Branch_Layout">Hierarchical Branch Layout</h3>
<p>If the
<b>Hierarchical Branch Layout</b> toggle is enabled, branches will be shown in a hierarchical layout using slash (/) as hierarchy separator:
</p>
<p>
<img border="0" src="images/RepoMgrHierarchicalBranchLayout.png"/>
</p>
<p>This can be helpful for organizing large numbers of branches.</p>
<h3 id="Bare_Repositories">Bare Repositories</h3>
<p>"Bare" Git Repositories (as opposed to "development" or "standard" Repositories) have no working directory by definition, so all actions related to the working directory (check-out, project import, browsing the working directory) are not available for such Repositories. The "Bare-ness" of a Repository is visualized on the "Working Directory" node, which is always a leaf:</p>
<p>
<img border="0" src="images/RepoMgrBareRepository.png"/>
</p>
<h3 id="Removing_Repositories_from_the_Git_Repositories_View">Removing Repositories from the Git Repositories View</h3>
<p>This is offered as a menu action on the "Repository" node. Note that this does not delete the Repository, but just removes the node from the view. If there are projects in the workspace which are located in the working directory of the Repository, the user will be prompted to confirm deletion of these projects from the Eclipse workspace.</p>
<p>
<br/>
</p><hr/>
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<td style="width: 20%" align="left">
<a href="Concepts.html" title="Concepts">
<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="Reference.html" title="Reference">
<img alt="Next" border="0" src="../../images/next.gif"/>
</a>
</td>
</tr>
<tr>
<td style="width: 20%" align="left" valign="top">Concepts</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top">Reference</td>
</tr>
</table>
</body>
</html>
|
