3 of 12

Image of Overall Structure of Repository

Our group GitHub repository (online)

These are the copies of our code that are kept in the repo:

MAIN: source-of-truth, end version for deployment

DEV: working copy that has all our merged code in it. We all share this.

INDIVIDUAL WORKING BRANCH: where you complete your coding task

No interaction with main occurs until ready for deployment

Merges from individual working branches into dev are controlled by branch protection rules set by the admin, usually involving pull requests and approvals of your code by another collaborator

The individual working branches that are stored in the repository are basically records of the code you have merged into dev.

Working in this way, abstracted away from our shared code bank, means that if we create a breaking error we can’t fix, we can revert to dev and reset our version. No code lost!

To view all the branches, on our repository’s main page, follow the images below:

Click here

dev is set as the default branch, which means all changes we push up from our local working branches merge into this one.

The local branches (and main) are listed here. I called this branch `nkc-1` when I created it. It’s where I’m making all my changes, and I’ll merge it into dev when my most recent task is done.

Takes you here

4 of 12

Image of What’s on Your Local Computer

On Your Local Computer:

These are the copies of code that are kept on your machine.

The big arrows represent the flow of code.

DEV: this is NOT the real dev that is in the repo, this is YOUR COPY of that code that you made when you cloned the repo to your machine.

Keeping this local copy up-to-date by pulling after anyone merges code into the repo will ensure you can avoid conflicts and errors when you push yours up

YOUR CURRENT WORKING BRANCH: this is the branch copy that you make to complete a specific coding task.

When the task is completed, you will check to make sure that you can successfully merge your changes into the repo, and push this branch up.

When you first clone the repo, a copy of dev is made to your local computer system.

After anyone merges changes into the repo, and before you push your changes up, you pull the most recent version of the dev that lives in the repo to the copy of the dev that lives in your machine.

You never do your work in this branch, and you never push to the repo from this branch. This is your local back up of the code that exists in the repo.

Anytime you update your copy of dev by pulling from the repo, you need to merge it into your local working branch. This will catch any conflict early so you can fix them more easily.

You always merge dev into your working branch, not the other way around.

Ideally, every time you merge your changes (i.e., complete a task), you should ideally create a new unique working branch for your next one.

Once your task is finished and you’re ready to merge it into dev (meaning you’ve already updated your local copy of dev and merged it into your working branch), you push the working branch up to the repo version of dev.

You don’t pull from the repo into this branch.

5 of 12

Commands: Cloning a Repo (via terminal)

In the GitHub repository, hit the green “Code” button, then select the type of link you want to use to clone the repo. Recommend to use SSH if you have it set up, and https if you don’t. Click the button with the two sheets of paper on it to copy the link.
Open a terminal in the folder where you would like the repository to live (like a coding projects folder). You can do this in your file navigator by right clicking on the file and choosing the option to open a terminal (the example given is on a Mac, but PCs are very similar).

Enter the command git clone, paste your link after it and hit ‘Enter’. This will make a copy of the repo’s default branch (which should be set to ‘dev’) on your local machine. This is now your local copy of dev. You will maintain this by pulling from the repo after anyone merges code, and before you push code up to the repo.

Copy your chosen link to paste into your terminal

…then…

6 of 12

Commands: Creating a New Branch

If you have just cloned the repo, ‘cd’ into your new folder so your terminal is on the correct file level. If your terminal is already open in your local repo folder, proceed.

Enter the command git checkout -b your-branch-name, replacing ‘your-branch-name’ with whatever you want to name your branch. A typical pattern is your initials-the task you’re working on. For example, nkc-login might be the name I chose if I was working on the login page. It is best practice to choose a new branch name each time you start a new task after a push to the repo.

To open your code editor from the command line, enter the command code . If you are using VS Code, you will notice your new branch’s name in the lower left-hand corner of the screen. This is a great place to get used to checking with your eyes at regular intervals just to make sure you’re not working in your local copy of the dev branch (which could lead to all sorts of headache for you later).

You’re now ready to complete your task! Add your changes.

I did not pick a good branch name! I should have been more descriptive.

7 of 12

Commands: Committing

Whenever you have completed a step in the change you’re making to your local working branch, it’s a great idea to commit that change. This is like saving it.

To do so, in your terminal (can use either independent terminal window or integrated terminal in code editor, as long as it’s open at the root level of the folder you’re working in) enter the command `git add .` , then hit enter. This basically gets your changes ready to be saved.

Next, enter the command `git commit -m “enter message about the changes you made here”`. This is what actually saves the changes. Try to be descriptive in the commit message; say what you changed.

That’s it! You’ve saved your changes. You should complete these steps A) whenever you finish a piece of the particular piece of code you’re working on, or B) whenever you need to switch branches.

8 of 12

