Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

EGit/User Guide/3. Tasks

EGit User Guide

Contents

Creating Repositories

Considerations for Git Repositories to be used in Eclipse

The short story

When setting up Git Repositories with EGit, there are two recommendations for the creation of "productive" (as opposed for "playground") Repositories:

  • Don't create the Repository within the Eclipse workspace
    • Be careful when cloning or creating a Repository
    • Make sure to use the Git Sharing Wizard correctly
  • Don't create a Repository with an Eclipse project as root
    • Make sure to use the Git Sharing Wizard correctly

The first one happens when you specify a workspace folder during cloning or creation of a Repository.

Both of the above will happen when you use the Git Sharing Wizard from an Eclipse project that you have created manually in your workspace without taking precautions (the wizard has been fixed in the latest version).

Below you will find some motivation for these recommendations.

The longer story

Eclipse Workspace and Repository working directory

Git Repositories can be created in different ways, for example by cloning from an existing Repository, by creating one from scratch, or by using the EGit Sharing wizard.

In any case (unless you create a "bare" Repository, but that's not discussed here), the new Repository is essentially a folder on the local hard disk which contains the "working directory" and the metadata folder. The metadata folder is a dedicated child folder named ".git" and often referred to as ".git-folder". It contains the actual repository (i.e. the Commits, the References, the logs and such).

The metadata folder is totally transparent to the Git client, while the working directory is used to expose the currently checked out Repository content as files for tools and editors.

Typically, if these files are to be used in Eclipse, they must be imported into the Eclipse workspace in one way or another. In order to do so, the easiest way would be to check in .project files from which the "Import Existing Projects" wizard can create the projects easily. Thus in most cases, the structure of a Repository containing Eclipse projects would look similar to something like this:

EGit-0.12-SetupRepo-RepoStructureTwoProjects.jpg

Implications

The above has the following implications:

  • It is probably not a good idea to make a project the root folder of your Repository
The reason is that you will never be able to add another project to this Repository, as the .project file will occupy the root folder; you could still add projects as sub-folders, but this kind of project nesting is known to cause lots of problems all over the place. In order to add another project, you would have to move the project to a sub-folder in the Repository and add the second project as another sub-folder before you could commit this change.
  • It is a good idea to keep your Repository outside of your Eclipse Workspace
There are several reasons for this:
The new Repository will consider the complete folder structure of the Eclipse workspace as (potential) content. This can result in performance issues, for example when calculating the changes before committing (which will scan the complete .metadata folder, for example); more often than not, the workspace will contain dead folders (e.g. deleted projects) which semantically are not relevant for EGit but can not be excluded easily.
The metadata (.git-) folder will be a child of the Eclipse Workspace. It is unclear whether this might cause unwanted folder traversals by Eclipse.
You can easily destroy your Repository by destroying your Eclipse Workspace

Creating a new empty Git Repository

You can create a project first and share it afterwards. The Share Project Wizard supports creation of Git repositories (see Adding a project to version control).

You can also create a new empty Git Repository from the Git Repositories View (see Creating a Repository).

Creating a Git Repository for multiple Projects

You may first create multiple 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 Finish


Starting from existing Git Repositories

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.

Starting the import wizard

To start the wizard click Import > Git > Projects from Git

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

Egit-0.9-import-projects-select-repository.png

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.

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. To start the Clone Wizard click Clone.... The Clone Wizard is described in more detail in Cloning Remote Repositories. Upon successful completion of the clone operation, the newly cloned repository appears 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. Click Add...; and select 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 listed and you can select repositories to add :

Egit-0.11-import-projects-add-dialog.png

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

Egit-0.11-import-projects-filled-list.png

Selecting a Repository from the List

You can now select a repository and click Next. On the following wizard page, you will decide how to import projects.

Importing projects

This page offers a group with radio buttons that allow you to select a wizard and a directory tree that optionally allows you to select a folder in the working directory.

Egit-0.11-import-projects-select-wizard.png

Wizard for project import

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:

Egit-0.9-import-projects-select-projects.png

Use the New Projects Wizard

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.

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.

Click Next to open a simple dialog for entering a name and a directory for the new project:

Egit-0.9-import-projects-general-project.png

By default the suggested project name matches the name of the directory.

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 in Managing Repositories) using the Clone a Git Repository toolbar button or view menu.

Repository Selection

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

Egit-0.9-clone-wizard-url-page.png

  • 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.
  • Store in Secure Store Whether the password is saved in the Eclipse secure store.

The following protocols are supported:


Note: If you are behind a firewall you may need to configure your proxy settings (Preferences > General > Network Connections). Many HTTP proxies are configured to block URLs containing a username (and/or password) like e.g. http://fred:topsecret@egit.eclipse.org/egit.git hence it's recommended to use the user, password fields at the bottom of the wizard page, the credentials will be transmitted as HTTP headers.

Branch Selection

On the next page choose which branches shall be cloned from the remote repository:

Egit-0.11-clone-wizard-branch-page.png

If you are not sure which branches you need, simply hit "Select All".

You can filter the branches by their name by typing using the text control above the list. Note, however, that branches that have been checked will always be shown in the list, i.e. they will not be filtered.

Local Destination

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

Egit-0.9-clone-wizard-destination-page.png

  • 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".

The default root path for storing Git repositories can be configured in the preference Team > Git > Default Repository Folder

You can press Finish ob this page or press Next if you are working with Gerrit Code Review and you want to configure your repository accordingly.

