1. Introduction
   • What is a VCS?
   • What is git and why are we using it?
   • What is GitHub and why are we using it?
2. Getting started
   • Installing git
   • Setting up GitHub
3. Usage
   • Basic git commands
   • Best practices & rules
4. Walkthrough Examples
   • Commiting basic changes
   • Branches & PRs

In this article we will go through everything you need to know to contribute to the HYPED code base using git and GitHub. While this is fundamentally aimed at complete beginners, you may still find some of the information presented useful.

Version Control Systems are a category of software tools that help a software team manage changes to the source code over time. It

• keeps track of every modification made to the code in a special kind of database. If a mistake is made, the developers can go back and compare earlier versions of the code to help fix the mistake while minimizing disruption to all other team members.
• protects source code from both catastrophe and the casual degradation of human error and unintended consequences.
• allows several people to work on different parts of the source code while tracking every individual change by each contributor and helping prevent concurrent work from conflicting.

More information can be found here.

git is a free and open source VCS. It has been tried and tested on virtually all operating systems and a wide selection of tools and documentation is available. Today, it is the undisputed industry standard, which makes it the obvious choice for the Software Team.

The three most important terms within git are the following:

• repository: A git repository contains all the code related to a piece of software and the history of changes. In your local file system a repository corresponds to a folder. If you make changes to the files in the folder, you can then add these changes (more or less) permanently to the history of the repository.

• commit: A git commit is the smallest unit of change within a git repository. Of course, a single commit can affect multiple lines of code and even files, but operations like merging and reverting treat a commit as the smallest possible step. Therefore, a single commit should only include a single change at a time. For more information see 3.2 Best practices.

• branch: A git branch describes a certain state of the code base and the changes that lead there. A repository may contain many different branches at the same time, without the changes made on each affecting one another. To combine the changes of one branch with another, one can merge the branches.

Using these, git allows us to develop features independently and then, once they are ready, include them into the software on the develop branch.

More information on git can be found here and why git should be used can be found here.

While git by itself is a very powerful tool, it can be a bit tedious to set up a repository by yourself, without any third party assistance. Luckily, there are many sites that do most of that work for you and even add quite a few additional features on top of that. Notable are GitHub, GitLab and Bitbucket. While there are differences between these providers, they all do the same job: provide easy to use repositories and make online collaboration easier.

We will be using GitHub, the website you are on right now. One of the features you will be using extensively is a Pull Request (PR). After creating a branch and diverging from the main code base, you will want to see your changes applied. To do this, you can initiate the merging process by opening a PR from your branch into develop and waiting for others to review your changes. GitHub makes it very easy for others to see what changes you are introducing. This not only makes it easier for project leads to keep track of changes, but also lets developers initiate discussions around their work before integrating it with the rest of the code base.

Now that you understand what git and GitHub are and why we are using them, let's get you up and running with both of them.

To install git, open a terminal. If you don't know how to do this, try pressing Ctrl + Shift + T. Essentially all Linux distributions have a git package that can be installed through the corresponding package manager. For example, on Debian-based distributions like Ubuntu, you can run

1. Open a terminal. If you don't know how to do this, try Ctrl + Shift + T.

2. Practically all Linux distributions have a package called "git", which you can install using the package manager of your choice. On Debian-based distributions like Ubuntu, for example, you can run

   $ sudo apt update
   $ sudo apt install git
   

   to update the package database and install git.

3. Verify the installation by running

   $ git --version
   

The easiest way to install git on MacOS is by using Homebrew.

1. If you don't have Homebrew, please install it now.

2. Open a terminal, e.g. by pressing Ctrl + Opt + Shift + T.

3. Run the command

   $ brew install git
   

4. Verify the installation worked by running

   $ git --version
   

1. Download the installer here.
2. Run the installer and follow the steps within the setup wizard. You can change the configuration but the defaults should work just fine. Make sure you are installing git bash, too.
3. Try and run git bash to verify the installation worked as intended.

Alternatively:

1. Install Windows Subsystem for Linux (WSL).
2. Reboot.
3. Run WSL.
4. Follow the instructions for Ubuntu.

To work with the Software Team, you don't only need git, but also GitHub.

1. If you don't already have one, create a GitHub account.

2. In your terminal (git bash/WSL on Windows), run the following commands to make sure your contributions are attirbuted correctly:

   $ git config --global user.name <Your Name>
   $ git config --global user.email <[email protected]>
   

   Make sure you are using the same email adress as on your GitHub account.

