EGit/User Guide

Getting Started

Overview

If you're new to Git or distributed version control systems generally, then you might want to read Git for Eclipse Users first. If you need more details and background read the Git Community Book.

Adding a project to version control

Create a new Java project "HelloWorld"

Select File > Team > Share Project

Select repository type Git and click Next

To configure the Git repository select the new Eclipse project HelloWorld

Click Create to initialize a new Git repository for the HelloWorld project. If your project already resides in the working tree of an exisiting Git repository the repository is chosen automatically.

Click Finish to close the wizard.

The decorator text "[master]" behind the project shows that this project is tracked in a repository on the master branch and the question mark decorators show that the ".classpath" and ".project" files are not yet under version control

Select Team > Add on the project node

The plus decorators show that now the ".classpath" and ".project" files are added to version control

Create a file .gitignore in the project folder with the following content:

bin

This excludes the bin folder from Git's list of tracked files. Add .gitignore to version control.

The file under ".settings" is not added to version control since it is by default on the list of ignored resources which can be changed in
Preferences > Team > Ignored Resources

Click Team > Commit in the project context menu

Enter a commit message explaining your change, the first line (separated by an empty line) will become the short log for this commit. By default the author and committer are taken from the .gitconfig file in your home directory. You may check the checkbox "Add Signed-off-by" to add a Signed-off-by tag. If you are committing the change of another author you may alter the author field to give the name and email address of the author. Click "Commit" to commit your first change.

Note that the decorators of the committed files changed.

Select Show In > History from the context menu to inspect the history of a resource

Create a new Java class HelloWorld and implement it, then add it to version control and commit your change. Improve your implementation and commit the improved class, the resource history should now show 2 commits for this class.

Double click "src/HelloWorld.java" in the Resource History View to open your last committed change in the Eclipse compare view

Perspective, Views and Menus

Git Perspective

Window > Open Perspective > Git Repository Exploring opens the Git Repository Exploring perspective

Git Repositories View

Window > Open View > Git > Git Repositories opens the Git Repositories view which is explained in detail here.

History View

Show In > History View on the context menu of resources under git version control navigates to the History View.

Project Context Menu

On project nodes in navigation views (Navigator, Package Explorer etc.) the following Git actions are available for projects shared with the Git team provider:

Resource Context Menu

On resource nodes (files and folders) in navigation views the following Git actions are available for projects shared with the Git team provider:

Menu Actions

• Commit...
• Push...
• Fetch...
• Branch...
• Merge...
• Tag...
• Reset...
• Apply Patch...
• Ignore: action to add files to .gitignore.
• Add:
  • Adds changes present in the working tree to the git index, also known as staging changes.
  • Puts newly created resources under git version control (Git does not automatically start tracking resources).
  • Resolves conflicts.
• Assume unchanged: Resources can be flagged "assume unchanged". 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. This setting can be switched on with the menu action Team > Assume unchanged (or on the command line with git update-index --assume-unchanged). Currently it can only be switched back on the command line with git update-index --no-assume-unchanged.
• Untrack: Removes resources from git version control. If you want to delete the resource from the working tree click also Delete in the resource's context menu.
• Disconnect: Disconnects the attached git team provider from this project.

Creating Repositories

Creating a new empty Git Repository

This is currently not possible with EGit. You have to create a project first and to share it afterwards. The Share Project Wizard supports creation of Git repositories (see Adding a project to version control).

Creating a Git Repository for multiple Projects

You may first create all projects under a common directory and then create a common repository for all projects in one go:

• create the Eclipse projects e.g. a, b, c under a common directory e.g. /repos/examples/
• select all projects a, b, c - from context menu click Team > Share Project > Git
• press Next
• select all projects a, b, c
• the wizard automatically moves up the default repository location to the parent folder /repos/examples/ since multiple projects have been selected
• click Create Repository and click Finish

Starting from existing Git Repositories

In order to work with the contents of a Git Repository in the Eclipse workbench, the files and folders contained in this repository must be imported in the form of projects. In principle, this import step 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.

Starting the import wizard

The wizard is started using
Import > Git > Projects from Git

If you started in a clean workspace, the first page will display an empty list:

Before you can continue, you need to add one or several Git Repositories to the list.

If you have already Repositories in the list, the following step is optional.

Cloning or adding Repositories

There are two ways to add Git Repositories to the list:

1. Clone a remote Repository
2. Add an existing Repository from your local file system