Gerrit Configuration

If you clone a repository from a Gerrit Code Review server you may use this page to

  • specify the push configuration used to push changes to code review
  • configure your repository to select the Compute Change-Id for Gerrit Code Review option in the Commit dialog by default

Egit-0.9-clone-wizard-gerrit-page.png

Select the check box Configure Push to Gerrit Code Review. This has two effects:

  • The fields in the sections Push URI and Push Configuration get enabled.
  • When you click Finish the wizard sets the repository configuration parameter gerrit.createchangeid to true. This ensures that the checkbox Compute Change-Id for Gerrit Code Review in the Commit dialog is selected by default. See Commit Message for details.
  • If you want to configure automatic Change-Id insertion at a later point in time you may use the repository configuration editor (Preferences > Team > Git > Configuration) to set the configuration parameter gerrit.createchangeid to true. If you want this configuration for all your repositories you may put it into ~/.gitconfig then you don't need to repeat this configuration for every new repository you happen to work on.

In the section Push URI you can configure the URI which is used for the default push configuration. It is pre-filled depending on the URI you are cloning from. If you clone with the git protocol, the protocol is automatically changed to ssh, and the default Gerrit ssh port 29418 is automatically added. For protocols which require a user there is a user field for convenience.

The section Push Configuration has one field, Destination Branch. Here you should enter the name of the target branch where changes accepted in the Gerrit code review workflow will be submitted to. This yields an entry HEAD:refs/for/<branchname> in the push configuration of the remote you specified in the clone wizard.

Pushing to other Repositories

Pushing to upstream

If you are working with a local branch which has a so-called "upstream configuration", the most convenient way for pushing relies on this upstream configuration.

Typically local branches are created based on a remote tracking branch. Since the remote tracking branch is associated with a remote and the remote contains the information required to access the corresponding remote repository, it is possible to automatically create this upstream configuration while creating the local branch (see Branching for more information).

When pushing upstream from the local branch, push requires no further parameters and hence can be performed without showing another dialog based on the stored upstream configuration.

In order to push upstream, right-click on a project and select Team > Push to upstream or right-click on a Repository in the Repositories View and click Push to upstream. There is also an action available in the Git Command Group.

Push will then be executed immediately after selecting the action. Once finished, a confirmation dialog will be shown displaying information about the pushed data and/or error messages:

Egit-0.11-PushResultDialog.png

Configuring upstream push

The upstream push can be configured using the "Configure..." button on the confirmation dialog (see above) or by right-clicking a project and selecting Team > Remote > Configure push to upstream....

A configuration dialog will be shown for configuration of push URIs and corresponding branch mappings (RefSpecs):

Egit-0.11-ConfigurePushToUpstream.png

The dialog is divided into three main sections. In the upper part, information about the current Repository and the currently checked out branch is shown. The outer Group shows the Push Configuration for the remote that is associated with the current branch (in our case, "origin" as shown in the Group text).

In this specific example, there is a warning message that there are several branches that use the remote named "origin". This means that changes in the push configuration will affect all these branches, not just the branch shown in the Branch field.

The URI Group contains two controls, a URI field and a Push URIs list. If the list is empty, the URI in the URI field will be used for Push, if at least one entry is in the Push URIs list, the URIs in the list will be used instead. It should be noted that if the Push URIs list is empty and the URI is changed in this dialog, the new URI will also be used for Pull, so care should be taken when doing so.

The RefMapping Group allows specification of one or several RefSpecs (see Refspecs) for Push.

The "Add" will open a small wizard that helps in the creation of the RefSpecs. You can also paste a RefSpec from the clipboard into the list.

Clicking on the "Advanced" control will show/hide an "Edit (Advanced...)" button that allows for more complex RefSpec editing similar to the Push Wizard below.

The buttons in the lower button bar allow you to save your changes and do the push immediately, save the changes without fetching, dry-run (push without saving the configuration), revert your changes, and Cancel.

Direct Push

Alternatively, you can use Direct Push Support on a Push Specification of a Remote.

Push Wizard

