EGit Tutorial for Beginners

Matteo recently created a very comprehensive tutorial for EGit, which I would like to share. The tutorial describes all basic features of EGit including screenshots. It is meant for people who are just starting to use EGit.
 
Installing EGit into Eclipse
Open the Eclipse Wizard to install new software Help => Install New Software. Insert http://download.eclipse.org/egit/updates after Work with: and hit Return. Select Eclipse EGit (Incubation) as a child from Eclipse Team Git Provider (Incubation). You don't have to install any other plugins. Click Next and confirm your selection in the following window pressing Next again. Finally, accept the terms of license agreement and click Finish to start the installation. After the installation has finished, restart Eclipse to work with EGit

EGit Configuration
Every commit in EGit will include the user's name and his email-address. These attributes can be set in the Preferences-window Window => Preferences. Navigate to Team => Git => Configuration and hit the New Entry... Button. Enter user.name as Key and your name as Value and confirm. Repeat this procedure with user.email and your email-address and click OK in the Preferences-window.

Creating Local Repositories
First ,you have to create any project you want to share via your local repository. For later purposes it would be useful to also add a class to your project. After you have created your project, rightclick it and navigate to Team => Share Project... . Select Git as the repository type and hit Next.

In the following window select your project, hit the Create Repository-button and click Finish. The repository will be assigned automatically.

 