Cloning a Repository

The first option is used if you start with a remote repository. The clone operation will copy that Repository to your local file system. The Clone wizard is started using the Clone... button next to the Repository list. The Clone wizard is described in more detail elsewhere. Upon successful completion of the clone wizard, the newly cloned Repository should appear in the list automatically.

Adding a Repository

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. Clicking on the Add... button next to the Repository list, a dialog is displayed which allows to enter a directory in the local file system. Press Search to trigger a scan for Git repositories contained in this directory. If Git repositories are found, they will be shown in a list and you can select repositories to add:

After successful completion, the repository list should contain some repositories:

Selecting a Repository from the List

You can now select a Repository and click Next. On the following wizard page, you will have to decide:

• How to do the import
• How to share the imported projects:
• (Optional): limit the scope of the wizard

Method for importing Projects

Import Existing Projects

If this radio button is selected, the wizard will scan the local file system for .project files and display the projects found for being imported. This is the most comfortable solution and should be used if .project files are checked into the Repository.

Limiting the Scope for Project Import

In this case, the directory tree at the bottom is active. You can limit the search for .project 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 Import Existing Projects wizard, but has some additional filtering capabilities:

Use the New Projects Wizard

When this option is chosen, this wizard branches to the generic "New Project" wizard. After completion of the "New Project" wizard, this wizard will resume and help you with sharing the newly created projects (if any) created using the "New Project" wizard.

In this case, the directory tree at the bottom is inactive, as the selection is not relevant for the "New Project" wizard.

Import as General Project

This option can be helpful when there are neither .project files available nor a suitable "New Project" wizard applies to the content of the Git Repository. If chosen, the wizard will generate a .project file and point the project to a folder of the Repository's working directory. The result is a "General Project".

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.

When clicking Next you will see a simple dialog suggesting a name and a directory for the new project:

The name will be suggested to be the same as the name of the directory.

Method for Sharing Imported Projects

The newly created projects (if any) must be shared with the correct Git Repository in order to become part of the Git Team Provider. The following options for doing this share are provided:

Try to Share Newly Created Projects Automatically

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 manually.

Share New Projects Interactively

This might be useful for very special circumstances where the automatic detection fails. Note that this will block the UI until project import is completed.

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:

Do Not Share New Projects

This may be helpful if you want to share projects manually for some reason.

Working with remote Repositories

Cloning Remote Repositories

Using the Git Clone Wizard you may clone remote repositories using different transport protocols.

The wizard can be started from the "Import Projects from Git" wizard using
Import... > Git > Projects from Git > Next > Clone...

or from the "Git Repositories View" (described elsewhere) using the Clone a Git Repository toolbar button.

Repository Selection

On the first page of the wizard enter the location of the remote repository:

• URI - The complete URI of the remote repository or the path on the file system. This field is automatically synchronized with the other fields.
  Note that you can use the Local file... button to browse for a local directory and that the URI field offers content assist by offering previously used values
• Host - The name of the remote host or empty if cloning from the file system.
• Repository Path - Path to the remote repository or on the file system.
• Protocol - One of the protocols described below.
• Port - Port number.
• User - The user name used for authentication.
• Password The password used for authentication.

The following protocols are supported:

• git - 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.
• git+ssh - Git over secure shell (SSH) protocol. Typically used for authenticated write access to the repository.
• sftp - SSH File Transfer Protocol
• http - Hypertext Transfer Protocol can be tunneled through firewalls.
• https - Hypertext Transfer Protocol Secure can be tunneled through firewalls.
• ftp - File Transfer Protocol
• file - File system access to the repository.

Branch Selection

On the next page choose which branch should be cloned from the remote repository:

Local Destination

On the next page define where you want to store the repository on the local file system and define some initial settings.

• Directory - The directory which will contain the Git repository. It will be created by the wizard if it does not yet exist.
• Initial branch - Choose here which local branch will be created and initially checked out.
• Remote name - Define a name for the remote repository. The default is "origin".

Git References

Git References are also known shortly as Refs.
They comprise

• branches
• remote-tracking branches
• tags

They all are named with a path using '/' as path separator and are starting with "refs".

• Local branches start with "refs/heads/"
• Remote tracking branches start with "refs/remotes/"
• Tags start with "refs/tags/"

Ref names can be abbreviated as long as the abbreviated form is unique.
E.g.

