|
| 1 | +# Git Basics |
| 2 | + |
| 3 | +#### Original author: Johnathan |
| 4 | + |
| 5 | +Modified by Henry Loi ( [email protected]) |
| 6 | + |
| 7 | +_Reference from HKUST-Robotics-Team-SW-Tutorial-2021_ |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +## Overview |
| 12 | + |
| 13 | +### What is Git and GitHub? |
| 14 | + |
| 15 | +* 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. |
| 16 | +* GitHub is designed as a **Git repository hosting service**. You can share your code and giving other users to make revisions and edits. |
| 17 | + |
| 18 | +### Basic Workflow |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +1. You and your friend clone a repository from GitHub. A _local copy_ now exists on both your machines. |
| 23 | +2. You make changes in your IDE. |
| 24 | +3. You **add** and **commit** those changes. The _local_ repo now registers this commit. |
| 25 | +4. You **push** your changes. The _online_ (aka remote) repo now shows these changes. |
| 26 | +5. 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. |
| 27 | + |
| 28 | +### Conflict/Merge Workflow |
| 29 | + |
| 30 | +1. You and your friend clone a repository. |
| 31 | +2. You **and your friend** make changes. |
| 32 | +3. You add and commit your changes. |
| 33 | +4. Your friend **add**s and **commit**s their changes. |
| 34 | +5. You push your changes. |
| 35 | +6. Your friend **pulls** your changes. |
| 36 | +7. Your friend **merges** the code. This may require a closer inspection and decision into each conflict. |
| 37 | + |
| 38 | +## Terminology |
| 39 | + |
| 40 | +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"). |
| 41 | + |
| 42 | +### Repository (repo) |
| 43 | + |
| 44 | +A centralised place to store files and resources. (Kinda like Google Drive or Dropbox.) |
| 45 | + |
| 46 | +### Commit |
| 47 | + |
| 48 | +(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). |
| 49 | + |
| 50 | +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. |
| 51 | + |
| 52 | +### Clone |
| 53 | + |
| 54 | +Copy the contents of a repository (normally to your local side). |
| 55 | + |
| 56 | +### Checkout |
| 57 | + |
| 58 | +Navigate between branches and commits. Your local repository will be updated. |
| 59 | + |
| 60 | +### Push |
| 61 | + |
| 62 | +Upload your local commits to the remote (online) repository. |
| 63 | + |
| 64 | +### Pull |
| 65 | + |
| 66 | +Download the remote repository and update your local repository. |
| 67 | + |
| 68 | +### Branches |
| 69 | + |
| 70 | +Branches allow you to make commit and push while maintaining independence from other people's commits.  |
| 71 | + |
| 72 | +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. |
| 73 | + |
| 74 | +### Merge |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +## Working |
| 79 | + |
| 80 | +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. |
| 81 | + |
| 82 | +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: |
| 83 | + |
| 84 | +* [Github Desktop](https://desktop.github.com/): Minimal, works well with Github repos |
| 85 | +* [Sourcetree](https://www.sourcetreeapp.com/): Complete, many buttons |
| 86 | +* Git Graph: VSCode extension |
| 87 | +* Sublime Merge |
| 88 | +* Git Kraken |
| 89 | + |
| 90 | +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. |
| 91 | + |
| 92 | +If you're using the terminal, you can find documentation for a command by typing `man git <command>` or `git <command> --help`. |
| 93 | + |
| 94 | +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. |
| 95 | + |
| 96 | +### Setup Workflow |
| 97 | + |
| 98 | +There are several ways to setup a Github repository. Here we'll just focus on cloning a repository from online. |
| 99 | + |
| 100 | +First you'll want to clone the repository. |
| 101 | + |
| 102 | +#### 1. Github Desktop (Suggested) |
| 103 | + |
| 104 | +1. Click the green Code button. |
| 105 | +2. Click Open with Github Desktop.  |
| 106 | +3. Specify a local path (default is ok). |
| 107 | +4. Press Clone.  |
| 108 | + |
| 109 | +#### 2. Shell |
| 110 | + |
| 111 | +This shell command will clone the repository to a folder in the current directory. The folder will have the same name as the repo. |
| 112 | + |
| 113 | +```sh |
| 114 | +git clone https://github.com/HKUST-Robotics-Team/Example |
| 115 | +``` |
| 116 | + |
| 117 | +You can add a second path to specify a folder to clone to. |
| 118 | + |
| 119 | +```sh |
| 120 | +git clone https://github.com/HKUST-Robotics-Team/Example path/to/your/repo |
| 121 | +``` |
| 122 | + |
| 123 | +### Development Workflow - Commit |
| 124 | + |
| 125 | +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. |
| 126 | + |
| 127 | +But first we need to update our local repository with the changes. Let's make a commit. |
| 128 | + |
| 129 | +#### 1. Github Desktop (Suggested) |
| 130 | + |
| 131 | +1. Check which files you want to commit. |
| 132 | +2. Write a commit message. This is sometimes pre-generated. |
| 133 | +3. Write a commit description (optional). |
| 134 | +4. Press Commit to .... (Ctrl/Cmd + Enter) |
| 135 | + |
| 136 | + |
| 137 | + |
| 138 | +#### 2. Shell |
| 139 | + |
| 140 | +At this point, it is crucial that your current directory is in the repo. |
| 141 | + |
| 142 | +```sh |
| 143 | +cd path/to/your/repo |
| 144 | +``` |
| 145 | + |
| 146 | +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. |
| 147 | + |
| 148 | +> ``` |
| 149 | +> % pwd |
| 150 | +> /Users/Robotics/Documents/path/to/your/repo |
| 151 | +> |
| 152 | +> % git status |
| 153 | +> On branch main |
| 154 | +> Your branch is up to date with 'origin/main'. |
| 155 | +> |
| 156 | +> nothing to commit, working tree clean |
| 157 | +> ``` |
| 158 | +
|
| 159 | +When making commits, generally the process follows: |
| 160 | +
|
| 161 | +```sh |
| 162 | +git add . |
| 163 | +git commit -m "(sensible message, preferrably describing what you changed and why)" |
| 164 | +``` |
| 165 | +
|
| 166 | +`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/`). |
| 167 | + |
| 168 | +`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. |
| 169 | + |
| 170 | +### Development Workflow - Push |
| 171 | + |
| 172 | +Now you want to upload your changes to the remote repository. |
| 173 | + |
| 174 | +#### 1. Github Desktop |
| 175 | + |
| 176 | +1. Press the push button in the top row. (Ctrl/Cmd + P) |
| 177 | +2. If there are no merge conflicts and you have a stable connection, you're done! |
| 178 | + |
| 179 | + |
| 180 | + |
| 181 | +#### 2. Shell |
| 182 | + |
| 183 | +Simplest command: |
| 184 | + |
| 185 | +``` |
| 186 | +git push |
| 187 | +``` |
| 188 | + |
| 189 | +If there are no merge conflicts and you have a stable connection, you're done! |
0 commit comments