The created repository will be empty, although the project is assigned to it (note the changed icons: the project node will have a repository-sign, the child nodes will have a question mark-sign, ignored files, e.g. the bin-directory, won't have any sign at all). Before you can commit the files to your repository, you have to add them. Simply rightclick the shared project's node and navigate to Team => Add. After this operation, the question mark-signs should have turned into plus-signs. The last thing to do is to commit the project: Rightclick the project node and select Team => Commit... from the context menu. In the Commit-wizard, all files should be selected automatically. Enter a commit message (the first line should be headline-like, as it will appear in the history view) and hit the Commit-button. If successful, the plus-signs should have turned into repository-signs as well.

Commit
To save changes done in your workspace into your repository, you will have to commit them. After changing files in your project, a ">" sign will be added, right after the icon, telling you the status of these files is dirty. Any parent folder of this file will be dirty as well.

If you want to commit the changes to your repository, rightclick the project (or the files you want to commit) and select Team => Commit... . This will open a new window, allowing you to select the files you want to commit. Before you can commit the files, you will have to enter a commit message in the upper textbox. After you're done, click Commit to commit the selected files to your repository.

Note that the status of the changed file is Mod., not staged. By staging the files before you commit (see section Additional Information), you can change the status to Modified (and the dirty sign to a staged icon).

If you realize your previous commit was incomplete (e.g. you missed to commit a file) or your last commit's commit message was wrong in any way, you might want to check Amend previous commit. This will merge the current commit and the previous commit into one, so you don't have to perform an extra commit (and maybe cause confusion). However, this should only be done if the previous commit hasn't already been published to a shared repository.
Another option is Show untracked files. By checking this checkbox, new files you created, but did not add yet, will be available for you to select. Checking untracked files will add them to your repository, after clicking Commit.

Adding Files
To add a new file to the repository, you will have to create it in your shared project first. The new file will, again, appear with a question mark-sign.

Rightclick it and navigate to Team => Add. The question mark-sign will turn into a plus-sign - the file is now tracked by Git, but not yet commited. All of the file's parent folders should now have a staged-sign (more on that later). In the next commit, the file will be added to the repository, therefore the plus-sign will turn into a repository-sign. The repository-signs of all the file's parents (packages/project...) will turn into staged-signs.

Reverting Changes
If you want to revert any changes, there are two possibilities: You can compare each file you want to revert with the HEAD revision (or the index, more on that later) and undo some or all changes done. Otherwise you can hard-reset your project, causing any changes in the working directory to be reverted.

Revert via Compare
Rightclick the file you want to revert and select Compare With => HEAD Revision. This will open a comparison with the HEAD Revision, pointing out any changes done. If you want to completely revert your file, hit the Copy All Non-Conflicting Changes from Right to Left-button in the Java Source Compare-toolbar. If you only want to revert several lines, select each line and hit the Copy Current Change from Right to Left-button from the toolbar each time. After any of these two you will have to save either the comparison or your local copy of the file to complete the revert operation.

Revert via Reset
To reset all changes done to your project, rightclick the project node and navigate to Team => Reset... . Select the branch you want to reset to (if you haven't created any other branches, there will be just one) and choose Hard as a reset type. By confirming this operation, all changes will be resetted to this branch's last commit, including all changes done in the workspace (and index, more on that later).

Cloning Repositories
Note: For this and some of the following (especially Fetch/Push) sections, you might want to use https://github.com for creating your own remote repository. This might be useful to perform several actions and gain some insight.

In order to checkout a remote project, you will have to clone its repository first. Open the Eclipse Import-wizard (e.g. File => Import), select Git => Projects from Git and click Next. This will open the Git Repository Selection. Hit the Clone... button to open another wizard for cloning Git repositories.

First you will have to enter the repository's location and connection data. Entering the URI will automatically fill some fields, if any other are required, fill these and hit Next. Select all branches you wish to clone and hit Next once more.

Choose a local directory to save this repository in.

Warning: I ran into some errors when choosing the default directory, as this was my workspace directory and I couldn't import projects into a subfolder in my workspace as Eclipse prohibited this. If you can't import projects from a repository, try changing this directory!

After clicking Finish, the cloned repository should appear in your repository list.

 To import the projects, select the cloned repository and hit Next. Select Import Existing Projects and Try to share newly created projects automatically (otherwise you would have to share the projects manually) and hit Next.

In the following window, select all projects you want to import and click Finish. The projects should now appear in the Navigator/Package Explorer (note the repository-sign in the icons - the projects are already shared)

Creating Branches
To create a new branch in your repository, rightclick a shared project and navigate to Team => Branch... from the context menu. Select the branch you want to create a new branch from, hit New branch and enter a name for the new branch.

The new branch should appear in the branch selection window. If you would like to checkout the just created branch, select it and click Checkout.

Merge
To merge one branch into another, you will have to checkout the branch you want to merge in to. Rightclick the project node and navigate to Team => Merge... . Select any branch (other than the checked out branch) and hit Merge.

The merge will happen automatically and pop up a result window telling you about the outcome. The possible results are Already-up-to-date, Fast-forward, Merged, Conflicting, Failed. A Conflicting result (see picture below) will leave the merge process incomplete, you will have to resolve the conflicts (see next chapter). A Failed result may occur when there are conflicting changes in the working directory.

Resolving Conflicts
If your merge resulted in conflicts (note the red sign in the file icons), you will have to resolve these manually. Open the conflicting files and scroll to the conflicting changes (<<<<<<<<<<

After you are done merging, you will have to tell Git that the conflict is resolved. To do so, Add the files and Commit afterwards to complete your conflicting merge.

Fetch
When cloning remote repositories, git creates a copy of the branches as local branches and as remote branches as well. A Fetch-operation will update the remote branches only. To update your local branches as well, you will have to perform a Merge-operation after fetching (Fetch and Merge is Pull in the original Git). To perform a Fetch, select Team => Fetch From... from the project's context menu. Enter the repository you want to fetch branches from (if you cloned this repository, the remote will be selected as default).

In the following window you will have to select what you want to fetch. By default, all branches are selected.

The result of the Fetch-operation will be shown in a final confirmation window:

Push
Local changes done to your local branches can be pushed to remote repositories causing a merge from your branches into the branches of the remote repository (X pulls from Y is the same as Y pushes to X). The Push-wizard is pretty much the same as the Fetch-wizard. First, rightclick the project node and navigate to Team  => Push... . Enter the repository you want to push your branches to (the default for this will be the same as the Fetch-default if you didn't configure a Push-default) and hit Next.

Choose the branches you want to push or click Add all branches spec if you want to push all branches. You can also select branches you want to delete from the remote repository. If you are done hit Finish.

A final window will show the results of the Push.

Synchronize
Comparisons between branches are done via the Synchronize-operation. Rightlick the project node and navigate to Team => Synchronize... . Select the branches you want to compare, include local uncommited changes if you like, and hit OK.

To compare the branches you may want to switch to the Synchronizing perspective. You might get a more detailed view of the several changes. The following picture shows a Synchronize in the Java perspective.

An example of a Synchronize-operation in the Synchronizing perspective:

History View
To show any shared file's history, rightclick it and select Team => Show in History. This will open the History View, granting an overview of the commits and allowing you to perform several actions (compare, creating branches/tags, reset...). Every commit you select comes up with a revision comment and revision details. The revision comment (bottom left corner) includes parents, children, commit message, changes... whereas the revision details (bottom right corner) name the changed files and the actions performed upon them (A=ADD, M=MODIFY, D=DELETE). Selecting a file in the revision details will scroll the revision comment to the changes of that file.

Creating Patches
EGit lets you create patches in Git patch format or default diff patch format. However, EGit doesn't support applying patches in Git patch format, yet. They could be applied via the command line though. Any patch can only include one commit, that is from a parent to its child (single parent, no merging allowed). To create a patch you have to open the History View first (see previous section). Rightclick a commit you want to create a patch for (this must be a child with exactly one parent) and select Create Patch....

Select either Clipboard or File and hit Next. Export this patch in Git patch format if you like (reminder: can't be applied via EGit yet) and click Finish. The resulting patch can be applied to the parent commit via Team => Apply Patch....

Repository View
The repository view is useful when working with branches/tags and executing operations on them as well as handling remote repositories and granting an overview over all your repositories. To open this view, select Team => Show in Repositories View from any file's context menu.

Additional Information

Icon Decorations/Signs

ignored: The repository treats these files as if they were non-existent (e.g. the bin-directory by default). Add a .gitignore file or Team => Ignore to ignore a file.

untracked: Any file known, but not yet recorded. To track a file, add it or select the Show untracked files-option in the commit-wizard and commit it directly.

tracked: Any file known to and recorded by the repository.

added: Any file known to the repository, but not yet commited. Perform a Commit to change this file's status to tracked.

removed: Any file that shall be removed from the repository. For this icon to appear Team => Untrack has to be performed. By deleting the file from the workspace, the file will disappear (and therefore no icon will appear). However, it will still be removed from the repository with the next commit.

dirty: Any tracked file with changes, that are not yet added to the index.

staged: Any tracked file with changes, that are already added to the index.

partially-staged: Any tracked file with changes, where some changes are already and others are not yet added to the index.

conflicted: Any file where the merge result caused a conflict. Resolve the conflicts and perform an Add-operation to change this file's status.

assume-valid: Any modifications won't be checked by Git. This option can be activated via Team => Assume unchanged. However, it can only be turned off via the command line without taking further actions. Performing a Reset-operation resets this status as well.

IndexThe index, sometimes referred to as staging area, is an area between the working directory and the repository. Any change done to any file will change this file's status to dirty (see above). Any dirty file can be added to the index with an Add-operation. The file's status changes to staged. You can compare files to the index and reset the index without resetting the workspace. In original Git, files had to be added to the index before performing a Commit-operation. This is not necessary in EGit, as Team => Commit allows to commit unstaged changes.

Reset Types
You can reset your current branch to any other branch, tag or commit you want. Rightclick any commit in the History View and select Reset. There are three options available:

Soft:
The current branch's tip will point to this branch/tag/commit. Changes in index and working directory, however, won't be resetted.
Mixed:
Same as a soft reset, only that the current index will be replaced by the selected branch/tag/commit's index. The working directory stays unchanged.
Hard:
All changes will be reverted to the selected branch/tag/commit. Uncommited changes will be lost, therefore this operation has to be confirmed.

Useful pages

• To create your own remote repositories and perform operations on them, you might want to register at https://github.com. As long as your repository is public, github is free.
• A tutorial with more information on certain options and actions: http://wiki.eclipse.org/EGit/User_Guide

Please feel free to post any comments or feedback. Thanks to Matteo for warpping things up.