EGit/User Guide

Getting Started/Adding a project to version control

If you're new to Git or distributed version control systems generally, then you might want to read Git for Eclipse Users first.

Create a new Java project "HelloWorld"

Select "File" -> "Team" -> "Share Project"

Select repository type "Git" and click "Next"

To configure the Git repository select the new Eclipse project HelloWorld

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

Click "Finish" to close the wizard.

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

Select "Team" -> "Add to version control" on the project node

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

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

bin

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

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

Select "Team" -> "Commit" from the context menu on the project

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

Note that the decorators of the committed files changed.

Select "Team" -> "Show in Resource History" from the context menu to inspect the history of a resource

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

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

Creating a new empty Git Repository

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

Creating a Git Repository for multiple Projects

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

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

Importing Projects from existing Git Repositories

In order to work with the contents of a Git Repository in the Eclipse workbench, the files and folders contained in this repository must be imported in the form of projects. In principle, this import step can be done using the generic "New Project" or "Import..." wizards, since the working directory of a Git Repository is just a normal directory in the local file system. However, the newly created projects would still have to be shared manually with Git. The "Import Projects from Git" wizards integrates project import and sharing and also offers some extra convenience.

Starting the import wizard

The wizard is started using

Import -> Git -> Projects form GIT

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

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

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

Cloning or adding Repositories

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

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

Cloning a Repository

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

Adding a Repository

The second option is useful when you already have a Repository in your local file system, for example because you have cloned it earlier, you created it from scratch or you copied it from somewhere else. Clicking on the "Add..." button next to the Repository list, a dialog is displayed which allows you to enter a directory in your local file system. Press "Search" to trigger a scan for Git Repositories contained in this directory. If Git Repositories are found, they will be shown in a list and you can select Repositories to add:

After successful completion, the Repository list should contain some Repositories:

Selecting a Repository from the list

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

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

Method for importing Projects

Import Existing Projects

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

Limiting the scope for project import

In this case, the directory tree at the bottom is active. You can limit the search for .project files by selecting a folder in this tree, otherwise the complete working directory of the Repository will be scanned. On the next page, a list of the found projects (if any) will be shown. This is very similar to the generic "Import Existing Projects" wizard, but has some additional filtering capabilities:

Use the New Projects wizard

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

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

Import as General Project

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

By default, the newly generated project will point to the working directory of the Repository. By selecting some folder from the directory tree at the bottom, you can have the project generated for that folder.

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

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

Method for sharing imported Projects

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

Try to share newly created projects automatically

This is the recommended option: the wizard will automatically detect newly created projects and find the corresponding Repository automatically. No user interaction is required. If automatic sharing fails, the projects will simply remain unshared. You can share them any time manually.

Share new projects interactively

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

Do not share new projects

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

Working with remote Repositories

Cloning remote Repositories

Using the Git import wizard you can clone remote repositories using different transport protocols. Additionally you may import existing Eclipse projects into your workspace and share the projects with the Git team provider.

Start the import wizard by navigating to File -> Import... and choose "Git Repository".

Repository Selection

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

• URI - The complete URI of the remote repository or the path on the file system. This field is automatically synchronized with the other fields.
• Host - The name of the remote host or empty if cloning from the file system.
• Repository Path - Path to the remote repository or on the file system.
• Protocol - One of the protocols described below.
• Port - Port number.
• User - The user name used for authentication.
• Password The password used for authentication.

The following protocols are supported:

• git - The most efficient built-in git protocol (default port 9418). This protocol doesn't provide authentication. Typically used for anonymous read access to the repository.
• git+ssh - Git over secure shell (SSH) protocol. Typically used for authenticated write access to the repository.
• sftp - SSH File Transfer Protocol
• http - Hypertext Transfer Protocol can be tunneled through firewalls.
• https - Hypertext Transfer Protocol Secure can be tunneled through firewalls.
• ftp - File Transfer Protocol
• file - File system access to the repository.

Branch selection

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

Local Destination

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

• Directory - The directory which will contain the Git repository. It will be created by the wizard if it does not yet exist.
• Initial branch - Choose here which local branch will be created and checked out.
• Remote name - Define a name for the remote repository. The default is "origin".
• Import projects after clone - If checked, the repository is searched for eclipse projects. In this case the finish button is disabled and the wizard continues with the project selection. If not checked, the finish button is enabled.