The most powerful (but also most complex) way is using the Push Wizard
Team > Remote > 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. The Finish button will be enabled if the Push Specification for this remote is configured properly (i.e. has at least one URI and a ref spec.
  • Otherwise click Custom URI and enter the URI of the upstream repository you want to push to.

Egit-0.9-push-wizard-destination-page.png

Push Ref Specifications

See also Refspecs for more explanations.

Click Next
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

Egit-0.9-push-wizard-accept-hostkey.png

If your ssh key is protected by a passphrase (which is recommended) you have to enter it here

Egit-0.9-push-wizard-ssh-passphrase.png

Click Add all branches spec

Egit-0.9-push-wizard-refspec-allbranches.png

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.

Egit-0.9-push-wizard-delete-refspec.png

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

Egit-0.9-push-wizard-refspec-conflict.png

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.

Egit-0.9-push-wizard-confirm-push.png

  • 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

Egit-0.9-push-wizard-push-result.png

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.

Click Ok to close the dialog.

Fetching from other Repositories

Fetching from upstream

If you are working with a local branch which has a so-called "upstream configuration", the most convenient way for fetching relies on this upstream configuration.

A local branch is typically created based on a remote tracking branch. Since the remote tracking branch is associated with a remote and this remote contains the information required to access the remote repository, it is possible to automatically create this upstream configuration while creating the local branch (see Branching for more information).

When fetching from upstream, this persisted configuration can be used to fetch automatically without the need to provide further parameters in a dialog.

In order to fetch from upstream, click Team > Fetch from upstream on a project or click Fetch from upstream on a Repository in the Repositories View. There is also an action available in the Git Command Group.

Fetch will be executed immediately after selecting the action. Once finished, a confirmation dialog will be shown displaying information about the fetched data and/or error messages:

Egit-0.11-FetchResultDialog.png

Configuring upstream fetch

The upstream fetch can be configured using the "Configure..." button on the confirmation dialog (see above) or by clicking Team > Remote > Configure fetch from upstream... on a project.

A configuration dialog will be shown for configuring the fetch URI and branch mappings (RefSpecs):

Egit-0.11-ConfigureFetchFromUpstream.png

The dialog is divided into three main sections. In the upper part, information about the current Repository and the currently checked out branch is shown. The outer Group shows the Fetch Configuration for the remote that is associated with the current branch (in our case, "origin" as shown in the Group text).

The URI field can be used to add/change the fetch URI.

The RefMapping Group allows specification of one or several RefSpecs (see Refspecs) for Fetch.

The "Add" button will open a small wizard that helps in the creation of the RefSpecs. You can also paste a RefSpec from the clipboard into the list.

Clicking on the "Advanced" control will show/hide an "Edit (Advanced...)" button that allows for more complex RefSpec editing similar to the Fetch Wizard.

The buttons in the lower button bar allow you to save your changes and do the fetch immediately, save the changes without fetching, dry-run (fetch without saving the configuration), revert your changes, and Cancel.

Direct Fetch

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

Fetch Wizard

The most powerful (but also most complex) 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. The Finish button will be enabled if the Fetch Specification for this remote is configured properly (i.e. has at least one URI and a ref spec.

Egit-0.9-fetch-wizard-source-page.png

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

Egit-0.9-fetch-wizard-source-url-page.png

Fetch Ref Specifications

See also Refspecs for more explanations.

Click Next
Click Add all branches spec

Egit-0.9-fetch-wizard-refspec.png

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

Egit-0.9-fetch-wizard-result.png

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 Branch

  • Right-click on a project in the Package Explorer and select Team > Pull or right-click on a repository in the Git Repositories view and select Pull to pull new changes from the upstream branch your local branch is tracking. This also works if resources are selected from more than one repository.
  • Whenever you create a local branch based on a remote tracking branch EGit can configure a tracking relationship so that subsequent pulls will fetch and then merge or rebase (depending on the configuration of this tracking relationship) the changes from the tracked upstream branch; see Branching for details.

Ad-hoc selection of the upstream branch to pull from is not yet supported by EGit.

Available alternatives 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...



Fetching a change from a Gerrit Code Review Server

If you are working with Gerrit (http://code.google.com/p/gerrit/), EGit allows you to conveniently fetch a change into your local Repository for inspection and/or modification.

Right-click on a project and select Team > Remote > Fetch from Gerrit... or right-click on a Repository node in the Repositories View and select Fetch from Gerrit...

A dialog will appear that lets you select or enter a URI and a change as well as some additional options:

Egit-0.11-fetchChangeFromGerritDialog.png

  • In the URI combo, select or enter the URI that points to your Gerrit instance; the combo will be pre-filled with all URIs defined in any remote of your current Repository; in addition you can type any URI into this field
  • In the Change field, you must enter the full name of a change; you can either take this value from the Gerrit Web UI, use the content assist described below, or build the name using the following pattern:
    "refs/changes/" + (last two digits from change number) + / + (change number) + / + (revision number)
  • In the "Actions to perform after fetch" you can decide what to do after the change has been fetched; you can either create and checkout a branch pointing to the change, create and checkout a tag pointing to the change, or simply checkout the change (thus making HEAD detached); the last option does nothing after fetch, but you will be able to find the commit pertaining to the change at FETCH_HEAD (go to the Repositories View and find FETCH_HEAD under the References node of your Repository, see Inspecting References ).
    The name for the branch or tag is suggested by the dialog but can be overwritten as needed.
    Since deletion of tags is currently not supported in EGit, we suggest to use local branches rather than tags for the time being. Since the Repositories view allows to group branches hierarchically using "/" as hierarchy separator, the suggested names can come in very handy when dealing with large numbers of changes.

Instead of the tedious copy-paste or manual entering of the change ID, the dialog also offers a content assist for the change. Simply press "Ctrl+Space" to activate this (consult the tooltip that appears when hovering over the little bulb decorator near the Change field). The Gerrit Server will be contacted and all available changes will be fetched and shown in a content assist dialog:

Egit-0.11-ContentAssistGerritChange.png

The list will be filtered with your input in the change field. After selecting the change in the content assist, the Change field will be filled with the correct information.

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:

01-TextDecorations.png

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:

03-ExampleDecoration.png

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:

02-IconDecorations.png

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


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. In order to do so, select a Resource (project, folder, or file) in the project explorer or navigator and right-click an action under Compare With.

To analyze the contents of a specific commit you should use the History View which supports this task much better, see task Inspecting Commits.

Compare editor and Git Tree Compare View

If you use any of the submenu actions of Compare With on a single file, a compare editor will be shown, otherwise the Git Tree Compare View will be opened that lets you browse the changes; by double-clicking on a changed file in this view, a compare editor will be opened for this file. An excpetion is the submenu action History..., which opens the History View.

Compare working tree with last commit

The difference between a resource 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 differences between the current working tree and the index (based on the currently selected resource) can be viewed from the context menu Compare With > Git Index.

Comparing Working Tree with a branch, a tag or a reference

  • Select a resource
  • right-click Compare With > Branch, Tag, or Reference...
  • select a branch, tag or reference

Comparing Working Tree with Any Commit

From the project explorer:
  • Select a resource
  • right-click Compare With > Commit...
  • select a commit from the commit graph
From the history view (files only):
  • Select a file in the package explorer
  • right-click Team > 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

  • Select a resource in the Package Explorer
  • click Team > Show in History or Compare With > History... (the latter for files only)
  • in the commit graph select two commits
  • right-click Compare with each other
  • this will open a compare dialog showing the changes between the two selected commits
  • you can also open a Git Tree Compare view by right-clicking Compare with each other in Tree

Comparing Index with HEAD or Any Other Commit

This feature is not implemented yet.


Comparing with Branches (Synchronize)

The difference between the working tree (including not committed changes) and a branch or tag can be viewed by clicking the dynamic menu Team > Synchronize on a project and selecting the Ref you want to synchronize your working tree against. If the Git repository contains multiple Eclipse projects it is sufficient to select one project, the Synchronization View will also include all other projects.

Egit-1.0-synchronize-dynamic.png

If you want to synchronize with a Ref not listed in the dynamic menu click Team > Synchronize > Other.... Then in the Synchronize Wizard click into the destination column of the repository you want to synchronize and select the Ref you want to compare against.

Egit-1.0-synchronize-custom.png

When clicking "Include local uncommited changes in comparison" also local, not yet staged changes and the already staged changes will be shown in comparison.

It is also possible to compare multiple repositories at once. In this case in the Synchronize Wizard select for each repository the Ref you want to compare against.

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:

04-QuickDiffPreferences.png

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

05-QuickDiffInEditor.png

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

06-QuickDiffInEditorPopup.png

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


Inspecting Commits

To inspect a given commit

  • from the context menu in package explorer select Team > Show in History
  • select the commit you want to inspect

EGit-0.7-ViewDiffInResourceHistory.png

View Diff for a Commit

The history view displays the diff in the lower left pane. Selecting a file in the lower right pane scrolls to the corresponding file section of the diff.

Showing the contents of a Commit

The behavior of a double click on a file in the lower right pane depends on the state of the compare mode toggle button. If it's on, a compare editor will be opened which compares the file content in the current commit with the content in the ancestor commit; if it's off, an editor will be opened showing the file content in the current commit.

Committing Changes

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.

Modifying the content

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 :

  • click Team > Add in the file's context menu

Alternatively you may display untracked files in the Commit dialog and check the Show untracked Files checkbox to select them for inclusion into the commit.

Label decorators e.g. in the Package Explorer View show

  • untracked files which are not yet under git version control (marked with "?")
  • files which have been added (marked with "+")
  • modified files (marked with ">" in front of the filename)

For details see Label Decorations.

Here is an example in the Package Explorer for

  • a committed file
  • a file modified in the working tree but not yet staged for the next commit
  • a modified file which modifications have been staged for the next commit
  • a file which has been newly staged for first-time inclusion with the next commit
  • a file which is not under git version control

Egit-0.9-label-decorators.png

Committing

To commit a change click Team > Commit... in the context menu of a resource in the project.

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.

Once you have triggered the commit the Commit Dialog will pop-up

Egit-0.9-commit-dialog.png

Commit Message

In the Commit Dialog you specify 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 (this is indicated by a grey vertical line).

Egit-0.9-commit-dialog-spell-quickfix.png

The commit message text is checked for errors by the Eclipse spell checker. The spell checker can be configured via the Eclipse Preferences > General > Editors > Text Editors > Spelling. Press Ctrl+1 to open quick fixes which may help to fix the spelling errors.

Egit-1.2-commit-dialog-path-assist.png

The commit message editor supports content assist for file names shown in Files section of the commit dialog, which can be activated pressing Ctrl-Space.

Footer Tags
In the last paragraph of the commit message optional footer tags may follow :

Bug: 3176
Change-Id: I267b97ecccb5251cec54cec90207e075ab50503e
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

  • 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
  • Gerrit Code Review uses the Change-Id: 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 Compute Change-Id for Gerrit Code Review; the ID will be generated on commit, until then a null Change-Id is shown as a placeholder. With the egit configuration parameter gerrit.createchangeid set to true the corresponding checkbox in the Commit Dialog is alway preselected. This parameter can be set on repository level, on system level or on user level. See Repository Configuration for more information.
  • The Signed-off-by: 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 Developer Certificate Of Origin used by the Linux kernel project. If the egit preference Insert Signed-off-by in Team > Git > Commit Dialog is set the corresponding checkbox in the Commit Dialog is always preselected.

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

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.

Note: 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.

Amend example:
Imagine you have committed a change to a file containing a typo

EGit-Typo.png

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

EGit-Corrected.png

then open the Commit Dialog again and select the option Amend previous commit.

Egit-0.9-commit-dialog-amend.png

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.

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.

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.


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 click Replace With > File in Git Index.

Replace with HEAD

This feature is currently not available on single file level. You can use Reset to with option hard 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.

Revert using quickdiff

The quickddiff feature can be used to revert individual changes to a file. You can revert by line, block (se range of changes lines) or selection. Select all text and then Revert selection to revert a whole file.

Reverting changes introduced by a specific commit

Changes which are introduced by a given commit can be reverted by an automatically created new commit on top of the currently checked out commit. The commit which is to be reverted does not have to be checked out for that.

Select the commit in the History View, open the context menu and select Revert Commit. This reverts the changes that the selected commit introduces by creating a new commit on top of the currently checked out commit.

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 entire 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 three ways:

  • Select Team > Reset... on a project. In the dialog select HEAD or your current branch and switch the radio button to hard.
  • Right click and select Reset... on any branch or tag in the Repositories view. This opens a dialog which lets you decide on the reset type. Choose hard here.
  • Open the context menu on the HEAD commit in the history view and select Hard Reset.


Branching

Checking out an existing Branch

From the team menu on a project node:

  • Select Team > Switch To... and select a branch name from the list

If there are too many branches the list does not show all of them. In this case

  • Select Team > Switch To... > Other...
  • On the dialog, select a branch, a tag or a Reference
  • Click Ok

From the Git Repositories View

  • Select Checkout on a branch node

or

  • Double Click on a branch node

From the History View

  • Select Checkout on a commit which has a branch label
  • If more than one branch point to the commit a dialog will let you decide which branch to check out.

Creating a New Local Branch

This is always done with the Branch Creation dialog. The newly created branch can optionally be checked out by selecting a check box on the dialog.

From the team menu on a project node, based on a branch, a tag or a Reference:

  • Select Team > Switch To... > New Branch....
  • On the dialog, select a branch, a tag or a Reference.
  • Click Create Branch....
  • The Branch Creation dialog will be opened.

From the Repositories View, based on a branch, a tag or a Reference:

  • Select Create Branch... on the "Branches" node or on any "Branch", "Tag" or "References" node.
  • The Branch Creation dialog will be opened.

From the History View, based on a given commit:

Renaming an Existing Branch

  • Open the Git Repositories View
  • Select the branch you want to rename
  • Click Rename Branch...
  • Enter the new branch name and click OK

Deleting Branch

  • Open the Git Repositories View
  • Select the branch you want to rename
  • Click Delete Branch

Branch Creation Dialog

There are several actions available to create a local branch. All these actions use the Branch Creation dialog:

Egit-0.11-BranchCreationDialog.png

The combo in the upper part allows to select the branch or commit the new branch shall be based on. Typically, this is a remote tracking branch, but it could be any branch or commit in the repository.

The "Pull Strategy" group allows to override the default setup for the "upstream configuration" which is helpful when fetching and pushing, but particularly when pulling. Depending on the selected option the following configuration can be chosen:

  • Rebase: When pulling, new changes will be fetched from upstream and the remote tracking branch will be updated. Then the current local branch will be rebased onto the updated remote tracking branch
  • Merge: When pulling, the changes will be fetched from upstream and the remote tracking branch will be updated. Then the current local branch will be merged with the new changes. This is the default if the new branch is based on a remote tracking branch (but this default may be overriden by specific repository configuration)
  • None: When pulling, no specific upstream configuration will be done for the new branch; however, if a default remote exists (a remote with name "origin", pull will try to use the configuration of this remote; this is the default if the new branch is not based on a remote tracking branch

You may view and edit the upstream configuration in the repository configuration.

EGit also supports the git configuration parameter branch.autosetuprebase, set it to always if you want to use the rebase pull strategy by default. If you set this in the repository configuration this is used for all local branches created based on a remote tracking branch in this repository, if you set it in your user configuration it will be used for all your repositories.

In the lower part, you can decide whether the new branch shall be checked out immediately.

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

You have two places where you can trigger the merge:

  • from the team menu
  • from the Git Repositories View

Starting merge from the team menu

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

Now the merge dialog opens:

MergeDialog.png

On the dialog, select a branch or a tag you want to merge with your current branch.

Starting merge from the Git Repositories View

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 Merging a Branch or a Tag for further details.

Possible merge results

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. 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 Resolving a merge conflict for further actions in case of merge conflicts).
Merge Result dialog

The result of a merge is summarized in a dialog:

MergeResultMerged.png

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.

On the second line you see the new HEAD commit in case of a successful merge (Already-up-to-date, Fast-forward or Merged).

In the table you see the commits which were merged.

Resolving a merge conflict

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 http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented for more details).

Egit-0.10-merge-conflict.png

Using Merge Tool

  • select the top level resource showing the red conflict label decorator
  • click Team > Merge Tool
  • select the merge mode Use HEAD (the last local version) of conflicting files" and click OK

Egit-0.10-select-merge-mode.png

  • the merge editor opens showing the working tree version in the left pane and the version to be merged in the right pane

Egit-0.10-merge-tool.png

  • edit the working tree version until you are happy with it
  • Team > Add the merged resource to mark the conflict as resolved
  • commit the merge commit via Team > Commit

Manual conflict resolution

To resolve a conflict you have to do the following steps:

  • Navigate to the conflicting resource
  • Edit the content of the conflicting resource
  • Tell EGit that the conflict is resolved with Team > Add
  • Commit the conflict resolution with Team > Commit

Finding conflicting files

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.

Conflicts.png

Editing conflicting files

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 http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented for more details).

Open the file in an editor, edit the content and save the editor.

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.

Adding conflict resolution to the git index

Once you are finished with editing a file select Team > Add 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.

When you have resolved all conflicts the textual repository label decoration changes to "Merged". There are no conflict markers anymore.

ResolvedConflicts.png

Committing a merge

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.

Select Team > Commit... anywhere in the navigation tree. The commit dialog opens with a slightly different look compared to a normal commit:

  • The Commit message area is prefilled with a standard merge commit message.
  • It is not possible to amend a previous commit.
  • It is not possible to add untracked files.
  • it is not possible to uncheck the checkboxes. This guarantees that all resolved conflicts are committed.

After pressing the "Commit" Button the merge is completed.

Aborting Merge

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.

The hard reset can be done from the team menu, the Git Repositories View or the History View. See Revert all local and staged changes for more details.


Rebasing

Rebase Introduction

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

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:

          A topic
         /
    D---E master

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

          A---B---C topic
         /
    D---E---F---G master

Now, in order to incorporate the changes in "master" into "topic", a Rebase of "topic" onto "master" would produce

                  A'--B'--C' topic
                 /
    D---E---F---G master


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.

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.

Rebase, A Simple Example

Let's have a look at some simple example: we have a text file "FamousWords.txt" which initially might have some content like

Chapter 1
Once upon a time...

Chapter 2
To be or not to be

Now, in "topic", two commits are created, the first one adding a French translation to Chapter 2, and another one adding a German translation:

After first change in "topic":

Chapter 1
Once upon a time...

Chapter 2
To be or not to be
Être ou ne pas être

After second change in "topic":

Chapter 1
Once upon a time...

Chapter 2
To be or not to be
Être ou ne pas être
Sein oder nicht sein

At the same time, the file was changed in "master" by adding two commits adding French and German translations to Chapter 1:

Chapter 1
Once upon a time...
Il était une fois
Es war einmal

Chapter 2
To be or not to be

The commit history looks like this:

EGit-0.10-MergeDemoHistory.png

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

The result is a merged version of "FamousWords.txt":

Chapter 1
Once upon a time...
Il était une fois
Es war einmal

Chapter 2
To be or not to be
Être ou ne pas être
Sein oder nicht sein

and a commit history with the commit history of "topic" on top of the current "master":

EGit-0.10-MergeDemoHistoryAfterRebase.png

The Real World: Rebase Conflicts

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

  • resolve these conflicts manually,
  • skip the current commit, or
  • abort the rebase completely


If Resolve Conflicts 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.

If Skip was chosen, the conflicting changes will be reverted and the next commit in the chain will be applied.

If Abort 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.

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:

                  A'--C' topic
                 /
    D---E---F---G master

Starting Rebase

Rebase is available in the Git Repositories View. On Repository nodes, Rebase... 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), Rebase immediately rebases the currently checked out branch onto the selected branch:

