├── images ├── vcs.jpeg └── git_in_github_overview.png ├── LICENSE └── README.md /images/vcs.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Machine-Academy/git-workflow/HEAD/images/vcs.jpeg -------------------------------------------------------------------------------- /images/git_in_github_overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Machine-Academy/git-workflow/HEAD/images/git_in_github_overview.png -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Machine-Academy 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Git & GitHub 2 | 3 | Learning Git / GitHub workflow 4 | 5 | # Table of Contents 6 | 7 | - [What is Git](#what-is-git) 8 | - [What is GitHub](#what-is-github) 9 | - [Terminology](#terminology) 10 | - [Installing Git](#installing-git) 11 | - [Initial Setup](#initial-Setup) 12 | - [Common Git Commands](#common-git-commands) 13 | - [Staging Files](#staging-files) 14 | - [Committing Changes](#committing-changes) 15 | - [Pushes](#pushes) 16 | - [Pulls](#pulls) 17 | - [Branches](#branches) 18 | - [Moving between Branches](#moving-between-branches) 19 | - [Logs](#git-log) 20 | - [Git Man Page](#git-manual) 21 | - [Common Workflow](#common-workflow) 22 | - [Merge a Branch](#merge-a-branch) 23 | - [Deleting Branches](#deleting-branches) 24 | - [Forks and Pull Request](#fork-and-pull-request) 25 | - [Visual Aid](#a-visual-aid) 26 | - [Videos](#videos) 27 | - [Other Web Resources](#web-resources) 28 | 29 | ## What is Git 30 | Git is a version control system, its a way for us to track changes in our code locally, manage a project locally and many other things. Git and GitHub are in no way connected to one another rather they are two separate tools. Git is a way to track, save and manage changes within your code and GitHub is a place where you can safely store your code as a backup. Git is a CLI tool while GitHub is a web application / collaborative space for developers. 31 | 32 | ## What is GitHub 33 | GitHub is a place where you are able to store, share and collaborate with others on project and code. GitHub is free to use and is  34 | one of many places where code can be stored online for free. We use GitHub to  35 | store code as a backup, over time you will have many projects and code bases that will end up taking lots of space on your machine, its also a place where you can backup your code. Should your computer hard drive or SSD ever go corrupt your code is safe in GitHub. 36 | 37 | NOTE: Other than GitHub there are other platforms like it such as GitLab, BitBucket ect. All of them server the same purpose with slight variations in what the platform offers as extra features. Through out our journey however we will stick to using GitHub, but feel free to use whatever you want! 38 | 39 | ## Terminology 40 | 41 | - repository → The "directory" or folder that contains the code, but is tracked by Git 42 | - remote → A repository on GitHub (or on another machine / server) 43 | - branch → A split from the current branch, allows for new features without altering the functioning code in a code base 44 | - un-tracked → New file / directory that is not tracked by Git 45 | - tracked → Changes are being tracked by Git 46 | - staged → The file(s) is added but the changes have not been committed (saved) yet 47 | - commit → All changes are saved and a 'snapshot' is made of the current state of the code (on your local machine) 48 | - push → Push the changes (commits) to the origin (local repository) or remote repository 49 | - pull → Pull changes from a remote to your local repository (will pull the changes to the matching branch; main (remote) → main (local)) 50 | 51 | ## Installing Git 52 | 53 | In order to install Git on your system either refer to the commands (\*nix based) or 54 | refer to the Git-SCM page and find the correct system specs. 55 | 56 | - Debian Based Distros (Pop_Os!/Ubuntu/LinuxMint) 57 | ``` 58 | sudo apt install git 59 | ``` 60 | 61 | 62 | - Arch Based (Arch, Manjaro, Endeavour, ArcoLinux) 63 | ``` 64 | sudo pacman -S git 65 | ``` 66 | 67 | - Git first time setup 68 | 69 | [Git - First-Time Git Setup](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) 70 | 71 | 72 | 73 | ## Initial Setup 74 | 75 | ```bash 76 | git config --global user.name "John Doe" 77 | git config --global user.email johndoe@example.com 78 | ``` 79 | 80 | the above commands need to be ran once in order to use git properly. Be sure to replace "John Doe" with your name and the email "johndoe@example.com" with your email 81 | 82 | ## Common Git commands 83 | 84 | ### Cloning a project 85 | 86 | ```bash 87 | git clone 88 | ``` 89 | 90 | Clone / download a repo (project) onto your computer, in the current directory / folder you are in 91 | 92 | EX: `git clone [https://github.com/Machine-Academy/git-workflow.git](https://github.com/Machine-Academy/git-workflow.git)` 93 | 94 | ### Staging Files 95 | 96 | ```bash 97 | git add . 98 | ``` 99 | 100 | Add all changed files and folders, in the current folder you are in, into the `staging` area 101 | 102 | ex: git add . 103 | 104 | NOTE: . (dot) represents the current directory / folder that you are in. 105 | 106 | ```bash 107 | git add fileName [file2, file3 ....] 108 | ``` 109 | 110 | Add individual file(s) to the staging area, to be committed 111 | 112 | ### Committing Changes 113 | 114 | ```bash 115 | git commit -m "commit message" 116 | 117 | # Optionally for Git clout 118 | git commit -m "commit type: general message 119 | 120 | details about the commit here" 121 | ``` 122 | 123 | - Git Commits: Semantic Commits 124 | 125 | [Semantic Commit Messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716) 126 | 127 | When you commit code, you need to create a message, these messages are very useful for your self and others to understand changes that were made in the code at the specific point in time. This is really useful for when you want to `rollback` changes you made in your project 128 | 129 | ### Pushes 130 | 131 | ```bash 132 | git push origin 133 | ``` 134 | 135 | Push code back up to GitHub in the specified branch 136 | 137 | ex: git push origin main OR git push origin dev 138 | 139 | ### Pulls 140 | 141 | ```bash 142 | git pull 143 | ``` 144 | 145 | Pull new code down from remote repository (GitHub repo) into the current branch you are in. 146 | 147 | ### Branches 148 | 149 | ```bash 150 | git checkout -b 151 | ``` 152 | 153 | Create and move into a new branch 154 | 155 | ex: git checkout -b testing (create a new branch called testing an move into it) 156 | 157 | ### Moving between branches 158 | 159 | ```bash 160 | git checkout 161 | ``` 162 | 163 | Change your working branch, to a already existing branch. 164 | 165 | ex: git checkout dev (change to the existing branch named "dev") OR git checkout main (change to the existing branch named "main") 166 | 167 | 168 | ### Git Log 169 | 170 | ```bash 171 | git log 172 | ``` 173 | 174 | Show the commit history of the repo (project) 175 | 176 | 177 | ### Git Manual 178 | 179 | ```bash 180 | man git 181 | ``` 182 | 183 | ## Common Workflow 184 | 185 | One of the most common problem when people are starting to use git, is to do all of their changes into the master/main branch, and that is not how you should be using git from day to day. 186 | 187 | Let's say that we are working on adding a new feature to a app. A good workflow would look 188 | something like: 189 | 190 | ``` 191 | git branch -b 192 | 193 | # or 194 | 195 | git branch 196 | git checkout 197 | 198 | ``` 199 | 200 | **HINT** you can see the available branches on your repo by typing `git branch`. 201 | The branch you're currently on will be indicated by a asterisk and, 202 | if your shell allows it, a different color. 203 | 204 | After committing the changes, if you want to push the branch to your remote repository then: 205 | 206 | ``` 207 | git push -u origin calc-devide 208 | 209 | git branch -a 210 | 211 | ``` 212 | 213 | For more in-depth information on the flags used above, you can use the command `man git` or `git push --help` 214 | 215 | ## Merge a Branch 216 | 217 | After adding a branch, doing some change and finishing adding your features (please run the tests.) we are ready to merge that branch to main/master. 218 | 219 | git checkout master # Changing branch to master/main on GitHub/ other remote 220 | git pull origin master # Pulling the changes that could have been done before we merge our feature 221 | git branch --merged # This shows the branches that you already merged so far. 222 | git merge 223 | git push origin master 224 | git branch --merged # The new branch that was just merged should show here. 225 | 226 | 227 | ## Deleting Branches 228 | 229 | Now that the merge was done, and you added the feature you needed. You can delete this branch. 230 | 231 | ``` 232 | git branch -d 233 | ``` 234 | 235 | This command will delete the desired branch, but this change was just made locally. 236 | 237 | - If you want to delete the branch from the remote repo as well: 238 | 239 | ``` 240 | git push origin --delete 241 | ``` 242 | 243 | ## Fork and Pull Request 244 | 245 | On GitHub (and most other git related sites), you can fork a project and then begin making edits 246 | to the source code. This is useful for when you want to help build a project or improve a feature 247 | but are not a direct contributor or active maintainer. 248 | 249 | On GitHub, find a project that you may want to use / modify / contribute towards. On the repo's page 250 | you will see a "Fork" button on the upper righthand side of the screen. 251 | 252 | Click that and then you will be one step closer to writing code! Now that it's done, 253 | you can clone *your* version of this repo to your local machine and begin making edits. Once you have 254 | the change you would like to see (and meet any testing requirements) then you can go back to the 255 | ***Main*** project repo and open a new Pull Request. 256 | 257 | Note: You may have to specify what branches to compare against (you want to compare *your* version against *main* -- or whatever branch should be modified). 258 | 259 | Once this is done (meaning the PR is open) the project owner will then review the PR (or ignore it ... which can happen) and leave feedback or accept the changes. 260 | 261 | --- 262 | 263 | ## A Visual Aid 264 | 265 | ![Visual of Git flow](./images/vcs.jpeg) 266 | 267 | Or another example with a cloud based service such as GitHub: 268 | 269 | ![Visual of Git flow including a remote cloud repo](./images/git_in_github_overview.png) 270 | 271 | ## Videos 272 | 273 | - Web Dev Simplified 274 | 275 | [Learn Git in 20 Minutes](https://www.youtube.com/watch?v=IHaTbJPdB-s) 276 | 277 | - Fireship 278 | 279 | [Git It? How to use Git and GitHub](https://www.youtube.com/watch?v=HkdAHXoRtos) 280 | 281 | - Brad Traversy 282 | 283 | [Git & GitHub Crash Course For Beginners](https://www.youtube.com/watch?v=SWYqp7iY_Tc) 284 | 285 | - Learn Code Academy 286 | 287 | [GitHub Tutorial For Beginners - GitHub Basics for Mac or Windows & Source Control Basics](https://www.youtube.com/watch?v=0fKg7e37bQE) 288 | 289 | ## Web Resources 290 | 291 | - [Web app for git commands / help](https://gitexplorer.com/) 292 | --------------------------------------------------------------------------------