Note that if you press "Next" on this page the repository will immediately be cloned by the wizard. This is necessary to find the eclipse projects. If you end the wizard with the "Cancel" button later on you will be asked if the clone should be deleted.

Import Projects

On the next page the Eclipse projects found in the cloned repository are presented.

• Enable Git Team operations on imported projects - If this checkbox is selected the imported project are shared with the EGit Team provider. If it is not checked, the Team operations can still be enabled later on by choosing the project in eclipse and selecting Team -> Share Project...

Pushing a Local Repository to GitHub

Create Local Repository

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

Create Repository at GitHub

• create a new repository at GitHub

• you get a fresh clone URL for this new repository

Eclipse SSH Configuration

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

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

Push Upstream

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

• click "Next" and on first connection accept GitHub's host key

• enter your SSH key's passphrase

• click button "Add all branches spec"

• click "Next" and click "Finish" to confirm the push

• the next dialog shows the result of the push operation

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

Pulling (merge or rebase) new changes from upstream

This is not yet available. Available alternatives currently include:

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

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, he default for a dirty resource is a > on the left side of its name.

These are the default settings:

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

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

The "branch" variable displays the name of the currently checked out branch. If no branch is checked out, the decoration shows the shortened name of the commit (first seven characters followed by ellipsis). If tags and/or remote branches are pointing to this commit, a "best guess" heuristic is applied to also show this information: tags take precedence over remote branches, if several tags apply, the newest one is displayed; if there are several remote branches or tags have no modification date, then alphabetic sorting is applied and the last one is shown. Example: the checked out commit "e49f576..." refers to tag "v.0.7.1" of repository "egit":

Icon Decorations
Icon decorations appear on the lower left corner of the icon label. They can be configured on the Preferences dialog under Team -> Git -> Label Decorations on the tab "Icon Decorations".

These are the default decorations:

• dirty (folder) - At least one file below the folder is dirty; that means that it has changes in the working tree that are neither in the index nor in the repository.
• tracked - The resource is known to the Git repository.
• untracked - The resource is not known to the Git repository.
• ignored - The resource is ignored by the Git team provider. Here only the preference settings under Team -> Ignored Resources and the "derived" flag are relevant. The .gitignore file is not 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 are added to the index. Not that adding to the index is possible at the moment only on the commit dialog on the context menu of a resource.
• partially-staged - The resource has changes which are added to the index and additionally changes in the working tree that are neither in the index nor in the repository.
• added - The resource is not yet tracked by but added to the Git repository.
• 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. This setting can be switched on with the menu action Team->Assume unchanged (or on the command line with git update-index --assume-unchanged).

Commit dialog

A summary of the status of all changed tracked files can be seen on the commit dialog. When you doble click on a file the changes to be committed are displayed in a compare dialog. As Egit always commits the content of the working tree (commit -a) the compare dialog will compare the working tree with the last commit.

Comparing Content

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

Compare working tree with last commit
The difference between a file in the current working directory and in the last commit in the current branch can be viewed from the context menu "Compare With" -> "HEAD revision".
This feature is also implemented in the Commit dialog. Double clicking on an entry opens a compare dialog.

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

Compare working tree with any commit

• Select a file in the package explorer
• from the context menu select "Show in" > "History" or "Team" > "Show in Resource 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

Compare two commits with each other

• Select a file in the package explorer
• from the context menu select "Show in" > "History" or "Team" > "Show in Resource History" or "Compare With" -> *In the commit graph select two commits
• from the context menu select "Compare with each other"
• this will open a compare dialog

Compare index with last commit
This feature is not implemented yet.

Quickdiff

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

You then will see the difference annotation on the left hand side of the editor:

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

Per default, the comparison is against the HEAD. You can determine the version you are comparing to, the so-called quickdiff baseline, from the context menu of a commit in the history view (Team -> Show in Resource History). Here are three menu entries:

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

View Diff for a Commit

To display the diff for a given commit

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

Committing changes

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

Modifying the content

If you have a project which is already shared with Git then doing the actual modifications is easy: just modify or delete files either within Eclipse or even directly on the file-system. There is no need to "check-out" files or to tell Git in advance about these operations. Only when you add new files you should be cautious: new files which should be version-controlled have to be explicitly announced to git through the files context-menu.

