Git and GitHub

git is a version control system for maintaining your shared codebase that has very good support for distributed project development. We are requiring use of git for OOSE projects.

Leandro's Git tutorial

Our own Leandro Facchinetti has written an online git tutorial based on his lecture.
  • The animations from his in-class presentation are also available if you are interested, in Keynote and Movie formats.
  • A tutorial document written by Leandro is here.

git tutorials and help resources

There's still a lot more to learn about Git. Here's a list of great references:

git clients

There are three common ways to interact with git: command line, from within your IDE, and via a standalone tool. All modes can be good for some purposes, but you should at least know the command line as you will know exactly what git is doing if you understand the command line.

  • Command line: see Git downloads. This command line also comes with a simple GUI, git gui. Documentation on how to use the command line and the gui are found in the git documentation.
  • Github Desktop is a new Git client developed by GitHub. It is very useful for browsing the commit history and inspecting changes.
  • Eclipse and IntelliJ have git support built-in, see their documentation for how to use it.
  • If you want more options, here is A list of GUIs for you to choose from.

Your project's git repository on GitHub

  • We require that group projects use a repository which is hosted on Github under the jhu-oose organization; this allows us to access your codebase as necessary and keep archives of your data.
  • The repositories are by default private.
  • You are required to use this repository as your origin master for the main development branch.
  • Once groups are formed you will be receiving an email inviting you to the repository created for your group on GitHub.

Using GitHub's Issue Tracker

Along with using Gitub for your repository you are required to use the issue tracker to help your project progress forward.

When to make an issue

Create an issue for every:

  • Feature / use-case
  • Bug
  • Enhancement (e.g. refactorings)


  1. It can spark a conversation.
  2. It serves as documentation on what was decided.
  3. It lets people collaborate asynchronously.

What tags to use?

Categorize every issue with tags according to:

  1. Which component(s) it refers to: for example, is this a front-end or a back-end feature?
  2. What's the nature of the issue? Is it a feature or a bug?
  3. It's also common to tag according to difficulty of the issue.

Issues and Milestones

  • Add each issue to a GitHub Milestone. Make each OOSE project iteration a Milestone.
  • Assign someone to issues they are working on. This makes it easy to see what's being worked on. And people don't overlap trying to solve the same problem.
  • Having organized the issues this way, it's easy to come out with many kinds of metrics. For example, there's a progress bar showing how many issues we are done from finishing the next Milestone.

How to use issues with pull requests

See the article here, it covers how to relate Issues and Pull Requests. In summary,

  1. Create an Issue.
  2. Create a Pull Request with mentions the Issue number (e.g. `fixes #3`).
  3. When the Pull Request is merged, the Issue is automatically closed.

Why we are requiring you to use an issue tracker?

Yes, you really must eat your broccoli, its gooood for you!

  1. It's easy to learn and helps projects stay organized
  2. It's commonly used in industry