Overview

This document outlines how I use git in order to do development work. These are guidelines and not actual rules.

Step 1: Clone

The first thing we need to do is get the remote repo to be local. We do that by cloning the repo. As an example, if you wanted to do work on the beardedtim/my-little-nlp repo, you would run the following to clone it to a local folder:

# using SSH
git clone [email protected]:beardedtim/my-little-nlp.git

# using HTTPs
git clone https://github.com/beardedtim/my-little-nlp.git

This will take the code that is at beardedtim/my-little-nlp and copy it to your local computer inside of the my-little-nlp folder that it will create. If you want to name the folder something different on your local machine, you can do that by adding the folder name after the URL

git clone <url> folder-name

For example, running git clone [email protected]:beardedtim/my-little-nlp.git my-clone would clone the repo into the folder my-clone.

Once you have cloned the repo, you can now cd my-little-nlp or cd <folder-name> if you changed the folder name. Once you are inside of the repo folder on your local machine, you can move onto step 2

Step 2: Create a branch

Once you cd into the repo folder locally, you are on the master branch most likely. In order to do any work, you must create a new branch. You don't actually have to do this and you can do everything on master but you're shooting yourself in the foot if you don't create new branches.

To create a new branch, from the root of your project run:

git checkout -b <branch-name>

So if I wanted to create a branch called feature/update-username, I would run the following from the root directory of the repo

git checkout -b feature/update-username

If you get an error saying <branch-name> is already a branch, that means you already created the branch and do not need to pass the -b flag and instead run git checkout <branch-name> to move to that branch.

Once you are no longer on the master branch, you can move onto step 3

Step 3: Commit Changes

The entire point of git is to allow you to make changes without affect the master branch. We do this by making all of our changes on the branch you created or checked out into in step #2.

Once you have checked out into a new branch, any work you do to the files will be tracked on that branch.

For instance, if you ran git checkout -b blah and then changed some files, those files would be lost if you git checkout master. In order to keep those changes, you need to commit them to the blah branch. Think of commiting as saving a word document: do it often and liberally.

# edit some file
cat "Hello world!" > file.txt

# Add the changes to git
git add .

# commit the changes to git
git commit

Once you have commited the changes and given them good commit messages, you can move onto step #4

Step 4: Create Pull Request

Once you have your changes on your blah branch to where you'd like them or to a point where you feel you need review, it is time to create a pull request. To do that on Github, you need to push the blah branch to origin(the github thing).

We do that by running the following:

git push

This will give you an error the first time you do this, when the blah branch has never been pushed to origin. To fix this error, follow the error message or type the following

git push -u origin

That will push the blah branch to the origin server, which happens to be github. Once the branch is on github, you can create a Pull Request in step #5

Step 5: Create PR

Once the branch is up on GitHub, you can create a Pull Request. You can do this vai hub cli or via the github gui. To do so on the GUI, you go to the URL that houses the repo. you should see a big orange/yellow button that says "Create PR for blah branch". Clicking that will take you to the form to create the PR.

Once the PR has been reviewed and everyone likes it, you can move onto step #6

Step 6: Merge PR into Master

The code is in a PR branch, the PR has been approved. It's time to merge that bad boy!

There is a big green button on the PR page that merges the things. BE CAREFUL! Anything that merges to master should be a working codebase. If you break the build, it will be bad new bears.

Step 6.b: Update Local Branches

Once master is updated, you need to git pull the changes to your local master branch, along with merging the new master branch into any feature branches you're working on.

For example, say I have two branches locally, master and foo. A PR goes out that updates the master branch on origin. I need to update my master branch and then update my foo branch based on it.

# ensure you are on master locally
git checkout master

# ensure that master is up to date with origin
git pull

# check out to foo branch
git checkout foo

# update foo with the updates on master
git merge master

Note: The goal here is to keep your local changes up to date with master

beardedtim/index.md