3. We strongly recommend that you use SSH to connect to GitHub. This is strictly speaking not required because GitHub allows you to authenticate by other means, but it's more transparent and easier to reproduce. Follow this guide to set up SSH on your machine and your GitHub account.

command	usage	purpose
add	git add <name_of_file>	Add a change in the working directory to the staging area.
branch	git branch	Show a list of branches available on the working tree.
branch	git branch name_of_branch	Create a new branch with all the contents of the current branch.
checkout	git checkout name_of_branch	Switch to name_of_branch
checkout	git checkout -b name_of_branch	Create a new branch called name_of_branch and switch to that branch.
clone	git clone url_of_repository	Download a repository and its entire version history for the first time.
commit	git commit -m "<descriptive commit message>"	Save the changes from the staging area into a local commit.
log	git log --all	Shows all the commit logs.
pull	git pull	Download and incorporate changes made to the online version of the project, e.g. on GitHub.
push	git push	Upload your local commits; you may need to specify the upstream as indicated by the error message when pushing a locally created branch.
status	git status	Displays the state of the working directory and the staging area.

While there are many different ways of using git and GitHub, there are some rules you should follow.

1. Give descriptive short (50-80 characters) commit messages.
   • If the given character limit cannot be met, you should probably split your changes into more than one commit.
   • You can use git diff --cached to see which changes you are trying to commit.
   • You can use git add -p to select certain parts of the changes that you would like to commit.
2. If you are changing a specific module/subsystem, you should prefix the message with the appropriate identifier, e.g. "STM: Removed unused headers" for state machine.
3. Avoid ending the summary with a period.
4. Avoid generic commit messages like "Some changes", "Minor fixes", ...
5. Avoid enumerations. If you need to list multiple changes, you're probably violating rule 1.

More information can be found here.

1. Give meaningful branch names. Identifier of the specific module/subsystem will be used followed by the purpose of the branch.

   subsystem-purpose_of_branch
   

2. Never work on develop. All changes MUST be pushed to a separate branch and then merged by opening a PR.
3. PRs should never be merged without your PM's or the HoS's approval.

1. Go to GitHub, "Your Repositories and click "New"

2. Fill out the form and click "Create Repository".

3. Go to your repository and click the green "Code" button in the top right corner. Copy the link. Make sure you've selected HTTPS.

4. Launch your terminal (on Windows this should be WSL) and decide where you want to clone your repository. Use cd to change your working directory accordingly.

5. Run the following command: $ git clone <link_to_repo>. The output should look something like this:

   $ git clone [email protected]:MiltFra/hyped-git-exercise.git
   Cloning into 'hyped-git-exercise'...
   remote: Enumerating objects: 3, done.
   remote: Counting objects: 100% (3/3), done.
   remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
   Receiving objects: 100% (3/3), done.
   

   You may be asked to enter your GitHub credentials. If so, please do.

6. Change directories into the newly created folder and add some content. This could look something like this:

   $ ls
   README.md
   $ vim my-code.txt
   $ ls
   my-code.txt  README.md
   

   I used the editor Vim to something into my-code.txt. Which editor you use is of course not relevant, pick whatever you are comfortable with.

7. You can now add the newly created file to the staging area by using the git add command. Of course you can find out which files have changed by using git status first. This could look as follows:

   $ git status
   On branch master
   Your branch is up to date with 'origin/ master'.
   
   Untracked files:
     (use "git add <file>..." to include   in what will be committed)
           my-code.txt
   
   nothing added to commit but untracked   files present (use "git add" to track)
   $ git add my-code.txt 
   

8. The file is now added to the staging area. You can now apply all your changes in a single commit by using git commit. Remember to write a good commit message. For example:

   $ git status
   On branch master
   Your branch is up to date with 'origin/master'.
   
   Changes to be committed:
   (use "git restore --staged <file>..." to unstage)
           new file:   my-code.txt
   
   $ git commit -m "Add my-code.txt"
   [master 3c467f3] Add my-code.txt
   1 file changed, 1 insertion(+)
   create mode 100644 my-code.txt
   

9. Now that the changes have been commited locally, we can push them to the master branch of our repository. Simply run git push:

   $ git push
   Enumerating objects: 4, done.
   Counting objects: 100% (4/4), done.
   Delta compression using up to 8 threads
   Compressing objects: 100% (2/2), done.
   Writing objects: 100% (3/3), 295 bytes | 295.00 KiB/s, done.
   Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
   remote: This repository moved. Please use the new location:
   remote:   https://github.com/MiltFra/hyped-git-exercise.git
   To https://github.com/miltfra/hyped-git-exercise
   6c41cb2..3c467f3  master -> master
   

