Programming: GitHub

Getting Started

Create an account

• • go to github.com

  • click sign up in the top right hand corner

  • create a free account with your preferred email.

Join our Team

• • Once you have created a github account send a message to the #Programming Slack Channel with your name and github account name

Download Github Desktop

• • Go to https://desktop.github.com/ to download the latest github Desktop

  • Install on to your PC/Mac

  • Once it is installed sign in with your github account

Intro to Git

Github is a wonderful tool! It helps us with version control, an important aspect of any long-term programming project. Every contributor is responsible for understanding the following basic terminology, because you have all the power to keep things running smoothly.

Repositories

A project in Github is called a repository. It is the most basic level of organization. This is often shortened to "repo".

Branching

Let's say you are working on a larger repository with a bunch of other collaborators. If you have a great new idea to try out, but you're not sure if it will work yet or if it adds to the greater immediate mission of the project, you can create a branch and work on it independently from everyone else. If your team decides it is relevant at some point in the future, it can be merged back into the main code! Branching is the perfect way to develop without causing code breaks on the main branch.

To create a branch:

git branch <branch_name>

Note, this does not change the branch you are on. It only creates the branch. To see how to switch your local branch, read on.

Local

Your local branch is the branch currently on your computer. If you are working on your own dev branch, this will likely be that code. If you want to switch branches, use the checkout command.

git checkout <branch_name>

Remote

This may not be super applicable to you, but if you branch code from a remote git server, there are some important things to keep in mind. If you make edits to your origin/master while someone else makes edits to the remote server, your code will become desynchronized. If you wish to sync back with the remote branch, simply use this command:

git fetch origin

Master

The default branch in git is the master. Some projects may only have a master branch. All commits to the master should progress the project and be working, debugged code. More about commit conduct will be detailed below.

Commit

So how are changes actually tracked in git? Via commits! If you finish up a day's work in programming and have tested your code thoroughly, it may be time to commit your progress. That way, everyone else has access to your work and it is saved in case something happens. Remember, the primary reason we use git is version control, so if something goes wrong in the future you always have working code to come back to. So: commit often, but only commit working code!

The first step is to "add" files you have changed, or "delete" those you have removed.

git add src/code.cpp

Then, commit to your local branch. Make sure to have an informative commit message so anyone can understand what you have changed! This is very important! MAKE SURE YOUR COMMIT MESSAGE IS INFORMATIVE.

git commit -m "Added a new setup to allow for setting PID values via config files"

Push

When you commit code, it is saved locally. To push your changes back to the git server and have your code be available to everyone, you need to use the push command! Before you push, however, make sure you pull! See the next section for more info.

git push

Pull

Before you push your own code to the repo, make sure you pull the latest changes.

git pull

Merge

On occasions, a pull or push can cause a merge conflict. This means someone else has been editing the same file or same code section as you! Sometimes, Github can figure out what to do on its own by making sure you didn't edit the exact same lines. Other times, you may have to manually go through the file and determine what to keep and what to discard. NEVER do this without talking to the other contributor! You wouldn't want someone else to overwrite your code, so don't do it to others. Most of the errors involving git occur during manual merges, so pay close attention to what to do. If you still aren't sure, ask a mentor or peer if the situation ever comes up while coding.

This is what a merge conflict looks like in the actual file. When you try to pull or push Github will automatically change the file(s) to have these markers showing your changes and what's already pushed to the repo.

<<<<<<<

your code

=======

code on the master branch

>>>>>>> master

To resolve, delete the code you don't want anymore and remove the markers (<<</>>>>/=====). Then, re-add the file, re-commit, and push! In order to avoid these merge conflicts, pull often.

Unit Testing

Your role in the software development cycle is very important! You are in charge of making sure your code works. DO NOT PUSH CODE THAT DOESN'T WORK TO THE MASTER! Refrain from doing this at all, but it may be acceptable to share broken code on dev branches this way.

Approvals

Working as a group

Github Kanban

Comments

As all good programmers know, comments are crucial! Make sure you put comments detailing what your code is doing. Think of git commit messages as mini comments summarizing what you did in a piece of code. You can't ignore it! Take responsibility for your coding and leave comments. It makes everyone's life down the road that much easier!