EGit-0.10-StartRebaseFromRepoView.png

Rebase Confirmation Dialog

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.

Rebase Conflicts

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

  • Start the Merge Tool to resolve the conflicts manually
  • Skip the current commit
  • Abort the rebase altogether
  • Do nothing (return to the workbench), this is equivalent to hitting "Escape":

EGit-0.10-RebaseConflictDialog.png

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.

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.

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.

The Merge Tool can also be started from the corresponding entry in the Team menu.

Aborting Rebase

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.

Rebase Limitation

The current EGit rebase implementation 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.

Cherry Picking

Cherry-pick Introduction

A given commit C on branch stable-1.0 contains a set of changes you would like to integrate in your current development on branch master.

                  A--B--C--D stable-1.0
                 /
    D---E---F---G master HEAD

Cherry-pick the commit C to create a new commit C' on top of the head commit of the currently checked out branch master. C' will then contain the changes performed in C applied onto the HEAD of the currently checked out branch master.

                  A--B--C--D stable-1.0
                 /
    D---E---F---G--C' master HEAD

Cherry-pick Example

You are currently working on branch "feature2" (HEAD). There is a commit "feature 1" in another branch.
You want to integrate the changes performed by commit "feature 1" into your current development on branch "feature 2".

  • In the History View select commit "feature 1" and click Cherry-pick:

