COP-2805 (Java II) Project
Using Git and GitHub with an IDE

 

Due: by the start of class on the date shown on the syllabus

Description:

In this project you will learn to use some of the “team” features of your preferred IDE (Eclipse or NetBeans).  We will use the “Git” source code control system to allow all members of the class to work on the same project at the same time, and then to merge in your changes.  This is a “real-world” way of working on code; few developers work on real projects by themselves.  (And even then, version control is often useful and used.)

The project is a very simple one.  Main.java has a main method you need to edit.  Add a statement to main to greet the class by displaying a unique string (so your contribution differs from other students'), which should include your name.  (You are free to add additional code if you desire!)  The purpose is simply to learn to use Git, which takes time and lots of practice.  You can try using both IDEs, and make two changes if you want.

For this project, every student must individually commit their change(s)and submit this assignment. separately.

I have created a Git repository you can access from the GitHub.com.  This repository contains the initial version of Main.java, a README.md file, and a .gitignore file.  The initial version has a greeting from the instructor you can use as a model for your own addition.

Following the directions below, you will create a GitHub account for yourself, and clone the current repo.  (IDEs generally require a local repo to work with.)  You use this repo just like any other Java project.  When you are done making a set of changes (for this project you only need to add a single line to main), you must commit your changes.  That updates the local repository from your IDE's version.  Next, you Push your changes to the GitHub repo.  During this step you may discover another student has committed some changes after you had checked out the project.  If so, you will need to merge your changes into the new version.  You can also update your local copy of the project, over-writing your files with the latest ones from the repository.

You can perform other Git related operations with Eclipse or NetBeans.  (Generally, I find the Git interface for NetBeans more intuitive than Eclipse.)  It is expected that students will explore some of these operations.  Eclipse assumes you may have multiple projects per repo, and thus creates a project top-level folder within the top (root) of the repo.  NetBeans doesn't do that by default, but it is perfectly happy either way, so I set up the GitHub class repo using the Eclipse conventions.

Another issue is that Eclipse doesn't easily import non-Eclipse projects with existing sources.  It can be done, but it was easier to create a default Eclipse project file and add it to the repo.  It should be ignored by NetBeans, and it shouldn't be modifiable by Git; the repo was set to ignore changes to that file.

You can read about using these features with your IDE using the built in help system you have learned to use in a previous project.  For more information visit the Git Home, especially the Git book online, and the other resources found on our class web page.

Creating a new Git repository is easy, on your own computer using either NetBeans or Eclipse, or at some code hosting site such as GitHub.  Setting one up on your own server is harder.  Linux CVS Repository Setup Directions is a transcript of the steps I used on YborStudent.

Requirements:

Using either Eclipse or NetBeans (you don't have to use both, although you can) complete the steps shown below for your IDE to setup a Git project.  Then edit the shared Java program, test it, commit your change(s), and finally, push your changes back to the central repository (merging if necessary).

The first step is to make sure your IDE includes the latest Git plug-ins.  These may have been installed already, or you may need to add one or more plug-ins for it.  See your IDE's documentation to see how to add plug-ins.  (You can add some others if you wish, but until you are comfortable with your basic IDE features, I suggest you resist the temptation to install much extra.)  You should also check for updates, and install any found.

Next you need to create an account on GitHub.com.  This is easy, fast, and free.  When you have completed this step, you can create your own repositories there for practice.  I strongly suggest you create one (or more), and practice using them with your preferred IDE before attempting any changes to the project's repo.  (When done, you can delete any repo from its “Settings” screen.)

You must send an email containing your GitHub account name to your instructor.  Only those listed as collaborators on Github.com can push changes to the COP-2805-2016 repo there, and I need to add your account name to the list.

There are Windows GUI and command line tools for working with Git and/or GitHub.  They are not IDEs however; you view your repos, create new ones, and with some tools, add files or commit new versions of files.  As the Git plug-ins for Eclipse and NetBeans includes a full version of Git, you don't need any other tool.  (That is, this step is optional).  Still, it is handy to be able to run various Git commands outside of an IDE, especially when trying to learn.

I would suggest installing either “Git for Windows” from git-scm.com, or “Cygwin” from cygwin.com.  Cygwin includes a full set of Linux tools, including (if you select it) Git.  Git for windows includes a sub-set of the command line Linux tools, just the ones you would need to work with Git.  (It also includes a Git GUI, but it doesn't do much.)

Step by step directions for Eclipse IDE:

  1. Start Eclipse.
  2. (Optional step)  Close any currently open project.
  3. Make sure you have installed the “Eclipse Git Team Provider” plug-in.  (You should probably run an update check too.)
  4. Next you should configure Eclipse with some settings.  (If you don't, the Git settings will cause a dialog box to appear when you make your first commit.)  Go to Preferences→Team→Git→Configuration.  Add entries for “user.name” with your full name, and “user.email” with a working email address (such as your HCC Hawkmail address).  This information will be automatically included with every commit.

    From Preferences→Team→Git, you can set a default location for all your Git repos.  (I used My Documents\GitRepos.)

    From Preferences→General→Workspace:  Set the default text file encoding to UTF-8.

    It's not required for our project, but the “Package Explorer” hides many files by default.  In particular, it hides the “.gitignore” and similar files.  To fix that, click on the tiny downward-pointing triangle on the right of the Package Explorer tab bar, and click on “Filters...”.  Now un-check “.* resources”.  To re-hide the Eclipse project files, select “Name filter patterns” at the top, and enter “.classpath, .project, .git, JRE*” (without the quotes) in the box.

  5. It isn't required, but you can use SSH protocol and keys instead of passwords to access remote repos, such as those on GitHub.  If you wish to use keys, see Setting up SSH keys below.
  6. With Eclipse all set up, you are ready to start work.  Since you are contributing to an existing project, you will import it:
    1. Select “File→Import...”, then select “Projects From Git”, then click Next.
    2. Click “Clone URI”, and click Next.  (Don't use the import from GitHub option, which only shows if you've installed a certain plug-in.)
    3. Enter the correct URI for the remote repo.  You can do this easily with GitHub by opening the repo in your web browser.  The correct repo for this project is named https://github.com/profwpollock/COP-2805-2016.  On the lower-right of this repo's web page, you will find a “Clone URL” box:

      Picture of Github repo showing URI and copy button

    4. If using SSH (skip this step if using HTTPS):  Click the “SSH” link, to change the URL from HTTPS to the SSH protocol, if you are using SSH.  (Only authenticated users can Push their commits to the class' GitHub repos, so you must use either HTTPS (with a password) or SSH.)
    5. Click the copy button.  (It's a Flash button, so manually copy if you don't have Flash).
    6. Back in the Eclipse import wizard, paste the URI you copied.
    7. If using SSH (skip this step if using HTTPS):  Select “SSH” from the “Protocol” drop-down list.  Don't change the username; it should be “git”, not your Github name.
    8. Click Next.  If the URI was correct, the next screen shows a list of branches you can clone; if there is more than one, make sure you select “Master”.

      If all is well, you have cloned that repo locally.  Next is to build a project from it.  The Import... wizard should resume now.

    9. Select the (local) repository you just created, and click Next.
    10. Use the “Import existing projects” wizard, and click next.
    11. Select the project you wish to import from the repo (“Proj2” in our case).
    12. Complete the wizard, and you should be all set!

Step by step directions for NetBeans IDE:

  1. Start NetBeans.
  2. Make sure you've installed the Git plug-in.  (It should be installed by default.)  Also useful (but not required) are the following plug-ins:
    Display README files in project view
    Git Toolbar
  3. From the “Team” menu, select “Git→Clone...”.
  4. Enter the correct Repository URI for the remote repo.  You can do this easily with GitHub by opening the repo in your web browser.  On the lower-right of the repo's web page (https://github.com/profwpollock/COP-2805-2016), you will find a “Clone URI” box.  Click the “SSH” link, to change the URI from HTTPS to the SSH protocol, if you are using SSH.  (Only authenticated users can Push their commits to the class' GitHub repos, so you must use either HTTPS (with a password) or SSH to authenticate yourself when doing a Push.)
  5. Click the copy button.  (It's a Flash button, so manually copy the URL if you don't have Flash in your web browser).  Paste the URL into the NetBeans dialog box.
  6. If using SSH (skip this step if using HTTPS):  The copied SSH URI won't work in NetBeans!  You have to add the correct protocol to the front, and change the first colon to a forward-slash.  For our project, the copied URI of “git@github.com:profwpollock/COP-2805-2016.git” should be changed to “ssh://git@github.com/profwpollock/COP-2805-2016.git”.  Next, browse to locate your private key file, created outside of NetBeans.  (Or, as I keep saying, just use HTTPS and a password.)  Make sure the URI is correct; if using SSH, make sure the Username field is filled with “git”.
  7. After filling out the URI (and either your Github username and password, or your SSH key setup), click Next.  Make sure the “Master” branch is selected, and click Next.
  8. Click Next to create a clone of the repo (under the NetBeans projects folder).  This should also scan for projects.
  9. Not finding any NetBeans project files, the “Create project” wizard should launch automatically.  (It may show a popup window instead, with “Do you want to create an IDE project from the cloned sources?”  If so, proceed by clicking the Create Project... button.)  Use “Java Project with existing sources”, and click Next.
  10. Pick some project name (e.g., “Proj2”), and hit Next.  Click the “Add Folder” button (for the “Source Package Folders” section), and select the “src” project folder.  Click Next.
  11. Make sure mypkg/Main.java shows in the list of included files.  Then click the Finish button.

    If you only see “Main.java” and not “mypkg/Main.java”, then you didn't have the correct folder selected in the previous step.  In this case, hit the “Back” button, click on the folder to select it, and hit the “Remove” button.  Now click the “Add folder...” button and try again.

  12. That's it!  You should now have a local repo, and a NetBeans project linked with it.

Complete the Project Using either IDE:

  1. At this point, you should have a local copy of the project.  You should start by reading any README or license files included with the project.  (It may be easier to view those from the GitHub site directly.)  Open the src→mypkg package (folder) to see the “Main.java” file.
  2. Run the application, to make sure it works.  If not, you can either fix the issue yourself, or create an “Issue” on the GitHub site for the repo.  You can also add to the repo's Wiki.
  3. Edit Main.java and add your code.  Make sure the code will compile and run, and displays your greeting along with the other greetings from your fellow classmates.
  4. Save and run to make sure you changes work.  At this point, you are only changing and saving your project's (Git's working directory) copy.
  5. Commit your changes, to save your work to your local repository.  Enter a comment (log) describing your update.
  6. Finally, Push your commit(s) from your local repo to the “origin” (the GitHub class repo).

If you opened the project a while ago, others may have made changes.  In this case, Git won't be able to automatically merge the changes, since both changes were to the same file.  (The error message will say something about fast-forward failed.)  You must Fetch the new commit(s) into your local repo, then Merge your changes with those.  Both Eclipse and NetBeans have nice merging tools; they work best with a wide-screen monitor.  After reconciling the differences (and testing to make sure the code still runs), you complete the merge commit.  Then you can Push that merge commit to GitHub without problems.


(Optional) Additional Steps:

You should explore some of the other items on the “Team” menu.  You are encouraged to create branches and play with them.  Note that only the Master branch of the class' Github repo will be graded.  When finished with this project, right-click on the project and close it.  (This should help prevent “accidents”.)

Try creating your own repo on Github.com.  It's easy.  I suggest you check the box to create an initial README.md file.  Without at least one commit in it, it isn't possible to clone a repo.  (You can push to it however.)  Adding this file means you can clone the repo easily.

From the repo's settings page, you can delete a repo when you are done with it (or after you messed it up badly, and want to just start over).  You can create as many repos as you like on Github.  They are all public unless you pay money for a private repo.  (That means anyone can clone and view it; but only you and those you add as collaborators can push changes to it.)

Working with a local repo is easier than working with a remote one.  You can create a new project and share it using your IDE's Team menus.  This will create a local Git repo, for your project only.  With this, it is easy to practice making many commits, checking out old ones, creating branches, and merging branches.  Since you only are using a private, local repo, there is no Push or Fetch (Pull) to worry about.

If you mess up working with your IDE and want to start over, that is easy too.  Simply delete the project (including all files) from the IDE.  Next, find the Git repo created on your computer for that project; it is separate from the IDE's project folder (usually).  Then delete that too.  Now you can import the Git repo from Github again, and create a new project.

Please spend some time exploring the Git resources from our class web site.  They can really help, and I promise Git has many more features than you will use on this simple project.  Try not to forget the purpose of this project: to spend time learning Git.


(Optional) Set Up SSH Keys:

NetBeans can use SSH keys, but can't generate them.  You will need additional software to create a pair of keys, each in a file.  You then tell NetBeans the name of the file with the (private) key.  You can use the keys generated by Eclipse, or by the ssh-keygen tool that comes with Cygwin or Git for Windows.  Launch the Bash (command line) window, and follow the directions from Git-SCM.com/.../Generating-Your-SSH-Public-Key or from help.GitHub.com/.../generating-an-ssh-key.

Eclipse can generate and use SSH keys:

  1. Go to Window→Preferences→General→Network Connections→SSH2, and click on “Key Management”.
  2. Click “Generate RSA Key”.  (DSA keys would work too.)
  3. Give the key a useful name, for example “wpollock@home” or “WP-RSA-2014-01-01”.
  4. Click the “Save Private Key” button.  This will save the private key in a file you name (such as “wpollock-ssh-key”), and also save the public key in a similarly named file (in this case, “wpollock-ssh-key.pub”).  You don't have to password protect your private key, but keep in mind anyone or any malware with access to your computer can use that key!  So best practice is to password protect your private keys with good passwords.  Make a note of the files location.  Make an off-line backup of the files as well.
  5. The public key will also show once it is generated.  Copy the public key that appears to the clipboard.
  6. Log into GitHub and go to the “Profile→SSH Keys” page.
  7. Click the “Add SSH Key” button, and paste your public key.  (Note the public key is one long line; a trailing newline is fine.)

• Keys cannot be recovered if lost.  Make sure you have a good backup copy (or two).
• Use of your private key may have legal implications.  Either protect your private key with a strong password, or don't use that key for any other purpose.

To test your key, follow the directions at help.github.com/articles/testing-your-ssh-connection.

If you have trouble using keys, remember you can use HTTPS protocol instead (with a password).  You can also ask your instructor for help.


To be turned in:

A copy of the entire Main.java Java source code, including your additions.  (No credit if your changes aren't found on the Github repo, or if you don't use an IDE to make the changes.)  You can send as email to (preferred).  If email is a problem for some reason, you may turn in a hard-copy.  In this case the pages should be readable, dated, and stapled together.  Your name should appear on the first page.

Please see your syllabus for more information about projects, and about submitting projects.