Revision as of 14:36, 5 February 2010

Getting Started

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

Adding a project to version control

Select the project node of the project to be added to version control

Execute "Team" -> "Share Project" on the project node

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.

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

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

• enter as source ref: refs/heads/master and as target ref: refs/heads/master and 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 the project name there is additionally the variable "branch". If no branch is checked out the decoration shows the name of the commit.

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.

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 index
The difference between the current working directory and the index can be viewed from the context menu Compare With -> Git Index.

Compare working tree with last commit
This feature is not implemented yet. As a manual workaround you can view the content of the file after your last commit from the History View (Team -> Show in Resource History). Here you can see the differences between a commit and its parent by double-clicking on the entry in the Path-column on the lower right. You also can use Quickdiff (see below) by choose HEAD as quick baseline.

Compare index with last commit
This feature is not implemented yet.(As a manual workaround you can view the content of the file after your last commit from the History View (Team -> Show in Resource History). Here you can see the differences between a commit and its parent by double-clicking on the entry in the Path-column on the lower right.

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.

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.

Be aware that new files you added to the project which have not been explicitly added to version control (see "Modifying the content") will not be listed in the commit dialog and will not be part of the commit. If you are not sure whether you have created such files you may select "Team -> Add to Version Control" on an Eclipse project to add new files in the project to version control.

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