CherryPick1.png

  • As result you get a new commit "feature 1" at the tip of your current branch "feature" containing the changes of "feature 1":

CherryPick2.png

  • Cherry-picking can encounter conflicts. In this case conflict markers are rendered into the affected sources:

CherryPick3.png

  • Resolve the conflicts by editing the corresponding sources as described in Resolving a merge conflict
  • Team > Add the files you edited to mark the conflicts resolved
  • Commit the changes using Team > Commit


Tagging

Creating a Tag

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

Egit-0.8-tag-create.png

  • 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

Tags can also be created in the history view: select a commit and execute Create Tag... in the context menu. The tag will be created on the selected commit:

TagCreation.png

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.

Egit-0.8-tag-replace.png

  • 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

Deletion of tags

In order to delete a tag, select the tag to be deleted and click Delete Tag.

Note: it's a bad practice to delete tags which have already been published on a public server, some Git servers even disallow tag deletion to ensure traceability for releases which are usually tagged. Also see the section "On re-tagging" in the Git reference documentation of the tag command.

Light-weight and Signed Tags

Light-weight tags are shown in the Repositories View as well as in the Create Tag dialog, but can not be edited. Tags are shown with a blue icon in the Repositories View, lightweight tags are decorated with a dark blue "L".

Egit-1.1-tags.png