• "master" is short for "refs/heads/master"
• "origin/master" is short for "refs/remotes/origin/master"
• "v1.0.1" is short for "refs/tags/v1.0.1"

For a complete list for Ref names and the order of precedence if multiple references have the same shorthand form see the section "Specifying Revisions" section of git rev-parse.

Pushing to other Repositories

Direct Push

The easiest way for pushing is to use Direct Push Support on a Push Specification of a Remote.

Push Wizard

The other way is using the Push Wizard
Team > Push...

Push URI

• If you already configured a Push Specification in the Repositories View you may also select it here using the drop-down list under Configured remote repositories.
• Otherwise click Custom URI and enter the URI of the upstream repository you want to push to.

Push Ref Specifications

Click Next
Click Add all branches spec

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.

Click Add all tags spec to map local tags 1:1 to tags in the repository you want to push to.

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

• enter source and destination ref or select already existing branches from the drop-down lists
• click Add spec

This will transfer the newly defined mapping to the list Specifications for push

Other common push specs:

• You may e.g. map refs/heads/* to refs/heads/joe/* if you want to name the branches you push to according to your nickname joe. This is useful if multiple users want to publish their local branches on personal branches in a jointly used public repository.
• Another usual mapping is to map the source ref HEAD to the destination refs/heads/master. This means you want to map your current HEAD (which might currently point e.g. to any local topic branch) to the upstream master branch.

Delete Ref Specifications

To delete a ref in the destination repository select the ref to be deleted from the drop-down list Remote ref to delete and click Add spec. This will create a corresponding entry in the Specifications for push 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.

Conflicting Push Ref Specifications

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 Specifications for push

Push Confirmation

Click Next

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 Back and correct your push specs accordingly.

• For ref updates the range of commits to be pushed will be shown in the format <SHA1-from>..<SHA1-to> e.g. d97f5a2e..adfdbfd2 means all commits between d97f5a2e and adfdbfd2 will be pushed.
• For refs which do not yet exist in the destination repository [new branch] or [new tag] is displayed.
• For refs which will be delete [deleted] is shown.

• Select the Push only if remote refs don't change in the mean time 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.
• Select the Show final report dialog only when it differs from this confirmation report check box if you only want to get a report after executing the push if the result differs from this preview.

Push Result Report

Click Finish

Depending on the options you have chosen a push result report dialog is shown

Click Ok to close the dialog.

Example: Pushing a Local Repository to GitHub

Create Local Repository

• follow EGit/User Guide/Getting Started to create a new local repository (with your content instead of the demo project)

Create Repository at GitHub

• create a new repository at GitHub

• you get a fresh clone URL for this new repository

Eclipse SSH Configuration

• Click Window > Preferences and ensure that your SSH2 home is configured correctly (usually this is ~/.ssh) and contains your SSH2 keys (upload your public key to your GitHub account settings)

• if you don't have SSH keys yet you may generate them on the second tab Key Management of this dialog, use a good pass phrase to protect your private key, for more details see "working with key passphrases"

Push Upstream

• Select your new Eclipse project and click Team > Push....
• Enter Your GitHub Clone URL and your GitHub password (with the free github accounts do not enter a password but leave this field blank), leave the user as git.

• Click Next and on first connection accept GitHub's host key.

• Enter your SSH key's passphrase.

• Click Add all branches spec to map your local branch names 1:1 to the same branch names in the destination repository.

• Click Next. The push confirmation dialog will show a preview of the changes that will be pushed to the destination repository.
• Click Finish to confirm that you want to push these changes.

• The next dialog reports the result of the push operation.

• Point your browser at your GitHub repository to see that your new repository content has arrived

Fetching from other Repositories

Direct Fetch

The easiest way for fetching is to use Direct Fetch Support on a Fetch Specification of a Remote.

Fetch Wizard

The other way is using the Fetch Wizard
Team > Fetch...

• If you already configured a Fetch Specification in the Repositories View you may also select it here using the drop-down list under Configured remote repositories.

• Otherwise click Custom URI and enter the URI of the upstream repository you want to fetch changes from.

Fetch Ref Specifications

Click Next
Click Add all branches spec

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.

• Click in the edit field Destination Ref and replace the path segment choose_remote_name with a symbolic name for the upstream repository you are going to fetch from.
• The default remote name for the repository your repository has been cloned from is origin. The master of this remote maps by default from refs/heads/master to refs/remotes/origin/master.
• 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 refs/heads/* to the following tracking branches refs/remotes/joe/*.
• Deselect Force Update if you want to allow fast-forward updates only, select this option if you also want to allow non-fast-forward changes.
• Click Force Update all Refs to set the force update option on all specs
• Click Remove all specs to remove all specs from the list Specifications for fetch

• Click Add all tags spec to map tags tags in the repository you want to fetch from 1:1 to local tags.

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

• 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
• click Add spec

This will transfer the newly defined mapping to the list Specifications for fetch

Fetch Result Report

Click Finish

A fetch result dialog is shown.

• For ref updates the range of commits which have been fetched will be shown in the format <SHA1-from>..<SHA1-to> e.g. d97f5a2e..adfdbfd2 means all commits between d97f5a2e and adfdbfd2 have been fetched.
• For refs which didn't exist before in the local repository [new branch] or [new tag] is displayed.
• For refs which have been deleted [deleted] is shown.

Pulling New Changes from Upstream Repositories

This is not yet fully available.

In cases where fast-forward merges are sufficient (full merge is not yet implemented) you may run pull in EGit in the following way:

• Fetch changes from upstream repository
• Checkout the branch you want to pull the upstream changes into
• Merge the branch or tag you want to integrate into your current branch

Available alternatives currently include:

• run git pull from outside eclipse (but beware on Windows)
• if you did no local change or want to discard your local changes, use Team > Reset...

Inspecting the state of the Repository

Label Decorations

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.

The Git label decorations can be switched on globally in the Preference Menu (Window > Preferences) under General > Appearance > Label Decorations.

More detailed settings can be done in the Preferences under Team > Git > Label Decorations.

There are two different types of label decorations: text decorations and icon decorations.

Text Decorations

Text decorations appear on the left or right side of the text label. They can be configured on the Preferences dialog under Team > Git > Label Decorations on the tab Text Decorations. For example, the default for a dirty resource is a > on the left side of its name.

These are the default settings:

For files and folders there are the variables "name", "dirty" and "staged". "Dirty" and "staged" are flags; if they are true, the text after the colon is displayed.

For projects there are the additional variables "repository" and "branch". The "repository" variable displays the name of the repository.

The "branch" 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 e49f576... refers to tag v.0.7.1 of repository egit:

Icon Decorations

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 Team > Git > Label Decorations on the tab Icon Decorations.

These are the default decorations:

• dirty (folder) - 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.
• tracked - The resource is known to the Git repository and hence under version control.
• untracked - The resource is not known to the Git repository and will not be version controlled until it is explicitly added.
• ignored - The resource is ignored by the Git team provider. The preference settings under Team > Ignored Resources, "derived" flag and settings from .gitignore files are taken into account.
• dirty - The resource has changes in the working tree that are neither in the index nor in the repository.
• staged - 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.
• partially-staged - 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.
• added - 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.
• removed - The resource is staged for removal from the Git repository.
• conflict - A merge conflict exists for the file.
• assume-valid - 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 Assume unchanged action.

History View

The History View displays the the history of the files versioned in a Git repository. To open the History View select Show In > History View from the context menu on any resource under Git version control.

The top level pane is the commit graph displaying the commit log in reverse chronological order (newest commit on top).

• The tips of local branches are shown as green rectangles
• The tips of remote branches are shown as grey rectangles
• The local HEAD is shown as a white rectangle

• Tags are shown as yellow rectangles

The lower two panes show the details of the selected commit. In the lower right pane the files affected by the commit are listed.

The letter in the first column of this table describes the nature of the change for this file:

A  the file was added by the commit

M  the file was modified by the commit

D  the file was deleted by the commit

In the lower left pane the commit message and some of its metadata and the git diff for the affected files are listed.

History View Configuration

The toggle buttons in the the view toolbar control how the displayed commits are filtered with respect to the context set by the resource selected in e.g. the Navigator or Package Explorer view:

If none of the toggle buttons is down the commit log is filtered to show only commits which affected the selected resource.

If the right-most toggle is down the commit log is filtered to show all commits which affected any of the resources in the selected resource's parent folder.

If the middle toggle is down the commit log is filtered to show all commits which affected any of the resources in the selected resource's project.

If the left toggle is down the commit log is not filtered and shows all commits reachable from the currently checked out branch.

When the toggle button with the magnifying glass is down a search bar is displayed which allows to search for commits in the commit log:

Depending on the setting in the drop-down list in the search bar the commit's title, comments, author or committer are searched.
The found search hits are high-lighted in bold and the "next" and "previous" buttons allow to jump to the next or previous commit matching the search criteria.

The configuration drop-down menu in the view's toolbar allows to change formatting rules for the commit message and controls if the lower two panes of the History View should be displayed:

Commit Dialog

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.

Comparing Content

In daily work you will often want to see the changes between your last commit, the index, and the current working tree.

Currently a compare dialog can only be opened for a single selected file.

Compare working tree with last commit

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.

Comparing Working Tree with Index

The difference between a file in the current working directory and in the index can be viewed from the context menu Compare With > Git Index.

Comparing Working Tree with Any Commit

• Select a file in the package explorer
• from the context menu select Show in > History or Compare With > History...
• in the commit graph select a commit
• from the context menu select Compare with working tree
• this will open a compare dialog showing the changes between the selected commit and the current working tree

Comparing Two Commits with Each Other

• Select a file in the package explorer
• from the context menu select Show in > History or Compare With > History...
• in the commit graph select two commits
• from the context menu select Compare with each other
• this will open a compare dialog showing the changes between the two selected commits

Comparing Index with HEAD or Any Other Commit

This feature is not implemented yet.

Quickdiff

Instead of using a compare editor you can enable quick diff support and see the changes within the text editor.
This feature can be enabled via the General > Editors > Text Editors > Quick Diff preference page:

The difference annotation will then be displayed on the left hand side of the editor:

If you move your mouse over the annotation you see the content of the version you are comparing to:

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 (Show in > History). There are three menu entries:

• Quick Diff -> Reset baseline to first parent of HEAD - Compare against the first commit before HEAD.
• Quick Diff -> Reset baseline to HEAD - Compare against HEAD.
• Quick Diff -> Set as baseline - Compare against the selected commit

View Diff for a Commit

To display the diff for a given commit

• from context menu in package explorer select Team > Show in Resource History
• select the commit you want to inspect
• the history view will display the diff in the lower left pane
• selecting a file in the lower right pane will scroll to the corresponding file section of the diff

Committing Changes

Modifications to a project which is version-controlled with Git are persistently recorded in the history through commits. In Git you modify your project until you have reached a state you are satisfied with and then you commit all these changes together to the repository in one single commit.

Modifying the content

If you have a project which is already shared with Git then doing the actual modifications is easy: just modify or delete files either within Eclipse or even directly on the file-system. There is no need to "check-out" files or to tell Git in advance about these operations. Only when adding new files you should be cautious: new files which should be version-controlled have to be explicitly put under Git version control using the file's Add menu action or immediately before a commit in the Commit dialog you may display untracked files by checking the Show untracked Files checkbox and select them for inclusion in the commit.

You can see for example in the Package Explorer View which files have been added (file icon marked with "+") and which files have been modified (file marked with ">" in front of the filename). For details see Label Decorations.

Here is an example of one added and one modified file in the Package Explorer:

Committing

When you are satisfied with the state of the project you may commit your changes. To do that select Team > Commit... from the context menu of a project or a file in the project.

It does not play a role whether you select this action on a certain file or on the whole project. The reason for this is that Git tracks all changes made to the whole repository capturing the modifications of each and every version-controlled file in that repository not regarding if these files reside in the same Eclipse project or not.

Once you have triggered the commit the following dialog will pop-up.

Commit Message

In this dialog you specifiy the commit message describing the change.

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.
At the end a number of footer tags may follow :

Bug: 3176
Reported-by: Joe Developer <joe@dev.org>
Signed-off-by: William Shakespeare <will.from@the.past>

The semantics of these tags are project or tool specific, e.g. Gerrit Code Review uses the Change-Id: footer to correlate the different patchsets of a change evolving during the review process towards the finally accepted patch. The Signed-off-by: footer is used by many projects to create a formal track record of declarations that the signing authors 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.

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.

One example: 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.

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 .gitignore 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 Show untracked Files is selected by default.

Amending Commits

When you commit you may specify that the current commit should "amend" the previous commit in the current branch. Your commit will then replace the previous commit. This feature is often use to correct wrong commits before they are published to other repositories.

Example: Imagine you have committed a change to a file containing a typo

After you committed you detect the typo. In order to correct this typo and the corresponding commit you just fix the typo in the source file

Afterwards you trigger the commit and select the option Amend previous commit.

The commit message of your previous commit (the one which 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.

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 else and in order not to clutter the history of your project with unneeded commits you may decide to use the amend feature.

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.

Signing off commits

Git gives you the chance to "sign off" commits. This adds a Signed-off-by: <Your Name and Email-Adress> footer to the commit message. The purpose of this signed-off-by information is not defined by Git but by the team using Git. Some teams use this information to record who has reviewed a certain commit. Other teams use the signed-off information to record that a commiter agreed to certain standards/rules. E.g. you may have to sign-off your own commits to state that you have read and understood the license-specific rules of your project.

Reverting Changes

Reverting changes in the working tree

Replace with File in Git Index

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 select

Replace with HEAD

This feature is currently not available on single file level. You can use Reset to with the option hard to set the whole working tree of your repository to the state of the HEAD commit (See "Resetting your current HEAD" below). By this you revert all changes in the working tree and the index. You can't do it on a selected set of files yet.

Resetting your current HEAD

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 whole repository.

You have the option to do a hard reset, a mixed reset and a soft reset.

• soft - the HEAD points now to the new commit, the index and the working tree are unchanged
• mixed - the HEAD points now to the new commit, the index is updated, the working tree is unchanged
• hard - the HEAD points now to the new commit, the index and the working tree are updated

Reset to specific branch or tag

Select Team -> Reset... on a project. This opens a dialog where you can select a branch or a tag.

Reset to a specific commit

Select a commit in the History view and open the context menu. Here you find the entries Hard reset, Mixed reset and Soft reset.

Revert all local and staged changes

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 hard you overwrite the working tree and the index with the content of the HEAD. You can do this in two ways:

• Select Team > Reset... on a project. In the dialog select HEAD or your current branch and switch the radio button to "hard".
• Open the context menu on the HEAD commit in the history view and select Hard Reset.

Branching

Branching in the Repositories View

The Repositories View supports the following branching actions:

• Checkout of branches
• Creation and deletion of branches
• Determining the checked out branch

Branching Dialog

To open the branching dialog click
Team > Branch...

Creating a New Local Branch

• Select the branch your new branch should be based on
• Click New Branch
• Enter the branch name and click OK

Renaming an Existing Branch

• Select the branch you want to rename
• Click Rename
• Enter the new branch name and click OK

Checking out a Branch

• Select the branch you want to check out
• Click Checkout

Merging

A merge incorporates changes from named commits (since the time their histories diverged from the current branch) into the current branch.

Merging a branch or a tag into the current branch

Note: Egit currently supports only fast-forward merges (see below).

In the Package Explorer or Navigator, open the context menu on a project node. Select Team > Merge...

Now the merge dialog opens:

On the dialog, select a branch or a tag you want to merge with your current branch. After pressing the Merge button, the following scenarios can occur:

• Already up to date: Your current branch points to a commit that has the selected branch or tag as predecessor. In this case nothing is changed.
• Fast-forward: 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).
• Real merge: When neither of the conditions above apply egit triggers a merge of the commits. This is not implemented yet.

Tagging

Creating a Tag

• Select Team > Tag... from the project context menu.

• Enter the tag name
• Enter the tag message
• Optionally select the commit you want to tag (default is HEAD)
• Click OK to create the annotated tag

Replacing an Existing Tag

What to do if you tagged the wrong commit or ended up with some sort of typo ?

• If you didn't yet push this out just replace the tag and you are done.
• If it's already published you shouldn't replace the tag 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.}}

So if your old tag wasn't yet pushed you may correct it in the following way :

• Select Team > Tag... from the project context menu.

• Select the tag you want to replace from the list of existing tags
• 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
• Mark the checkbox Force replace existing tag
• Change the tag and press OK

Light-weight and Signed Tags

Light-weight and signed tags are not yet supported by EGit, use command line git tag or git tag -s as a workaround

Patches

Creating Patches

"A patch is a piece of software designed to fix problems with, or update a computer program or its supporting data" (wikipedia). 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.

The patch formats used by eclipse (Team > Apply Patch) and by git (git apply or git am on the command line) are different. It is possible to create both types of a patch in EGit.

Create a Patch from a Commit

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.

It can be done from the history view:

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.

Patch Wizard

The Wizard consists of two pages. Page one lets you select the location of the patch:

The name of the patch file is created from the first line of the commit message.

On the second page you can change the patch format.

Currently there is one check box: Export in git patch format.

• If you do not check it (this is the default) the patch can be applied with the eclipse Apply Patch... wizard. The paths are relative to the eclipse projects and do not contain prefixes (like git format-patch --no-prefix on the git command line).
• If you check it the patch will look like the result of git format-patch --no-stat on the git command line.

Applying Patches

Currently it s not possible to apply patches in git format. It is possible to apply patches using the standard eclipse format using Team > Apply Patch....

Managing Repositories

The "Git Repositories View" is the primary UI element to facilitate working with multiple Repositories simultaneously (i.e. within one Eclipse Workspace).

This view can be opened using the menu path
Windows > Show View > Other... > Git > Git Repositories

It is also part of the "Git Repository Exploring" perspective available using menu path
Window > Open Perspective > Other... > Git Repository Exploring

If you already have projects in your workspace which are shared with a Git Repository, you can use
Show In... > Git Repositories

on any resource to open the view:

Adding Repositories to the Git Repositories View

Initially, the Git Repositories View is empty. In order to add Repositories to it, there are several options:

1. Cloning a Repository and having the cloned Repository added to the view automatically
2. Adding a Repository from the Local File System manually
3. Adding a Repository by pasting a Git Repository path to the view

Cloning a Repository

In order to clone a Repository, refer to Cloning remote Repositories. After a successful clone operation, the newly cloned Repository should appear in the Git Repositories View automatically.

You can also use the Clone a Git Repository button from the view's toolbar to start the Clone wizard:

Please refer to Cloning remote Repositories about how to use the wizard.

Adding a Repository manually

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 Add an existing Git Repository button from the view's toolbar:

A dialog will appear prompting you for a directory of your local file system. After selecting the correct directory, you can hit the Search 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 OK:

Adding a Repository using copy and paste

As a shortcut,it is also possible to just paste the local file system path of a Git Repository from the clipboard to this view. In order to do so, copy the path of a Git Repository (the path to the repository's .git folder) to the clipboard, then open the context menu on the view panel (i.e. not selecting a node):

or simply perform Edit > Paste 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.

After the view has been populated with some Repositories, it should look like this:

Structure of the Git Repositories View

The following screenshot shows the topmost two levels of the Git Repositories View:

The root node represents the Repository itself. The node text indicates the name of the Repository and it's 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.

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).

Finally, the "Remotes" node allows browsing and manipulating the remote configurations used for Fetch and Push.

Functions of the Git Repositories View

Project Import

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.

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:

The rationale for offering the Import Projects... 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 Import Existing Projects 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.

The details of project import are discussed elsewhere.

Branch and Tag Support

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. 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 "refs/heads/master" you would find an entry "master" under the "Local Branches" node, instead of "refs/remotes/origin/master" the shortened name "origin/master" is displayed under the "Remote Branches" node. Similarly, tag names are shortened by omitting the "refs/tags/" prefix:

Check-out of Branches and Tags

Branches and tags can be checked out by either double-clicking on the respective node or by selecting the corresponding context menu entry.

Creation and Deletion of Branches

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" 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" node, the source branch drop-down will be pre-selected with either the selected branch or the currently checked-out branch:

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.

Branch deletion is done using the corresponding context menu entry.

Determining the Checked-out Branch

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:

"Detached" HEAD

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).

Browsing the Working Directory

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:

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 Copy to Clipboard action is also available using Edit > Copy (or the corresponding keyboard shortcut).

Repository Configuration

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 Open Properties view action is provided in the context menu:

Remote Repositories

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 Properties 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:

Menu actions are provided to add, configure, and remove Remote configurations and Fetch and Push Specifications.

Direct Fetch and Push Support

It is possible to execute fetch and push directly (i.e. without a wizard) on the respective "Fetch" and "Push" nodes:

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.

Adding a Remote Configuration

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:

The details of Remote configuration are explained elsewhere. Upon completion, the new Remote configuration will be visible:

Changing Remote Configurations

It is also possible to add, remove, or change Fetch/Push Specifications for an existing Remote configuration using the context menu.

Refresh

The view is auto-refreshed periodically. The Refresh button in the toolbar allows to trigger an immediate refresh:

Link with Selection

If the Link with selection toggle is enabled, the file or folder corresponding to the current workbench selection will be displayed automatically:

Bare Repositories

"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:

Removing Repositories from the Git Repositories View

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.