You can see for example in the Package Explorer View which files have been added (file icon marked with "+") and which files have been modified (file marked with ">" in front of the filename). Here is an example of one added and one modified file in the Package Explorer:

Committing

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

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

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

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

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 which are derived (e.g. the bin folder in java projects) will not be shown here. If you have no other changes in your repository than such untracked files the checkbox "Show untracked Files" is selected by default.

Amending Commits

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

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

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

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

The commit message of your previous commit (the one which you want to replace) is filled into the "Commit Message" field. This gives you the chance not only to correct errors in the content of the version-controlled files but to also correct errors (e.g. typos) in the commit message describing your change.

As an alternative to amending you could just commit the corrected version as a subsequent commit. But the first commit containing the typo is of no use to anybody else and in order not to clutter the history of your project with unneeded commits you may decide to use the amend feature.

Be aware that amending commits which are already published to other repositories may cause trouble. Once you have pushed a commit to a remote repository or your local repository was cloned by somebody else you should be very careful whith amending commits. In this case publishing a second commit which corrects the first one is probably a better solution.

Signing off commits

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

Reverting Changes

Reverting changes in the working tree

Replace with File in Git Index

Changes which are not yet committed and not yet staged can be reverted for a set of selected files. Select the file(s) in the Package Explorer or an analogous view and select

Replace with HEAD

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

Resetting your current HEAD

Git offers the possibility to reset the HEAD of the current branch to any other commit. It optionally resets the index and the working tree to match that commit. Note that this action affects all files and folders in the whole repository.

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

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

Reset to specific branch or tag

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

Reset to a specific commit

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

Revert all local and staged changes

This can be done as a special case of reset. If you reset to the current HEAD (normally the last commit on your branch) with the option "hard" you overwrite the working tree and the index with the content of the HEAD. You can do this in two ways:

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

Patches

Creating Patches

"A patch is a piece of software designed to fix problems with, or update a computer program or its supporting data" (wikipedia). A patch file contains a description of changes of a set of resources which can be automatically applied to another eclipse workspace or git repository.

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

Create a Patch from a Commit

This is the most common use case for a distributed versioning system. A developer commits a change on a local feature or bugfix branch and wants to export this change into a patch file.

It can be done from the history view:

The patch file will contain the difference between the commit and its parent in the history view. Note that the filter of the history view applies also for patch creation.

Patch Wizard

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

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

On the second page you can change the patch format.

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

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

Applying Patches

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

Managing Repositories

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

This view can be opened using the menu path

	Windows -> Show View -> Other... -> Git -> Git Repositories

It is also part of the "Git Repository Exploring" perspective available using menu path

	Window -> Open Perspective -> Other... -> Git Repository Exploring

If you already have projects in your workspace which are shared with a Git Repository, you can use

	<Context menu> -> Show In... -> Git Repositories

on any resource to open the view:

Adding Repositories to the Git Repositories View

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

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

Cloning a Repository

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

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

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

Adding a Repository manually

You can add a Repository from your local file system to the Git Repositories View without cloning it. This can be helpful if you are setting up a new Eclipse workspace and want to re-use your Git Repositories. Use the "Add an existing Git Repository" button from the view's toolbar:

A dialog will appear prompting you for a directory of your local file system. After selecting the correct directory, you can hit the "Search" button to see a list of Git Repositories in this directory. You can then select some or all found Repositories and add them to the view using "Ok":

Adding a Repository using copy and paste

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

or simply perform Edit->Paste from the main menu (or the corresponding keyboard shortcut). If the clipboard content is not suitable, an error popup sould be displayed, otherwise the added Repository should appear automatically.

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

Structure of the Git Repositories View

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

The root node represents the Repository itself. The node text indicates the name of the Repository and it's location in the local file system. The "Branches" and "Tags" nodes allow browsing and manipulation of tags and branches. The "Symbolic References" node lists other references which are not branches or tags, most notably the "HEAD" symbolic reference.

The "Working directory" node displays the location and structure of the working directory on the local file system (only in case of a development, or non-bare Repository, for bare Repositories, this node is always a leaf).

Finally, the "Remotes" 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, it's 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 independent of the clone operation.