In the History View, tags are shown as yellow labels.

Egit-1.1-tags-history.png

Signed tags are not yet supported by EGit, use command line git tag or git tag -s instead.


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:

Egit-0.0-create-patch-menu.png

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:

Egit-0.0-create-patch-dialog.png

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.

Binary diffs are currently not produced.

Applying Patches

Currently EGit isn't able to apply patches in git format. It is possible to apply patches using the standard Eclipse (unified diff) format using Team > Apply Patch.... Git patches may contain non-standard extensions for rename and binary diffs. The current version of EGit does not generate these extensions.


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
Team > Show in Repositories View

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. Adding a Repository from the Local File System manually
  2. Cloning a Repository and having the cloned Repository added to the view automatically
  3. Creating a Repository on the Local File System
  4. Adding a Repository by pasting a Git Repository path to the view

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:

RepoMgrAddRepositoryIcon.png

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:

Egit-0.11-import-projects-add-dialog.png

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:

RepoMgrCloneRepositoryIcon.png

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

Creating a Repository

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 Create a new Git Repository button from the view's toolbar:

RepoMgrCreateRepositoryIcon.png

A dialog will appear which lets you choose a directory:

RepoMgrCreateRepositoryDialog.png

If you select the checkbox Create as Bare Repository the new repository will not have a working directory. You then can only add content by pushing changes from another repository.

