SVEditor Git Guide

Note: The guide below assumes that you want to setup Git to participate in SVEditor development. Some portions of the below do not apply if you are using Git in read-only mode to get access to the latest and greatest SVEditor source.

Register for a GitHub Account

SVEditor uses GitHub for Git repository hosting. Sign up for an account here: https://github.com/signup/free

Install EGit

Eclipse provides support for Git via the EGit set of plug-ins. Egit has been part of Eclipse since Eclipse version 4.5.x. If not installed in your copy of Eclipse, install EGit from your development Eclipse environment. Select Help->Install New Software.

The EGit user guide is here: http://wiki.eclipse.org/EGit/User_Guide

Install Git (Optional)

Installing the command-line version of Git may be helpful. Instructions for installing Git can be found here:

Git Development Workflow

Git is a distributed version control system that has been gaining popularity with Open Source projects due to its features that facilitate decentralized development.

In a version control system, such as Subversion or CVS, there is one central source repository. Developers with commit access to the repository can modify the repository directly -- committing source to repository, creating branches, and merging branches. Developers without commit access must submit their changes to the project source via more indirect means -- perhaps by creating a patch file and submitting it for consideration to one of the project maintainers.

In a distributed version control system, there are multiple repositories. Developers with commit access to the primary repository can modify the repository at will. Developers without commit access to the primary repository can create a 'fork' of the primary repository. This, effectively, creates a derived repository that is linked to the primary repository. The developer can now modify the source in the derived repository, all the while receiving updates from the primary repository when desired. When a feature in a derived repository is complete, a 'pull' request is sent to the maintainer of the primary repository. At this point, the maintainer can review the proposed changes, provide feedback, and finally 'pull' the code for the completed feature from the derived repository.

Creating a Development Repository

This section describes how to setup a Git repository for development.

Forking the SVEditor Repository

The primary SVEditor Git repository is hosted on GitHub here: https://github.com/mballance/sveditor

Log-in to GitHub (in this case, I'm signed in as mballance-sf, a user that contributes to SVEditor)
Navigate to https://github.com/mballance/sveditor
Select the 'Fork' button in the upper-right corner, as shown below

GitHub will take a few moments to create a new fork of the repository
Finally, the new fork of the repository (owned by mballance-sf, in this case) is shown

Adding the Git Repository to Eclipse

In the web browser that is displaying the forked SVEditor repository:
Select the 'HTTP' button
Copy the displayed URL, as shown below

Launch Eclipse
Open the Git Repository Exploring perspective
Select Window->Open Perspective->Other...
Select Git Repository Exploring from the list
In the Git Repositories view, select the 'Clone Repository' button, as shown below

The Clone Git Repository dialog will open.
The URL copied in step 1 should be auto-filled. If not, copy the URL into the dialog
Fill in your GitHub password

Select Next
The Clone Git Repository wizard will fetch the branches from the repository, as shown below

Select Next
Specify the local directory in which to place the cloned repository

Finally, select Finish
Eclipse will clone the repository, which could take some time depending on the network speed

The new cloned repository will now be shown in the Git Repository Explorer.

Specifying the Upstream Repository

We've specified how to access our developer's fork of the SVEditor repository. We now need to specify how to access the primary repository so we can obtain updates.

In a web browser, navigate to https://github.com/mballance/sveditor
Select the repository URL (https://github.com/mballance/sveditor.git) and copy it
Note that you want the "mballance" link as shown above.

[[Image:create_remote_upstream_url.gif]]

Expand the repository in the Git Repository Explorer
Select Remotes, then select Create Remote... from the context menu

The New Remote dialog will open.
Specify the Remote name as "upstream"
Specify "Configure fetch"

Select OK
The Configure Fetch dialog will open

Select the Change... button
A dialog will open with the primary SVEditor URL filled in (the URL you copied in step 1)

Select Finish in the 'Select a URI' dialog
Next, select 'Add...' in the RefSpec: portion of the Configure Fetch dialog
In the "Adding a Refspec for Fetch", specify the following source: refs/heads/master

Select Next in the "Adding a Refspec for Fetch" dialog
The next wizard page prompts for a destination. Select Finish to take the default settings.

Now, we are back to the "Configure Fetch" dialog.

Select "Save and Fetch" to complete.
Now, the upstream repository is shown in the Git Repository Explorer

Importing Projects

Once the remote repository is cloned and connected to the primary repository, we can import the SVEditor projects into Eclipse.

In the Git Repository Explorer, select the repository, then select Import Projects...

The Import Project wizard will open, as shown below. Select Next

The Import Project wizard displays the projects found within the Git repository clone. Select Finish.

Now that the projects are imported, switch back to the Java perspective

Committing Changes

Centralized version-control systems, such as Subversion, implement a single-step commit operation. Git, effectively implements a two-step commit operation.

The first step of a Git commit commits selected changes to the local clone of the Git repository. Git refers to this operation as "commit"
The second step of a Git commit transmits locally-committed changes from the local Git-repository clone to the remote Git repository. Git refers to this operation as "push"
Committing changes using EGit is initiated using the 'Commit' menu item in the 'Team' category, as shown below.

The Commit Changes dialog prompts for the set of files to commit, and for a comment for the commit. Confirm that all files you intend to commit are 'checked' in this dialog.

Pushing locally-committed changes to the remote development repository is also initiated from the Push Upstream menu item in the Team context menu.

A dialog will open to confirm the set of commits to push to the remote repository.

You can commit multiple local changes and push them to your central development repository with a single 'push'.

Submitting Changes to SVEditor

Once you're happy with a particular set of bug fixes ore improvements to SVEditor, you will want to submit them back to the primary SVEditor repository. This is done by sending a Pull Request via GitHub.

Log-in to your account on GitHub.
Navigate to your development clone of the SVEditor repository.
Click on the Pull Request button

Specify the pull-request subject
Specify a change-log entry, describing what the changes accomplish. You can see more detail about what is being submitted on the Commits and Files Changed tabs.
The maintainer of the core SVEditor repository (that's me) will receive an email with details on the change to be submitted. Once the proposed changes are accepted, they will be pulled into the central SVEditor repository and made available to everyone.

Updating a Development Repository

When a change is applied to the master SVEditor repository, you will want to fetch that to your development repository. This can be done via the following steps.

Open the Git Repository Explorer view
Expand the Git repository and find the Upstream repository in the Remotes category
Select 'Fetch' from the context menu

If new changes are available in the master repository, they will be displayed

Next, we need to apply these changes to our local development repository
Select the repository root and select Merge from the context menu

Select the upstream/master branch as the source of the merge, the select Merge.

A summary of the changes that were fetched from the master repository will be displayed

The local development repository is now up-to-date with changes from the master SVEditor repository.

Google Sites

Report abuse