Congratulations! You have successfully applied the very basics of git. You can check your online repository to confirm that your file has been added and your commit message is visible.

In this example, you will be learning how to create a new branch, how to switch branches and how to push that branch onto GitHub. You will also learn how to create a pull request and finally how to merge that branch with the “master” branch. You can use the previous repository you created.

1. Since you are not the only one contributing to the git repositories of HYPED, you should always ensure you are including the most recent changes by running git pull before making any modifications. Of course, you need to make sure you are in the right folder, e.g. the hyped-git-exercise folder from 4.1. It should look something like this:

   $ git pull
   Already up to date.
   

2. Branching is one of the most important features of git. It helps to keep the "master" branch in a stable state and keeps bugs to a minimum. By creating a branch you create your own version of the code base which you can modify as you see fit. You will start with all the files that are on the branch you are currently on.

   Creating a branch is simple: Just run git branch <name_of_branch> as follows:

   $ git branch
   * master
   $ git branch sns-fake_imu
   $ git branch
   * master
     sns-fake_imu
   

   As you can see, we have created a new branch called sns-fake_imu which contains all the files that are currently on master.

3. Before you start coding, you should switch to your new branch. This can be done by running git checkout as follows:

   $ git branch
   * master
     sns-fake_imu
   $ git checkout sns-fake_imu
   Switched to branch 'sns-fake_imu'
   $ git branch
     master
   * sns-fake_imu
   

4. You can now make the changes you want without affecting the master branch. After making changes you should commit them as in 4.1.

   $ ls
   my-code.txt  README.md
   $ vim my-code-better.txt
   $ ls
   my-code-better.txt  my-code.txt  README.md
   $ git status
   On branch sns-fake_imu
   Untracked files:
   (use "git add <file>..." to include in what will be committed)
           my-code-better.txt
   
   nothing added to commit but untracked files present (use "git add" to track)
   $ git add my-code-better.txt
   $ git commit -m "SNS: Add better code"
   [sns-fake_imu b6e76c9] SNS: Add better code
   1 file changed, 1 insertion(+)
   create mode 100644 my-code-better.txt
   $ git status
   On branch sns-fake_imu
   nothing to commit, working tree clean
   

5. Now that you have committed your changes, you want to upload them from your machine to the HYPED repository. To do this, we use git push. However, since you are working on a new branch, you will have to tell git where to upload the changes to. We do this by using the --set-upstream flag like so:

   $ git push --set-upstream origin sns-fake_imu
   Enumerating objects: 4, done.
   Counting objects: 100% (4/4), done.
   Delta compression using up to 8 threads
   Compressing objects: 100% (2/2), done.
   Writing objects: 100% (3/3), 316 bytes | 316.00 KiB/s, done.
   Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
   remote: This repository moved. Please use the new location:
   remote:   https://github.com/MiltFra/hyped-git-exercise.git
   remote: 
   remote: Create a pull request for 'sns-fake_imu' on GitHub by visiting:
   remote:      https://github.com/MiltFra/hyped-git-exercise/pull/new/sns-fake_imu
   remote: 
   To https://github.com/miltfra/hyped-git-exercise
   * [new branch]      sns-fake_imu -> sns-fake_imu
   Branch 'sns-fake_imu' set up to track remote branch 'sns-fake_imu' from 'origin'.
   

6. Now, you will need to let everyone else know that you would like to include your changes in the main software by opening a PR. To do this, go to your repository, select the "Pull requests" tab, press the green "New" button and select your branch in the right drop down menu that says "compare". Now you can select "Create pull request".

7. You should now give a short but descriptive title of what your changes are aiming to achieve and elaborate further in the section below. In particular, you should list all the individual changes you have made and why they are necessary. When you are done, create the PR by pressing the button in the bottom right corner.

8. If you were working on the main HYPED repository, several checks would now run and you would not be able to merge your code without at least two approvals. Since you are on your own repository however, you can go to the bottom of the page and select "Merge pull request" and delete the branch when you are done.

9. Go back to the main page of your repository, make sure you have selected the master branch in the top left corner, and observe that the changes you made on your new branch are now incorporated into the main code base.

Congratulations, you have successfully made a contribution by using a separate branch!