Adding a Repository using Copy and Paste

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 .git folder) to the clipboard, then open the context menu on the view panel:

RepoMgrPasteRepositoryPath.png

or click 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:

RepoMgrViewWithRepos.png

Removing Repositories

Removing a Repository from the Repositories View

In order to remove a repository from the Repositories View select a repository and click "Remove Repository"

Egit-0.10-RemoveRepository.png

Deleting a Repository

In order to delete a repository, select it in the Repositories View and click "Delete Repository".

Egit-0.10-DeleteRepository.png

Then confirm that you want to delete the repository

Egit-0.10-ConfirmRepositoryDeletion.png

and decide if you want to delete projects contained in the repository from the Eclipse workspace.

Egit-0.10-ConfirmProjectRemoval.png


Structure of the Git Repositories View

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

Egit-0.11-RepoViewTopLevel.png

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 "References" node lists other references which are not branches or tags, most notably the "HEAD" and "FETCH_HEAD" symbolic references (see Git References).

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:

Egit-0.11-ImportProjectsFromRepoView.png

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 in Use the New Projects Wizard.

Branch and Tag Support

The "Branches" node allows to create, browse, checkout and delete local and remote branches. The "Tags" node allows to browse and check out tags. Both the "Branches" node and the "Tags" node allow to merge the branch or tag into the currently checked out branch and also to synchronize with the currently checked out branch.

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:

RepoMgrBranchesAndTags.png

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 the Branch Creation Dialog. The wizard is opened by right-clicking on the "Branches", the "Local Branches" on any "Branch" and "Tag" node).

Branch deletion is done using the corresponding context menu entry.

Rebasing

You can trigger rebasing of the currently checked-out branch onto another branch by right-clicking Rebase on any (local or remote tracking) branch node.

Merging a Branch or a Tag

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 Merging for further details of the merging features.

  • When you select any branch node other than the currently checked out branch or any tag node, use Merge to directly trigger a merge into the currently checked out branch.
Synchronizing with a Branch or a Tag

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

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:

RepoMgrCheckedOutBranch.png

Resetting to a Branch or a Tag

Right click and select Reset... on any branch or tag. This opens a dialog which lets you decide on the reset type. See Resetting you current HEAD for further details.

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

Inspecting References

The References node displays some References other than branches and tags (the list is dynamic and depends on the current state of the Repository):

Egit-0.11-RepoViewReferencesNode.png

If the Reference is symbolic, i.e. points to another Reference, the name of the target reference is shown, followed by the object ID of the reference's target. If the Reference is not symbolic, only the object ID is shown.