Commands: Pulling from the Repo

Whenever someone completes a task and merges it into the online GitHub repo, everyone should pull to update their local copy of dev (including the person that just pushed). This will ensure that everyone is working with the most up-to-date version of the app, avoiding a lot of headaches and conflict fixes down the road.

The first step is to commit the changes you’re working on. See the previous slide for details. Feel free to make your commit message something simple, like “wip”. You’ll be back.
Next, you are going to leave your working branch (make a note of the name you used for it!!) and enter your local copy of the dev branch. In your terminal, enter the following command: git checkout dev . This will take you into your local copy of the dev branch. You can see this by looking at the bottom left corner of your code editor’s window. It’ll now say ‘dev’. This is why it’s a good idea to create a habit out of checking the corner: you don’t want to do work in the dev branch. Again, creates huge headaches in the future.
Now that you’re in ‘dev’, enter the command git pull . This will pull the most recent version of dev in the repo and merge it into your local copy, thereby updating it.
Now that dev’s updated, switch back to your working branch: git checkout your-current-branch-name (I hope you wrote it down! Otherwise, Google how to find it).
The next step is to merge the changes that you just pulled into your local copy of dev into your current working branch, so you’re working with up-to-date information: git merge dev . Here’s where some funny business might happen:

If there is no code that conflicts with what’s in your current working branch, the merge will go smoothly and you can get on with it.
If there are conflicts (these result from the two sets of code not playing well together potentially resulting in big errors and issues), you will receive a notification that the merge has failed due to merge conflicts. In your terminal, it will list the files where the conflict exists. Go to those files in your code editor. You will see that the code editor also highlights the conflicts for you. It will as you to either keep your version of the code, erase yours and accept the incoming version, or keep both (which could really cause issues, so proceed with caution). Once you’ve made your selection and the conflicts are resolved, you will need to save your work again (redo the ’git add .’ & ‘git commit -m “fixing merge conflicts”` and reattempt the merge.

Now you can continue with your work.

These teeny-tiny buttons are what you push to choose which version you want to keep

Your code

The conflicting code you’re trying to merge in

9 of 12

Commands: Pushing Your Changes to the Repo

YOUR CURRENT WORKING BRANCH:

You’ve completed your current task. Time to get ready to push! Save/stage your progress:

git add .

…then…

git commit -m “commit message here”

When you’re done with your current task and ready to push your code to the repo, first commit your changes (see slide 7 & picture)

Then switch into your local copy of ‘dev’.

Then switch back to your local branch.

Merge the updates to your local dev copy into your working branch to check for conflicts. If there are any, fix them and recommit.

Pull from the repo just to make sure you really are up to date (sometimes you get a surprise!)

Push your code up to the repo, then go online to the GitHub repository for the final steps!!

10 of 12

Procedure: Initiating a Pull Request on GitHub

That’s it! Your request to merge is in. Let the team know you need your request reviewed and merged!

And don’t forget: once your changes are merged into the dev branch on GitHub, pull them down to your local copy of dev as well, to keep up to date.

When you open the GitHub repo online, you will see an alert that says you have made a push, and you need to initiate a pull request. Click on the green “Compare & pull request” to begin.

You’ll be taken to this screen. Make any comments you like, then hit the green “Create pull request” button.

Your pull request is in! Now let the rest of the team know that you need it reviewed, approved, and merged into the dev branch on GitHub. Once it’s merged, the red will disappear, and the green “Open” tag will turn purple.

11 of 12

Procedure: Reviewing & Approving a Pull Request on GitHub

When someone has a pull request submitted that needs approval, someone should verbally (or, you know, through a message) acknowledge that they are going to deal with it, to make sure everyone’s upto speed.

Open your GitHub account and look where it says “Pull requests” up top. If there’s a number next to it, there re requests that need reviewing. Click on it.

When you’re brought to this screen, click on the pull request you’d like to view.

You will be brought to this screen, this time as the reviewer of someone else’s pull request.

Click on “Add your review”. Have you ever seen such a tiny important link?

Old code

New code being pushed

You’ll be brought to a window and shown the changes that your colleague made. Review them and see if you have any questions.

Once you’re satisfied that it all looks good, hit the green “Review changes” button.

This modal will then pop up. You can leave a comment in the window if you like, but the important part will be to click the “Approve” radio button before you hit the green “Submit Review” button.

12 of 12

Approving: Last steps

Confirm Merge

Click

…then click

Purple means success!

OK, very last steps! Now you just need to merge their changes into the GitHub ‘dev’ branch.

Click green “Merge pull request” button, followed by green “Confirm merge” button, and if you see the top bubble alert turn purple and say “Merged,” you’re all done!! Yay!!!

OK, that was a run –through of the GitHub basics! Lemme know if you need any help!