Using git for Homework

Postscript and PDF available. Terry Sergeant

Background

The program git is an example of distributed version control software. It is used by programmers for the purpose of tracking changes to a code base, especially for projects that involve multiple programmers.

Prospective employers have provided us with feedback multiple times that it would be nice for CSCI grads to have experience in the use of version control software. To that end we are introducing git in the Program Design and Development II course and will use it in various capacities in other programming courses.

We will teach command-line use of git because it is portable across multiple systems. Although you will be allowed to use a graphical tool when doing your own work we will not provide help with those tools. We recommend you exclusively use the command-line in whatever environment you choose for doing your work.

There are some significant benefits of using version control software for homework assignments:

Setting Up Your Workspace

NOTE: These steps only need to be done once per semester. Most people have a particular computer they like to do their work on. If you have multiple computers you will need to take these steps for each computer:
  1. Install git on your computer. See https://git-scm.com/book/en/v2/Getting-Started-Installing-Git. Make sure that git will be available on the command-line.

  2. On the command line on your computer identify your name and HSU email address to git by entering these commands:
    git config --global user.name "Your first and last name here"
    git config --global user.email "your-email@hsutx.edu"
    
    NOTE: Please use your HSU email address. Please do not use a screen name.

  3. Decide what directory/folder you want to put your CSCI homework files.

  4. On the command line navigate to that folder and enter this command: git clone [URL] where URL is the location of the homework repository for the course in question.

  5. Make note of the name of the directory/folder created by the command. That directory/folder contains the homework files and you will do your work for the semester in it.

  6. NOTE: By cloning from the course repository, git will automatically designate that URL as a remote named origin. So, when working in a repository set up in this way, commands that use the name origin are referring to the course repository.

To summarize, the steps above accomplish two things:

Setting Up a Hosted Repository

NOTE: These steps only need to be done once per semester. Now you are ready to create a hosted repository where you will a copy of your work. The work you save at this hosted repository is the work that will be graded by the instructor. For Sergeant's courses you will be using https://bitbucket.org to host repositories. Follow these steps:
  1. If you haven't done so already create an account at https://bitbucket.org using your hsutx.edu email address. If you have an account but it is associated with a different address you can either create a separate account or add your HSU address as an alias (see settings) to the existing account.
  2. Create a repository by importing from the course repository:
    • Log in to your bitbucket.org account.
    • In the menu at the top choose: Repositories->Import repository.
    • Under ``Old repository'':
      • choose ``git' from the drop-down
      • enter the URL for the course repository (same URL as in previous section)
    • Under ``New repository'':
      • keep yourself as the owner
      • click in the ``Repository name'' box ... the name should autofill ... do not change the name
      • make sure the repository is marked as private
    • click ``Import Repository''
    NOTE: When the import operation completes you should be at the overview page of the newly created repository.

  3. Share the newly imported repository with your instructor:
    • From the newly imported repository's overview page click ``Settings'' in the menu to the left (you may have to scroll down in the menu).
    • Under ``General'' click on ``User and group access''.
    • Under ``Users'' enter the HSU email address of your instructor and choose ``Write'' from the drop-down box. Then click ``Add''.

  4. Return to the overview page and highlight and copy (to the clipboard) the URL for your repository near the top-right of the screen. This is the URL you will use to refer to your hosted repository.

  5. Set up a new remote name to refer to your hosted repository on your local computer.
    • Return to the command-line on your local computer.
    • Navigate to the directory/folder and into the repository you cloned earlier and issue this command: git remote add mine [URLofYourRepository] (where URLofYourRepository is the URL you just copied to the clipboard).
    • NOTE: In this command you are informing git of a remote and giving it the name mine. You can actually call it whatever want but the discussion below will make a lot more sense if you call it mine.
    • Issue the command: git remote -v to see what URLs git has assigned to what names. (origin should point to the original course-provided files and mine should refer to your hosted copy of those files).

Working on Your Homework

Some terms/assumptions in these work flows:

Work Flow for Typical Homework

In a typical homework assignment you will:
  1. Verify your local repository has been committed. Use git status to see if anything has been changed since the last commit. If there are changes you want to hang onto you should go ahead and commit: git commit -m "info about changes you are committing".
  2. Pull changes (if any) from the base repository. Use git pull origin master.
  3. Work on your homework. In a typical assignment you should have 5 or more commits. Students often wait until they think they have everything completely finished to commit. You should commit after each success. For example, if you are writing a program that will read words from a large file and count how many times each word appears you might follow this sequence:
    1. Create a small words file for testing purposes. Add the file to repository using: git add nameoffile. Then commit with an appropriate message using

      git commit -m "Created small words data file for testing purposes"

    2. Write code that opens the file, reads each word and displays each word to the screen. If code was in new source file, add file to repository. Commit with message ``Opening data file and displaying each word to the screen.''
    3. Suppose this is all you have time for at this sitting. You will push your changes to your hosted repository using git push mine.
    4. Write a method to search an array for a word. Document the method using JavaDoc conventions. Commit with message ``Wrote method to search array for a given word.''
    5. Modify reading code to store words into array only if word not found in existing list. Commit with appropriate message.
    6. Add code to count recurrences of words. Commit with appropriate message.
    7. Suppose this is all you have time for at this sitting. You will push your changes to your hosted repository using git push mine.
    8. Add code to track time elapsed in program and to display various stats/results. Commit with appropriate message.
    9. Verify program is adhering to all documentation requirements and Java programming conventions. Switch to large data file and test. Commit with ``Completed Homework to Count Word Frequency".

  4. Make sure git status is clean. Use git status and verify that files you want to be staged for commit have been added with git add. If needed do a final commit. In the commit message you should indicate that the homework assignment is completed. Be sure to specify which assignment it is you completed. This will help the instructor navigate your repository when grading.

  5. Push all changes to your hosted repository. Use git push mine. Verify that the repository you pushed matches what you thought you pushed by logging in to your BitBucket account and viewing the source of the most recent changes you made.
  6. Wait patiently for work to be graded. The instructor will pull code from your hosted repository when grading. You can, of course, start on the next homework assignment before grading is complete.

Some Other Cases

The work flow suggested above will cover many cases. Here are some possible scenarios you may encounter and how to deal with them.

Quick Links