In the example above, HEAD is a symbolic Reference pointing to branch "refs/heads/master" (i.e. branch "master" is checked out", while FETCH_HEAD points directly to commit 226a7f... .

The following actions are available on right-clicking on a Reference: Checkout (unless the Reference is already checked out) and Create 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:

RepoMgrOpenTextEditor.png

Alternatively, files can be opened by dragging them from the Working Directory to the Editor Area.

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. With a drop down box (left red box in the screen shot) you can switch between the display of the Repository Configuration, the Global Configuration and a view which aggregates both. If the view displays the Repository Configuration or the Global Configuration you can open an editor dialog with the Edit button (right red box in the screen shot). The editor dialog has the same functionality as the preference page Team > Git > Configuration.

In the Git Repositories view, there is a Properties action in the context menu, which will open a configuration dialog allowing to edit the Repository Configuration. Here, key value pairs can be added, changed or deleted. The Open button allows to open the Repository Configuration file in a text editor.

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:

RepoMgrRemoteConfig.png

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:

RepoMgrSimpleFetch.png

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.

The "Fetch" node contains a so called fetch specification and the "Push" node contains a so called push specification.

A default fetch specification is created when the repository is cloned. You can edit the fetch specification with the menu entry Configure Fetch.... 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 Fetch Ref Specifications.

You can create or edit a push specification with the menu entry Configure Push.... 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 Push Ref Specifications.

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:

RepoMgrNewRemote.png

If the Configure Fetch checkbox was selected, the next wizard page will ask for the URI of the Repository to fetch from:

Egit-0.9-repo-view-createRemoteWizardFetch.png

Click Change... 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 Fetch Ref Specifications about the details.

If the Configure Push 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 Add.... to add URIs to the list using the same dialog as above. You can remove URIs by marking them in the list and hitting Remove. 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 Next button is enabled, even though there is no Push URI in the list:

Egit-0.9-repo-view-createRemoteWizardPush.png

The next step is to define the Remote Specification for the push URIs. See Push Ref Specifications about the details.

Upon completion, the new Remote configuration will be visible:

RepoMgrRemoteCreated.png

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:

RepoMgrRefresh.png

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:

RepoMgrLinkWithSelection.png

Link with Editor

If the Link with editor toggle is enabled, the file or folder corresponding to the currently active editor will be displayed automatically:

RepoMgrLinkWithEditor.png

Hierarchical Branch Layout

If the Hierarchical Branch Layout toggle is enabled, branches will be shown in a hierarchical layout using slash (/) as hierarchy separator:

RepoMgrHierarchicalBranchLayout.png

This can be helpful for organizing large numbers of branches.

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:

RepoMgrBareRepository.png

Bare repositories are only changed by pushing changes to them.

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.

Showing Repository in Related Views

Show in History

The command Show in > History will open the History View showing all changes in the selected repository.

Show in Reflog

The command Show in > Reflog will open the Git Reflog view showing the Git reflog of the selected repository.

Show in Properties

The command Show in > Properties will open the Properties view showing the properties of the selected repository.


Working with Tasks

Since EGit 0.11 a first integration with Mylyn is available to support working with task repositories.

Installation

You need to install the feature "EGit Mylyn" to use the EGit Mylyn integration. This requires also Mylyn to be installed.

Commit Message Template

  • Configure the Mylyn commit message template under Preferences > Tasks > Team and edit Commit Comment Template.
  • Use the following variables as well as any text to alter the commit message.
    • connector.task.prefix, repository.kind, repository.url, task.assignee, task.cc, task.description, task.id, task.key, task.keywords, task.lastmodified, task.notes, task.priority, task.product, task.reporter, task.resolution, task.status, task.summary, task.type, task.url, task.completiondate, task.creationdate, task.reminderdate

Egit-0.11-configure-commit-template.png

  • Before committing your change activate the corresponding Task using the Mylyn UI.

Egit-0.11-activate-task.png

  • When launching the commit dialog EGit will pre-populate the commit message using the commit message template.

Egit-0.11-commit-using-template.png

See the Mylyn User Guide for more information how to work with tasks.

Viewing Commits

The Egit commit viewer allows commits to be opened in the Eclipse editor area.

The EGit commit viewer displays the following commit information:

  • Commit tab
    • Links to open parent commits
    • Author
    • Committer
    • Message
    • List of tags pointing to this commits
    • List of branches that the commit exists on

Commit-editor-commit-page.png

  • Diff tab
    • Text viewer with the output of the file differences
    • The colors used in the viewer can be configured from the Preferences > General > Appearance > Colors and Fonts > Git folder

Commit-editor-diff-page.png

  • Notes tab
    • All Git notes for the commit

Commit-editor-notes-page.png

Tagging a commit

  • Select the Create Tag icon from the commit viewer toolbar
    • The Tag dialog will open allowing you to create a tag from the commit.

Creating a branch from a commit

  • Select the Create Branch icon from the commit viewer toolbar.
    • The Branch dialog will open allowing you to create a new branch from the commit

Checking out a commit

This checks out the commit displayed in the commit viewer. The commit will be checked out and HEAD will become detached.

Cherry picking a commit

Applies the change introduced by the commit displayed in the commit viewer on top of the currently checked out commit or branch.

Opening the commit viewer

The commit viewer can be opened from the following places:

Searching for commits

EGit supports searching for commits.

Git Search page

Commits can be searched from the Git Search tab in the standard Eclipse Search dialog.

This dialog supports searching for text or patterns present in the different fields of a Git commit such as the message, author line, committer line, and the SHA-1 ids of the commit, its parent(s), and the tree associated with it.

Git-search-page.png

Browsing Search Results

Commit search results are displayed in the standard Eclipse Search view. Results are grouped by repository when in Tree mode. Double-clicking a commit from the Search view will open it in the commit viewer.

Git-search-results.png

Launching Git Search

The Git Search page can be opened by selecting the Git Search option from the Search drop-down on the Eclipse toolbar.

Git-search-dropdown.png

Open commit dialog

EGit 1.0 has an Open Git Commit dialog similar to the Mylyn Open Task and core Open Resource dialogs. The dialog searches every configured Git repository for the branch, tag, or commit SHA-1 entered into the filter box and displays the matching commits.

Git-open-commit.png

The dialog can be opened by selecting the Open Git Commit button on the Eclipse navigation toolbar.

Git-open-commit-toolbar.png

Finding the author of each line in a file

EGit 1.0 supports showing git blame information inside the editor ruler.

Selecting the Team > Show Annotations action on file selections will open the editor and display an annotation ruler with commit and author information for each line in a file. Hovering over the ruler will display a pop-up showing the commit id, author, committer, and the commit message.

The look and feel of the blame annotation editor ruler can be configured from the Revisions sub-menu available from the ruler context-menu.

Egit-1.0-blame-ruler.png

Selecting the SHA-1 hyperlink from the popup will open the commit in the commit viewer.

Back to the top