Saturday, May 30, 2015

Git with Eclipse (3) - basic use cases in EGit with local repository

This post introduces indexing files (stage), committing files and reverting changes in local repository with EGit. Here assume the project has already been shared to Git local repository. For how to share a project to Git local repository, please read Git with Eclipse - creating local repository with EGit in Eclipse. All screenshots below are from Eclipse Kepler.

Adding Files to staging area

Staging area is a new concept introduced by Git. Git has three main states of a file: modified, staged and committed. In a centralized version control system, there are only two states which are modified and committed. In Git, staged means that your file is marked in its current version to go into your next commit snapshot. It is useful when you have a major change in your project like adding a new feature. You cannot finish the work in one goal and you also cannot commit half completed work to the repository. In Git, you can stage your completed changes and continue your work. When you finish the whole implementation of the new feature, you can commit your work and all staged files will be committed in one snapshot. The following diagram shows the relationship of the three states.



To add a file into staging area in EGit, right click on the file and select Team -> Add to Index.


Once the file is added into staging area, a plus symbol will appear on the file and all parent folders of the file will have an asterisk symbol indicating it is staged.


EGit also allows to commit files not staged. In this case, those files will be staged and committed at the same time.

Committing Files to local repository 

Similar to centralized version control system, commit is straightforward. Right click on the project and select Team -> Commit... It will open a new dialog. In the upper textbox, you will have to enter a commit message. In the lower part of the dialog, you can select the files you want to commit. All staged files of the project are selected by default and you can also select staged files from other projects. In my example, the staged file from Project1 is selected by default and I can also select the staged file from Project2. Furthermore, if you click on the Show Untracked Files icon, those files not staged will also be displayed. And you are allowed to select those files. Click Commit button and all selected files will be committed to the local repository.


In Git, You can change your previous commit if you realize your previous commit is incomplete or your commit message needs modification. This is different from centralized version control system and it is a very convenient function to correct mistaken commits. To amend previous commit, click this icon on the right top of the commit message textbox. It will not add a new version to your committed files and your comment message in last commit will be overridden. However, this should only be used if the previous commit has not been pushed to a remote repository.

Reverting Changes 

There are several ways to revert changes in Git. Revert the changes in files or revert the changes in project.

Reverting changes in files

If you want to revert changes in one or more files, select the files and right click to popup the context menu. Select Replace With in the context menu, EGit provides several options to revert. Four of them relate to the local repository, HEAD Revision, Git Index, Previous Revision and Branch, Tag, or Reference...


HEAD Revision: This will replace the contents of the file with the HEAD revision. Any untracked changes and staged changes will be lost.
Git Index: This will replace the contents of the file with the contents in the staging area. Any untracked changes will be lost.
Previous Revision: This will replace the contents of the file with previous revision.
Branch, Tag, or Reference...: This enables you to revert your file to any branch, tag or reference revision.

Furthermore, you can use the Compare With to compare your files with any revision and revert changes line by line.

Reverting changes in project

If you want to revert changes in the whole project, right click on the project and select Team ->Reset... in the context menu. The Reset dialog will be popup. In the upper box, you can select any revision you want to reset to. In the bottom Reset type box, there are three types.

Soft (HEAD updated): This will only reset your current HEAD revision to the revision you select in the upper box. If the revision you selected is the same as your current HEAD revision, you will notice there is no change after reset. The untracked changes and staged changes will be retained.

Mixed (HEAD and index updated): This will do a Soft reset and reset the staging area. After Mixed reset, you will notice all your staged files become untracked. You can imagine as all the changes are removed out of staging area, but they still stay in your working directory.

Hard (HEAD, index, and working directory updated): This will do a Mixed reset and reset your working directory. After Hard reset, your working directory will also be reverted to the revision you selected, which means all uncommitted changes will be lost. You should be careful with Hard reset because you cannot bring your changes back.



There are other use cases of EGit in local repository. For a full guide of EGit usage, please refer to https://wiki.eclipse.org/EGit/User_Guide. For how to interact with remote Git repository in EGit, please read Git with Eclipse (4) - pushing local repositories to remote repositories.


Reference:

Sunday, May 24, 2015

Git with Eclipse (2) - creating local repository with EGit in Eclipse

This post describes how to create a local repository using EGit. For how to configure EGit in Eclipse, please read Git with Eclipse (1) - configuration of EGit in Eclipse. All screenshots below are from Eclipse Kepler.

