Git Basics
Last updated
Last updated
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.
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.
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.
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.
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").
A centralised place to store files and resources. (Kinda like Google Drive or Dropbox.)
(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.
Copy the contents of a repository (normally to your local side).
Navigate between branches and commits. Your local repository will be updated.
Upload your local commits to the remote (online) repository.
Download the remote repository and update your local repository.
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.
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.
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.
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.
Click the green Code button.
Specify a local path (default is ok).
This shell command will clone the repository to a folder in the current directory. The folder will have the same name as the repo.
You can add a second path to specify a folder to clone to.
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.
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)
At this point, it is crucial that your current directory is in the 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.
When making commits, generally the process follows:
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.
Now you want to upload your changes to the remote repository.
Press the push button in the top row. (Ctrl/Cmd + P)
If there are no merge conflicts and you have a stable connection, you're done!
Simplest command:
If there are no merge conflicts and you have a stable connection, you're done!
Branches allow you to make commit and push while maintaining independence from other people's commits.
Click Open with Github Desktop.
Press Clone.
