Why use Git

We use git for version control. This gives us several advantages.

1. This lets us work on code while it's running elsewhere
2. If we make a mistake we can revert to a previous working version
3. This allows for multiple people to work on the project simultaneously from different computers.

General Git workflow

In git we have 2 main versions of our code. Main and Dev. Main is where our current running process is. Dev has updates that we're testing. If it passes the tests, we merge dev into main so main has all the new code.

the Structure looks like this.

• Master/Main <— Dev <— Task Branches

You'll notice that dev has task branches coming off of it. That's where we do all of our coding. the branch will be a copy of dev that we work on. Then when its done we'll merge the branch into Dev to be tested.

Key points:

• Main holds our "production" code and should always be working.
• Dev should also be in a “working state” meaning the code compiles and runs.
• Once tested Dev gets merged to main.
• We work on branches off of Dev and merge to Dev when we're done.
• Nobody ever makes changes directly to main or dev. always done through branches off dev.

Cloning (downloading) a git repository onto your computer

*Note: all of these steps are done on a Unix based command line. if you're on a mac you don't need to do anything different. if you're on windows you can download a Unix based command line program. for example Git Bash.

1. Download Git

https://git-scm.com/downloads

2. Navigate to wherever you want the code on your computer

Use cd (change directory) command to navigate through the folders (directories) on your computer

cd path/where/you/want/your/code

3. Clone the repository

Go to the github repository you want to clone. there is a green button that says code towards the top. Click it and it will give you a https link to use in the next step.

use the "git clone" command to clone the repository

git clone https://github.com/fake_github_repo.git

Note: git, github and git bash are 3 distinct things. git: a version control software. manages branches, conflicts ect.. github: online code backup, storage, and sharing service powered by git git bash: a local Unix based command line program. made by the makers of git

Making new branches

1. Check branches

now that the repository is on your computer use the "git branch" command to see the available branches

# Shows branches on your machine
git branch

You should see main, dev, and maybe some other ones that people are working on. There's probably a star on main. meaning that's the branch you're currently on

2. Switch to dev branch

use "git checkout" to switch to the dev branch. when you do this a bunch of the files might change on your computer. Its an entirely different version of the code! then do git pull to make sure dev is synced online.

# swiches to dev branch then pulls the lastest version from github
git checkout dev
git pull 

3. Create a new branch

use "git checkout -b" to create and switch to your new branch.

# Creates and switches to new branch
git checkout -b nameOfNewBranch

Since you had dev checked out before, your new branch has a copy of the dev code that you can change. you branched off of dev.

How to use your branch (add, commit, push)

1. add or change some files

add a new file to your branch. use the nano command to make and edit a text file

# use nano editor to create and edit new file
nano example.txt

once you're done writing something ctrl o saves and ctrl x exits.

2. push your changes to Github.

You need 3 commands to push your changes to Github. "git add ." this adds all your file to the git stage. only staged files will saved locally or online by git. "git commit" this commits the change to your branch along with a message. now it's an official local version. you can revert to previous commits or make more. "git push" This sends your commits to Github and saves everything online.

Note "git add ." will only track added and updated files where "git add -A" will also track files you deleted. or in other words use -A if you want to delete files from previous commits and the online backup

# save code and upload to github
git add .
git commit -m "added example.txt"
git push

Note: your first time pushing to github it might come up with an error. it will say something about having an unset upstream. use the command it suggests to set the upstream path. This tells git where to send your code when you push online

3. See your changes on Github

Navigate to the repository on github.com and look for your branch. then look for the file you added. your new file should be saved online!

Merge changes into dev

Now that you have a branch with committed changes, let's put your changes onto the dev branch so they can be tested.

1. Make sure you have dev's latest changes

Before you put your changes onto dev, you want to make sure you have the latest version of dev. For example somebody else may have merged changes into dev now it's incompatible with the version you originally branched off of.

# updates your brach with dev's changes then uploads to github
git pull origin dev
git push

This will update your branch, but all of your changes will still be there.

IMPORTANT: run this command frequently so you always have the most updated version of the project. You should run this daily

2. Create a pull request

Now to merge your code into dev we need to create a pull request. You do this on github.com. it requests pulling your code into dev. to do this you'll need to:

• go to the github repository online
• navigate to the pull request tab
• start a new request. Dev pulls your branch. dev <--- newBranch
• add your team lead as a reviewer

IMPORTANT: By default the pull request will try to pull into main. make sure you're pulling into dev and not main

Now your team lead will review all your code. If it looks good they will merge it into dev.

Delete your branch

now that your task branch is complete you can delete it. you can't delete a branch that you have checked out. You'll have to switch to dev first.

# Switch to dev branch then delete old task branch
git checkout dev
git branch -d branchName

This will delete the branch off of your computer. The online backup on github might still exist though. Normally the team lead will delete the online backup when they finish the pull request, but if they didn't you can run this command.

# Deletes online backup of branch from Github
git push origin -d branchName

Remember all your code is merged into dev now, so there's no reason to keep the old task branch or it's backup.

Done!

now you've completed a normal workflow! you will repeat the process of creating a branch and merging it to dev for every task you complete.

Trouble shooting

git wont let you switch branches because of "untracked files"

this means you have edits or new files that you want on a specific branch, but git wont let you switch. For example let's say you accidentally make some edits on main or dev that should be on your branch. To solve this you can stash the changes and move them to another branch

git add . # stage the chages to track them
git stash  # stash all the changes
git checkout branchName  # Switch branches
git stash pop  # get you changes out of the stash

git requires my username and pass for every push/pull

you can save your credentials locally and tell git to look there instead of asking you. Don't store your github password this way. use github's access tokens instead.

cd ~
git config --global credential.helper store
echo "https://${username}:${access_token}@github.com" > ~/.git-credentials

How to undo a commit

let's say you committed something that you didn't want to. for example a large image directory that is too big for github to back up.

# undoes most recent commit
git reset HEAD^

all your changes from the latest commit are still there, but you can edit/remove what you want then commit again.