Create Local Repositories

Compare to centralised version control system SVN or CVS, you can easily create local repositories in Git. It enables you to version your work locally before sharing with other people.

Firstly, you need create a project in the workspace. Then right click on the project and select Team-> Share Project...


Select Git as the repository type and click Next.
























In the next window, select your project and click Create button to create a Git repository. You can also tick 'Use or create repository in parent folder of project' to create the repository in the parent folder of the project. But it is not recommended and EGit will not allow if the project is under Eclipse workspace folder like my example in this post. The reason will be discussed later. 

In the popup dialog, specify a directory in Parent  directory. It can be any directory on your disk. But it is a good practice to use the parent directory of Eclipse workspace, because EGit will move the project folder from workspace folder to the repository folder. A new developer might be confused why he could not find the project folder in workspace. By doing this, it is easier to know where is the project folder on the disk. Then give a name of the repository. Click Finish to return to the Configure Git Repository dialog. EGit tells you the projects will be moved from the Current Location to the Target Location in the lower table of the dialog.
























The Path within repository enables you to specify a sub folder inside the repository folder, and the projects will be moved to the sub folder you specified. I leave it blank so the project will be in the repository folder. Then click Finish button to create the repository.

Once the repository is created, you will notice a ">" sign appears next to the question mark icon on the project folder and some files are also have a question mark icon on them. The question mark icon means the project folder and all those files are new in the repository. And the ">" sign tells you there is modification inside project folder. You may also notice there is no question mark on the bin folder. It is because the folder has been added in to .gitignore file. All files and folders specified in .gitignore file will be ignored by Git and will not be shared into the repository. The files to be ignored are typically class files and sometimes the project settings files.






















Now you are ready to commit your project to the local Git repository. For some basic use cases of EGit, please read Git with Eclipse (3) - basic use cases in EGit with local repository.

Eclipse workspace and repository working directory

Unlike SVN or CVS has to put the repository metadata folder inside the project folder, Git can put its metadata folder .git outside project folder. In my example, the .git folder is under GitRepository folder. I can share more than one projects in this repository and they all use the same .git folder to store the repository metadata.

According to EGit user guide, “it is not a good idea to make a project the root folder of your repository”. Because it will not possible to share more than one project in that repository.

And there are reasons why EGit keeps the repository working directory outside Eclipse workspace.

  • When calculating the changes before committing, only active projects folders will be scanned. Irrelevant folders like .metadata or any inactive projects inside Eclipse workspace will be skipped.
  • If .git folder is inside workspace folder, it is unclear whether Eclipse will do unwanted folder scan on the .git folder.
  • Repository data is independent to the Eclipse workspace.

Reference:

Friday, May 22, 2015

Git with Eclipse (1) - configuration of EGit in Eclipse

This post provides a step by step configuration of an integrated Git tool in Eclipse - EGit. Read EGit for basic knowledge about Git/EGit.


Installing EGit in Eclipse

EGit is already included in the Eclipse releases after Juno, so you don't have to install it if you download Juno release or newer versions of Eclipse. For old version Eclipse, open Install wizard by clicking Install New Software... in Help menu.


















Type http://download.eclipse.org/egit/updates in Work with: field. Select Eclipse Git Team Provider and click Next.






































In the next window, click Next again to confirm your select. Then accept the terms of use and license agreement and click Finish to start installation. Restart Eclipse after installation finished.

I am using Eclipse Kepler version and all screenshots below are from Eclipse Kepler.

EGit User Configuration

To configure your username and Email address in EGit, open the Git configuration dialog by clicking Preference in Windows menu.





















Then Type Git in the filter, select Configuration under Git. In User Settings tab, you can add your username and Email by clicking the Add Entry... button. In the pop up window, input user.name in the Key field and your username in the Value field. Click Add Entry... button again to add your Email by entering user.email in the Key field and your Email address in the Value field. The username and Email address are normally the same as your Git account. You can signup your Git account on GitHub website at GitHub.






































The completed configuration window is looked like below. Click Apply button to save your configuration. And click OK button to close the window.






































Now you are ready to create your first local repository. The username and Email address you configured above will be included in your every commit in EGit.

For how to create local repository with EGit, please read Git with Eclipse (2) - creating local repository with EGit in Eclipse