Git and GitHub - LdhssRobotics/How-Tos-2015 GitHub Wiki

###By: Kieran Bingham

What is Git and GitHub?

Git is a Source Control Manager (SCM) which was originally written in 2005 by the Linux development community (and in particular Linus Torvalds, creator of Linux), for their own use.ref Since then, it's become extremely popular for programing projects, from small to large.

"Why would we use Git?" you say, "Why not just save our code on our hard-drives?" Well, that would work fine if we just used one computer, however, as a robotics team, we use MANY different computers. Git allows us to transport our code from computer to computer, and sync up any changes we make with the rest of the team.

Git also takes care of versioning for us.

Versioning is the creation and management of multiple releases of a product, all of which have the same general function but are improved, upgraded or customized... Version control is the practice of ensuring collaborative data sharing and editing among users of systems that employ different versions of a product. ref

Essentially, versioning allows us to track changes to our program. This is useful because you can use Git to check if you are a version behind and need to update. It can also be used to undo any changes or mistakes that are made, such as code that breaks the program, or someone accidently deleting everything.

Git can be used on any computer locally, but is most useful when connected to a remote server so code can be shared across multiple devices. This is where GitHub comes in. GitHub gives us remote server space to host our Git repositories on. By hosting a repository on GitHub, we can pull (retrieve), and push (submit), code to, and from the cloud, on any computer. It also provides additional capabilities integrated with repositories, such as simple Wikis (like this one), and issue management (bug & change request tracking). Also, through FIRST, our robotics team receives a commercial-level service for free, and free is awesome.

Getting Started

Accounts

To use GitHub you need an account. You can either make your own or you can use one of the accounts we have pre-made for the robotics team. Once you have an account, you can be added to our LDHSS Robotics organization.

Making an account

At the top right hand side of the GItHub homepage, there is a button that says sign up. Once you are there you fill out the information that they ask for. Make sure that you use a professional username, remember, you might want to one day show this to potential employers.

Getting added to Raven's Robotics

You can get added to the Raven's Robotics organization by anyone who is a current 'owner' of the organization. Once you have been sent an invitation, you need to go to our organization's homepage to accept it, I'll link to it HERE. If you can't find an owner to add you, you can use one of our pre-made ravens accounts to add yourself.

Using the pre-made raven accounts

For the 2015 season we created a handful of accounts for use with ravens robotics. The accounts are called swteam 1-6, (sw - SoftWare). These accounts are for the software team to use if they do not have their own accounts, or if they are using one of our teams laptops and don't want to leave their account logged on. To get the login information talk to Morrison, one of the mentors or E-Mail one of the former team members.
swteam accounts

Creating a repository

Creating a repository is really simple. On the Raven's Robotics main page there should be a new repository+ New Repository button. Simply click on this button to create a new repository. This new repository can ether be made private or public. Public repositories can be seen by anyone, however you can still control who commits to them. With a private repository only people who are members of Ravens Robotics will be able to see the contents of the repository. However we can only have a certain amount of private repositories, so they shouldn't be used all the time. Once you create the repository in GitHub, you then need to clone it to the computer you want to use it on. Under construction

Cloning a Repository

Cloning a repository is to make a copy of it and all of its included resources, like:

  • Directory structure
  • source files (*.cpp, *.h, etc.)
  • Eclipse project files (.settings folder, .project & .cproject, and build.*)

We also get metadata with all the history of changes that were ever made in or synchronized to the remote repository. This appears as a hidden directory .git. Generally we only clone a repository when we want to use it on a new machine that doesn't have it already. If you simply want to get the most up to date version see PULLING.

Clone Using Eclipse

You have many options for how to do this, but in this guide we'll use the Eclipse eGit extension, which is included in Eclipse Luna.

    File > Import... > Git > Projects from Git

Click 'Next' to proceed to 'Select Repository Source'. Select 'Clone URL', then 'Next' to open the 'Source Git Repository' dialog.

You can find the Clone URL for the master repository in GitHub, on the right hand side. Make sure you are getting the HTTPS version.

Copy that value, and paste it into the "Location / URL" field in the Eclipse dialog. Enter the GitHub credentials that will be used by this development machine. Each of our laptops should use a unique GitHub id, like the swteam accounts. People working on their own machines should use their own GitHub account. See Getting Started for more info on accounts.

Click 'Next' to go to the 'Branch selection' dialog (should select all) then 'Next' again to get to the 'Local Destination' dialog.

