Git Basics

Original author: Johnathan

Modified by Henry Loi (hchloi@connect.ust.hk)

Reference from HKUST-Robotics-Team-SW-Tutorial-2021

This document aims to provide the reader with a sense of how the git version control system works and provide a simple, hands-on demonstration. Git is complex and this tutorial only demonstrates the basic essentials.

Overview

What is Git and GitHub?

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
GitHub is designed as a Git repository hosting service. You can share your code and giving other users to make revisions and edits.

Basic Workflow

You and your friend clone a repository from GitHub. A local copy now exists on both your machines.
You make changes in your IDE.
You add and commit those changes. The local repo now registers this commit.
You push your changes. The online (aka remote) repo now shows these changes.
Your friend pulls your changes. Their local copy now shows those changes. To clarify, before pulling, your friend still had the copy from the beginning (no change). But after pulling, the local copy is updated.

Conflict/Merge Workflow

You and your friend clone a repository.
You and your friend make changes.
You add and commit your changes.
Your friend adds and commits their changes.
You push your changes.
Your friend pulls your changes.
Your friend merges the code. This may require a closer inspection and decision into each conflict.

Terminology

Most definitions provided simplify the concepts a bit in an attempt to make them digestable. (Some were copied from online.) Google the term for more details (e.g. "git push").

Repository (repo)

A centralised place to store files and resources. (Kinda like Google Drive or Dropbox.)

Commit

(n.) A commit is a revision, an individual change to a file (or a set of files). These revisions are tracked by a unique ID (a hash).

To commit (v.) a change (or a file, or something) means to create a commit (n.). In most cases, this commit will only be stored in the local repository until you push.

Clone

Copy the contents of a repository (normally to your local side).

Checkout

Navigate between branches and commits. Your local repository will be updated.

Push

Upload your local commits to the remote (online) repository.

Pull

Download the remote repository and update your local repository.

Branches

Branches allow you to make commit and push while maintaining independence from other people's commits.

You can think of the default branch (normally called master) as the tree trunk, and other branches would branch off and diverge with their own changes.

Merge

When two branches are combined together. The changes from the incoming branch is applied to the current branch. If a file could not be resolved, a merge conflict will occur.

Working

There are multiple ways of working with Git. If your repo is on Github, you can edit text files directly in the Github editor. However, it is often more convenient to work with a local IDE.

Locally, you can directly use Git commands in the terminal. Another (often visually more convenient) way is to use a Git client, which is typically software designed to interface with the Git terminal commands. Some examples of Git clients are:

Github Desktop: Minimal, works well with Github repos
Sourcetree: Complete, many buttons
Git Graph: VSCode extension
Sublime Merge
Git Kraken

You can try them out to see which one suits you. For the purpose of this document, we'll stick to Github Desktop. Any other client should be able to do what Github Desktop can do.

If you're using the terminal, you can find documentation for a command by typing man git <command> or git <command> --help.

You can try out the following steps by creating a new repo solely for testing and playing around with. (To create a repo, click the + icon at the top right.) For the shell examples, we'll be using a fake Example repo. You can replace this with a repo of your choice.

Setup Workflow

There are several ways to setup a Github repository. Here we'll just focus on cloning a repository from online.

First you'll want to clone the repository.

1. Github Desktop (Suggested)

Click the green Code button.
Click Open with Github Desktop.
Specify a local path (default is ok).
Press Clone.

2. Shell

This shell command will clone the repository to a folder in the current directory. The folder will have the same name as the repo.

git clone https://github.com/HKUST-Robotics-Team/Example

You can add a second path to specify a folder to clone to.

git clone https://github.com/HKUST-Robotics-Team/Example path/to/your/repo

Development Workflow - Commit

Perhaps you've made some changes on the local side. Maybe you edited some code, moved some files or deleted some junk. It's time to sync up the remote repo with your local copy.

But first we need to update our local repository with the changes. Let's make a commit.

1. Github Desktop (Suggested)

Check which files you want to commit.
Write a commit message. This is sometimes pre-generated.
Write a commit description (optional).
Press Commit to .... (Ctrl/Cmd + Enter)

2. Shell

At this point, it is crucial that your current directory is in the repo.

cd path/to/your/repo

You can run pwd to check that you're in the right folder and run git status to check that you're in a git environment.

% pwd
/Users/Robotics/Documents/path/to/your/repo

% git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

When making commits, generally the process follows:

git add .
git commit -m "(sensible message, preferrably describing what you changed and why)"

git add stages your files, selecting them for a commit. The files haven't been committed yet, but they have been selected. We git add . to add modified files in the current directory. You can be more selective and select individual files or folders by specifying them (e.g. git add main.cpp, git add some-folder/).

git commit commits your staged files. We use the -m flag, followed by a string, to write a commit message. Typically, commit messages should describe what changes you've made in the commit and why you've made them.