Using EGit - pc2ccs/pc2v9 GitHub Wiki

PC² code, documents, scripts, and other project elements are stored in Git repositories ("repos" for short). Since the primary development IDE used by the PC2 project developers is Eclipse, it is useful to have tools within Eclipse to manage Git repositories.

(Note that, having said the above, it is not strictly necessary to use Eclipse to manage PC2 Git repos; Git repo management can be done outside of Eclipse using the Git command line toolset. It's just more convenient in many cases to do it within Eclipse.)

The primary tool for managing Git repos within Eclipse is the EGit Eclipse plugin. This tool allows all of the following operations (and more) to be done within Eclipse:

• Create a new local Git repo
• Clone an existing Git repo from an arbitrary remote URL
• Link Eclipse projects to specific Git repos
• Create and switch between different Git "topic branches"
• Commit changes to a local Git repo
• Push commits upstream to a remote Git repo (assuming you have write access to the remote repo)
• Pull changes made by others in an upstream Git repo down into your local repo
• Merge different versions of files (from different local and/or remote updates)
• View individual commits and commit history
• Temporarily "stash" changes while you work on other things
• Create "patches" which can be used to update other repo branches (including those in remote repos)

The easiest way to install EGit into Eclipse is to let Eclipse do it for you, and the easiest way to do that is to use the Eclipse MarketPlace Client (MPC). MPC is already installed in newer versions of Eclipse; to use it select the Help menu and choose Help > Eclipse MarketPlace.... This will open the Eclipse MarketPlace Wizard. Enter "Egit" in the Search box, and hit "Find" (or "Search") or press the "Enter" key. This should display an option for installing "EGit -- Git Integration for Eclipse x.y.z", where x.y.z is the EGit version number (not the Eclipse version). Click "Install" and it will automatically install EGit in your Eclipse system.

If you don't already have the Eclipse MarketPlace option under the Help menu, you can install the MPC by going to https://www.eclipse.org/mpc/, following the links there to the MPC version you need, then selecting Help>Install New Software... and entering the MPC version URL in the Work with: box and then clicking Add. It will ask you to give that location a "name" by which you want to refer to it; enter any name you like and click OK. After a few moments the dialog will refresh with the names of the software packages available at that MarketPlace repository location; check the "EPP Marketplace Client" box and then click Next and then (when it is done calculating the necessary resources) click Finish.

Once EGit is installed in Eclipse it provides the ability to present various "Views". The most commonly used views are the "Git Repositories" view, which shows all of the Git repos which your Eclipse installation knows about, and the "Git Staging" view, which shows the states of various files with respect to the Git repos with which they are associated.

To display a View, select Window>Show View>Other..., which displays the "Show View" dialog. Scroll down to "Git", click the little "arrow" icon to expand it, and select the Views you want to have displayed. Like all Views in Eclipse, these views can be positioned anywhere you want in any Eclipse Perspective.

This view displays a list of your Git repositories. (Since you probably won't have any to start with, the list will be empty initially.) The view has several little icons at the top (just below the title bar). Hovering your mouse over each icon will reveal that these include:

• Add existing local repository to the view
• Clone an existing repository
• Create a new (empty) repo

• Click the "Clone a Git Repository" icon. This will display the "Clone Git Repository" dialog.
• Enter the URI of the GitHub PC2v9 Git repository (which you forked from the PC2v9 project) into the "Location URI" box. (This will be something like https://github.com/yourOrganization/yourForkedRepoName).
• If the remaining "Location" boxes do not auto-populate, then
  • Enter the GitHub host name, which is github.com, into the "Location Host" box.
  • Enter the repository path, which will be something like /yourOrganization/yourForkedRepoName, into the "Location Repository path" box.
• Insure the "Connection Protocol" value is "http".
• Under "Authentication", enter the name and password for your GitHub account.
• Check "Store in Secure Store" if you want Eclipse to remember your credentials (otherwise you're going to have to re-enter them every single time you perform any action related to the remote repo).
• Click >Next.

This will display the "Branch Selection" screen, which allows you to select which branches of the repo you wish to clone to start with. Initially you just need the "master" branch, plus whatever existing topic branches you plan to work on (you can pull the others later if needed), so do the following:

• Click Deselect All.
• Scroll down and check the box next to Master.
• Check the box(es) next to any other branches you wish to clone.
• Click Next.

This will display the "Local Destination" screen, which allows you to specify where the repository clone will be stored on your machine as well as some aspects of its configuration.

• In the "Destination Directory" box, enter the full path to the folder where you want the repository clone to be stored. For example, if you were going to keep all of your Git repositories in a single folder named "git" under your home directory, you might enter something like "C:\users\yourUserName\git\pc2v9" (on a Windows machine) or "/home/yourUserName/git/pc2v9" on a Linux machine.
• Click the "Initial branch" dropdown list and select the branch which you want to be the initial (starting) branch (typically this would be "master").
• In the "Configuration Remote name" box, enter "origin" (if it hasn't already been auto-populated). This insures your local repo view of the names at the remote repository are consistent with the remote name.
• Check "Import all existing Eclipse projects after clone finishes".
• Click Finish.

This will clone the forked PC2v9 repo as a local Git repository on your machine; the cloned repo will contain the master branch (plus any other branches you selected).

The repository name should now appear in the Git Repositories view.

• Right-click the repository name in the Git Repositories view.
• Select Import Projects... from the resulting context menu. This will display a list of the various "Eclipse Projects" associated with the PC2 system.
• Click Deselect All (you probably don't want -- aren't interested in -- the entire set of PC2 projects)
• Check the box next to "pc2v9"
• Click Finish

This will import the "pc2v9" project into your workspace as an Eclipse Java Project.

See the PC2 Developer's Wiki article PC2V9 Source Code for information on the structure of the PC2v9 project code.

New branches are created in EGit by right-clicking on the Project Root entry and selecting Team > Switch To > New Branch. This displays a dialog which allows you to enter a new branch name. Refer to the PC2 Developer's Wiki article Development Environment for information on branch naming guidelines for PC2v9.

To switch to an existing branch, right-click on the Project Root entry and select Team > Switch To >, then select the existing branch you want to switch to. Selecting Team > Switch To > Other > Remote Tracking will allow you to switch directly to a remote (origin) repo branch.

Recall that (if you followed the above steps) the "remote" repo (normally referred to as the origin repo) for your local (cloned) repo will be the GitHub forked repo from which you cloned your local repo. This raises the possibility that while you are working on your local (cloned) repo, and occasionally pushing changes from it up to your PC2v9 GitHub fork, the original PC2v9 repo itself (the one which you forked) might have changed.

Normally, it is desired to insure that your forked repo is "in sync" with any changes that have been made to the PC2v9 repo. This repo is referred to as the upstream repo from the point of view of your fork. Refer to this GitHub article for details on how to arrange for your fork to remain in sync with changes to the PC2v9 upstream repo.