This is where you chose where the remote Git repository will be cloned on the local machine (where you will put the cloned files). You should select a folder that does not currently contain an Eclipse project.

Our project repository contains an Eclipse project, so make sure you import it as such.

Git operations

Commits

A commit is a saved version of your code. However, unlike normal saving, commits allow you to go back to previous committed versions if you need too. Each commit has its own ID, for example 'commit d1091434a83db907295958dc8c23296466f92529'. This commit is a small one I made to make part of one of my C++ classes more readable. If you click on the link i put on the the commit ID you can see exactly what I got rid of (in red), and what I replaced it with (in green). You can even see a history of all the commits done to a repository to see the changes between commits, and who made the commits. Knowing who did the commit is important because you know who to talk to about the changes or any possible issues.

Getting updated code

Git Fetch

A git fetch will grab all the changes from a remote repository but won't apply them to your code. It is useful to get the most up to date information without changing anything locally.

Git Pull

Pulling is the operation we use to take a new version of our code and merge it with our existing code. Git pull will look at the upstream repository for any committed changes since our last shared 'common ancestor', and pull those changes into our local repo. Essentially it does a git fetch followed by a git merge or git rebase. It should automatically change the parts of your code that need to be changed so that you have the most updated version. Sadly it isn't always that simple, although it usually is.

To bring the downstream (local) repository up-to-date with code & metadata changes from the upstream (GitHub) repository, we will pull and rebase locally.

There are other ways to accomplish this step. For instance, we could pull and merge, which would join the changes received from the upstream repository with the changes we've made locally. However, a rebase operation will typically be much cleaner.

While the work is still in progress and a feature branch needs to be brought up to date with the upstream target branch, use rebase – as opposed to pull or merge – not to pollute the history with spurious merges.

For more info see this, this, or this.

For now we will look at pull and rebase.

As the name implies, pull will look at the upstream repository for any committed changes since our last shared "common ancestor", and pull those changes into our local repo.

  1. Right-click on the project in the Project Explorer, and select:

     Team > Pull

You will then see a dialog pop up asking for your GitHub username and password. Just enter them to continue.

Eclipse / Git will contact the upstream server and get a list of available "fast-forward" tags. These will include both commits and explicitly added tags.

  1. Select the point in the upstream repository that we want to align with, then click go.

Depending on the number of changes, and speed of your connection, this could take from several seconds to minutes to complete.

When done, your local repository will include all the changes from the upstream repository, and all the content of your local repo. However, the local copy may not be a match for the upstream; for example, a file that had been moved from one directory to another upstream, will appear in both places locally. To complete our operation, and resolve these sorts of issues, we will rebase our local repo.

  1. Again, right-click on the project in the Project Explorer, and this time select:

     Team > Rebase

Chose what you want the rebase to be based on, then click rebase.

When this operation completes, our local will have rebased to an exact match for the upstream head revision, with any local changes re-applied over top.

Importing Code Troubleshooting

  • If you encounter conflicts during a merge, look for a conflict resolve dialog in your IDE, it should be with the rest of the Git related stuff. Get more help with merge/pull conflicts here.
  • Try to get different people working on different parts of the code so that there isn't any conflicts.
  • Use branches instead of using the main branch, this allows everyone to have their own code, avoids conflicts, and helps you see what each branch changes (if they have a good name, describing what it changes).

Submitting new code

Git Push

Git Push is an operation that takes local changes and 'pushes' them up to the remote repository. It basically makes the remote repository do a pull of your local repository. The remote repository will look at your local repository for any committed changes since your last shared 'common ancestor', and pull those changes into the remote repo.

To do a Git Push, right click on the project in the project explorer and go,

    Team > Remote > Push

It will then ask you which remote repo you want to push too, select the one you want then click finish, or click next if you want to push with specifications, such as deleting or pushing to branches.

Find more info about pushing to remotes in eclipse here.

Learn more about Git

Sometimes learning just the basics isn't enough. Here are a few resources that will help you start down the road to really learning about source control, focused on Git. I HIGHLY recommend the first one, it is really useful to be able to use git from command line. Also it will help you better understand the things I have talked about here and learn them, the best way to learn is to do.

Contact me

You can email me any questions at [email protected]. Just make sure to include 'Raven's FIRST' and your name in the subject line. If asked I might even be able to come in to help with anything, from coding or version control, to Computer Science in university, I can answer any questions you may have.

Sources

Sources

⚠️ **GitHub.com Fallback** ⚠️