The "Import Projects..." context menu is available on the "Repository" node as well as on any "Folder" node within the "Working Directory" node and the "Working Directory" node itself:

The rationale for offering the "Import Projects..." action on several nodes is that some of the wizards used for importing projects can take the file system directory into account, for example the "Import Existing Projects" wizard. If the import is started from the "Repository" or the "Working Directory" node, the working directory of the repository is set as context, otherwise the directory corresponding to the currently selected "Folder" node.

The details of project import are discussed elsewhere.

Branch and Tag support

The "Branches" node allows for browsing, creation, deletion and checking out of local and remote branches. The "Tags" node allows for browsing and checking out of tags. For better readability, branches are organized in two sub-nodes for local and remote branches, respectively, and only the shortened names are displayed, e.g. instead of "refs/heads/master" you would find an entry "master" under the "Local Branches" node, while instead of "refs/remotes/origin/master" would be shortened to "origin/master" under the "Remote Branches" node. Similarly, tag names are shortened by dropping the "refs/tags/" prefix:

Check-out of branches and tags

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

Creation and deletion of branches

Local branches can be created using a simple wizard. After selecting the corresponding context menu entry (available on the "Branches", the "Local Branches", and on any "Branch" node), you are asked to enter a source branch and a name for the new branch. Depending on whether you have called the wizard from a "Branch" node, the source branch dropdown will be pre-selected with either the selected branch or the currently checked-out branch:

You can change the source branch using the dropdown. By default, the newly created branch will be checked out after creation. Deselect the corresponding checkbox on the wizard if you don't want this to happen.

Branch deletion is done using the corresponding context menu entry.

Determine which branch is checked out

There are two ways to determine which branch or tag is currently checked out: the checked out branch/tag node is decorated with a little check mark and the "HEAD" entry under the "Symbolic References" node shows the (full) name of the checked out branch:

"Detached" HEAD

If HEAD is "detached", i.e. is not pointing to a local branch but to a commit, 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.

Browsing the Working Directory

The "Working Directory" node visualizes the local file system structure of the Git Repository. It is also possible to open a text editor on the files:

Also, on all file and folder nodes as well as on the "Repository" node, an option is offered to copy the (file-system specific) path to the clipboard. This is sometimes useful when the path is needed, for example to open a directory using a file browser or to copy and paste Repositories between view instances (see above about how to add Repositories to the view). The "Copy to Clipboard" action is also available using Edit->Copy (or the corresponding keyboard shortcut).

Repository Configuration

Integration with the generic "Properties" view in Eclipse allows for viewing and editing Git Configuration (global and repository-specific configuration). If the "Properties" view is open, it will be updated automatically when a "Repository" node is selected. For convenience, an "Open Properties view" action is provided in the context menu:

Remote Repositories

The "Remotes" node allows for browsing and editing remote configurations. Each remote configuration has a name and either a push specification, a pull specification, or both. If a "Remote Configuration" node or any of its children is selected, the "Properties" view will show a summary of the remote configuration. In this example: there is a remote configuration named "origin" which only has a fetch specification, but no push specification:

Menu actions are provided to add, configure, and remove remote configurations and fetch and push specifications.

Direct Fetch and Push support

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

Note that the fetch or push operation will be executed immediately in an asynchronous job; you will get a confirmation pop-up displaying the fetch result.

Adding a Remote Configuration

This is done using a context menu action on the "Remotes" node. A wizard will be started asking for the name of the new configuration and whether to configure Fetch, Push, or both:

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

Changing Remote Configurations

It is also possible to add, remove, or change fetch/push specifications for an existing remote configuration using the context menu.

Refresh

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

Link with Selection

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

Bare Repositories

"Bare" Git Repositories (as opposed to "development" or "standard" Repositories) have no working directory by definition, so all actions related to the working directory (check-out, project import, browsing the working directory) are not available for such Repositories. The "Bare-ness" of a Repository is visualized on the "Working Directory" node, which is always a leaf:

Removing Repositories from the Git Repositories View

This is offered as a menu action on the "Repository" node. Note that this does not delete the Repository, but just removes the node from the view. If there are projects in the workspace which are located in the working directory of the Repository, the user will be prompted to confirm deletion of these projects from the Eclipse workspace.