This blog post will walk you through a basic GitHub workflow. We’ll touch on some core Git concepts, but for the most part this is just a practical guide to using GitHub. We’re going to start off by creating a new GitHub repository and connecting it to a local repository on your personal machine. Then, we’re going to discuss adding collaborators and using branches to work in conjunction with other programmers.
Creating Your Local Directory
The first thing you’ll need to do is set up a folder on your local computer where you’ll want your new project to live. We can do this using our terminal. If you don’t have a folder you want to store your new project in, you can create one using the mkdir <new-folder-name> command, where <new-folder-name>is the name of your directory. Let’s say I’ll be creating a social media app for puppies, which I’ll want to call “Puppo”.
mkdir puppo
Once you’ve created your new directory, you’ll want to cd into it:
cd puppo
To make sure you’re in the right directory, you can run the pwd command, which will show you the full path of the folder you’re currently in.
Now that you’ve set things up locally, it’s time to create a repository on GitHub.
Creating Your Remote Repository
The first thing you’ll need to do is log into your GitHub account, if you haven’t already logged in.
Once you’ve logged in, you should be taken to your GitHub home page.
From here, you’ll select the “+” dropdown menu in the upper right hand corner of your screen, next to your profile picture.
Select “New repository” from the dropdown menu. You’ll be taken to a “Create new repository” page.
In the empty “Repository name” field (marked by a red asterisk), you’ll type the name of your new repository. (I want to keep my naming consistent, so I’ll call my repo name “Puppo”.) GitHub will let you know if that name is available or unavailable. If it’s unavailable, you’ll have to come up with a different name.
Once you’ve put in a name, you should be able to click the green “Create repository” button. You can give your repository a brief description before you create it, if you want to. You should also make sure you set your repository to public. (We want other people to be able to see our code!) For this workflow, we won’t be selecting any of the boxes in the “Initialize this repository” section.
Go ahead and click that “Create Repository” button once you’re all set. You’ll be taken to a new page with a set of instructions telling you how to connect this remote GitHub repository with your local machine.
We’ll be using that first set of instructions under the header …create a new repository on the command line.
Connecting your local machine to your remote repository
We’ll be running through those lines of code provided by github one by one. The first line they’ve included is that echo “# Puppo" >> README.md1 command. Make sure you’re in the right directory in your local environment, (in my case, I should be in the “puppo” directory I created earlier), then run this command.
This command does a couple of things. First, it creates a new README.md file, which is handy, since we’ll want our project to have a readme file that tells other programmers about our code. Second, it will add the text “Puppo” to our README.md file. If you just wanted to create a readme file without adding anything to the file, you could just run the command touch README.md.
The next command we’ll be running is git init. git init is a command that initializes Git within this directory on your local machine. You’ll need to initialize Git within this directory in order to connect this directory with your GitHub.
A Note on Git: Git is a version control system; it’s essentially a way to store snapshots of your code — “versions” of your code — at different moments in time. You can actually use Git on your machine without ever connecting it to GitHub, and it will work just fine. The handy thing about using GitHub is that it allows you to store and share these different versions of your code on a server. This is helpful for a variety of reasons. One, it keeps your code in good shape even if your machine crashes or has some funky bugs. Two, it allows you to easily access your code from a different machine if you want to work on a project you’re building using a different computer. And three, it allows other developers to view and contribute to your code. So, while you can just use Git locally, there are a lot of good reasons to use GitHub. It’s not strictly necessary, but it’s an incredibly useful tool.
Okay, so you’ve created your README.md file and you’ve initialized Git in your local directory. Let’s move onto the next command git add README.md.
Before we run this command, let’s run a different command — git status. You should see something like this appear in your terminal.
We’re getting a lot of really helpful information here. One of the pieces of info we’re getting is that we have “untracked files.” This means that there are files that have either been created or changed that aren’t currently being tracked by Git — Git doesn’t know that it’s supposed to be paying attention to these files. The untracked files are listed in red under that “Untracked files” section — currently, it looks like our README.md isn’t being tracked by Git. That untracked files section also tells us what command we need to run to make sure that our untracked files are being tracked by git; git add <file>, where <file> is the name of our untracked file.
In this case, our file name is README.md — hence the command given to us by GitHub, git add README.md. Let’s go ahead and run that command, then run git status again.
Now, we’re getting something a little different. Instead of receiving a message that has “untracked files”, we’re receiving a message that tells us we have changes that are “ready to be committed.” Those files that are ready for a commit are written in green.
Let’s check out that next command from GitHub’s instructions git commit -m “first commit". Once we have those files tracked, we can run this command.
But what exactly is a commit? It’s what actually saves that version of your code — it’s the command that takes the snapshot. Until you run a commit command, your changes haven’t been saved by Git. That “-m” flag included in the commit command stands for “message”, and it allows you to write a message describing your commit. In this instance our message is “first commit”, but it could be something else. If, for example, we had just finished creating a like button, our message could say “like button functionality implemented”, or something along those lines.
Let’s run our git commit -m “first commit"command. Now, we’ll move onto the next command: git branch -M main. The default branch that Git is set up with is referred to as “master.” However, due to changes in convention, developers now use branch “main” as the default branch. This command is telling Git to specify the default branch as “main” instead of “master”.
After running this command, you can run git status. You should see the following output:
This is telling you that you’ve successfully changed the name of your branch from “master” to “main.”
Now, we’re finally ready to run the command that will connect your local repository with your remote GitHub repository — git remote add origin git@github.com:Matt-Eva/Puppo.git. The link to your repository will look a little different than mine, since you’ll have a different GitHub name and different repository name than I do.
Running this command is what actually connects your local repository to your remote GitHub repository. Once this command has been run, you’re ready to push you local commits to your remote repository.
Which is exactly what that final line of instructions from GitHub is telling you to do! git push -u origin main will push the commits you’ve made from your local machine up to your GitHub repository. That “-u” flag will set your default push and pull branch to main — if you include it, you can just run git push or git pull in the future without including origin main. However, we’re going to start working with branches in a moment, so we do still want to keep that origin <branch-name> part of our command in mind.
Once we’ve run this final command, we can refresh the GitHub page that has our directions on it — once we’ve refreshed, we should see the page of our new repository instead.
Congratulations, you did it! You created a brand new repository! Now, it’s time start thinking about collaborators and branches.
Adding a Collaborator
We’re often not the only one’s working on a single project — oftentimes, we’ll need to add collaborators who can access our repository and add changes to our code. Fortunately, GitHub makes this pretty easy!
The first thing we’ll do is click that “settings” option in the navigation bar of our repository. It should be located at the right end of your list of options.
Once you click on it, you should see a page that looks like this:
On the left hand side, in the sidebar, you’ll see a section labeled “Access”. Click the “Collaborators” option that’s listed within that section (you may be prompted to re-enter your GitHub password).
Once you’ve re-entered your password, you should be taken to a page that looks like this:
From here, you can click that green “Add people” button to add a new collaborator. When you do, you’ll see a little pop-up window prompting you to input somebody else’s GitHub username.
Type in the name of your collaborator — you should see a list of options dropdown from the text input field as you type.
Go ahead and select your collaborator by clicking on the dropdown option. Your modal should look like this:
Then, click the green button that says “Add <collaborator-name> to this repository”. You should now see them listed amongst the collaborators on your collaborator page:
That collaborator should receive an invitation email telling them that they’ve been added to the repository — they should also receive a notification in GitHub. There can sometimes be a delay, so if you want them to be immediately able to access the repository, you can send them the repo url. The collaborator should see an invitation message when they visit that URL — they can then accept the invitation and start working on some code!
Working as a collaborator
Let’s switch places for a second — now, instead of being somebody who has created a repository and just invited a new collaborator, you’re somebody who’s just been invited to a new repository as a collaborator. You’ve accepted the repository invitation, and are ready to get started.
The first step you’ll need to take is similar to the step the repository creator took — set up a local directory on your computer where you’ll want this project to live.
You can do this using the mkdir <your-directory-name> command. Once you do cd into that directory.
Now, let’s go back to that repository you’ve been added to. In the main page of that repository, you should see a bright green button that says “Code” on it.
Once you click that button, a dropdown menu will appear:
Make sure you’ve selected the SSH option (it should be bold and underlined). Then, you can click on the clipboard icon next to the text field showing the name of the repository. This will copy the repository name to your clipboard.
Let’s return to your terminal — you can now type the command git clone into your command line and paste in that repository name you’ve copied. In total, it should look something like this:
git clone git@github.com:richwblake/my_great_project.git
Your github name and repository name will be different than what’s in this example.
Once that’s all set up, go ahead and hit enter. You should receive an output that looks something like this:
If you type ls in your terminal, you should see a new folder listed with the name of the remote repository. Once you cd into that, you’re ready to start contributing to the project. Let’s open this project up in your VS Code by running that code . command.
Using Branches
Let’s talk about branches. Branches are a really useful Git tool that allow you to try out new things or work concurrently with other people on different features without messing up the working version of your code. By convention, most developers keep working copies of their code on the “main” branch of Git. To check which branch you’re on, you can type the command git branch into your terminal. The branch you’re currently on should be highlighted in green, and will have a little white asterisk next to it:
In this example I’m on branch “main”.
Because “main” is where we want to store working versions of our code, we’ll want to create a new branch when we want to modify our code (like revising current code or adding a new feature). We can do this by running the command git checkout -b <new-branch-name>, where <new-branch-name> is the name of your new branch.
It’s typically a good idea to give your new branch a name that describes what new feature you’re building. In this case, I want to add a new file to the project, demo.html. So, I can name my branch “creating-demo-html”. So, my command would look like this:
git checkout -b creating-demo-html
The command creates the new branch and switches you over to that newly created branch. So, if you were to run git branch in your terminal again, you should see that you’re on your newly created branch:
You’ll notice that your other available branches are still listed as an option — they just aren’t highlighted and marked with an asterisk.
VS Code also gives you a handy method for checking which branch you’re on. If you look in the lower left-hand corner of your VS Code window, you should see the name of the branch you’re currently on:
To switch between different branches, you can use the command git checkout <branch-name>, where <branch-name> is the name of an existing branch you want to switch to. If you typed in git checkout main, you’ll be brought back to your main branch. You should see your VS Code update in real-time with that information.
If you’ve switched over to your main branch, let’s switch back to the new branch you’ve created using that git checkout <branch-name> command.
Now let’s make some changes! As I mentioned, I switched to this branch in order to create new file, demo.html. I can create that file using the touch command in my command line. Since I want to create a demo.html file, I’ll run the following command:
touch demo.html
After creating your new file, look at the sidebar on the left-hand side of your VS Code. You should see the new file you created highlighted in green with a capital “U” next to it.
This means that this file has changes in it that are currently “Untracked” by git. To make sure git is tracking them, we can run our git add command:
git add .
This command tells git to listen to all untracked files.
If you look at your VS code now, you’ll see that the “U” has changed to an “A”. This means that this file has been “added” to the files that Git is tracking:
Now, we’re ready to commit these changes. Let’s run our commit command, and leave a helpful commit message:
git commit -m “created demo.html file”
Now, that file name will change back to normal. All the changes in it have been added and committed by Git!
We’re ready to push our changes up to GitHub! Once they’re on GitHub, our peers can review them before we merge them onto our main branch. It’s always important to approve the changes you’ve made with your collaborators before merging them with your main branch. (Remember, the main branch is conventionally where we want our working code to live!) Merging buggy code with the main branch without checking in with your collaborators can cause a lot of headaches for a lot of people — yourself included!
Because of this, we’re going to make sure we push our changes up to this new branch we created, rather than pushing them directly to main. We can do this by using the command git push origin <branch-name>, where <branch-name> is the name of your branch. In my case, I’ll be running the command:
git push origin creating-demo-html
When you run your command, you should see an output that looks something like this:
If you look at that final line, you’ll notice it says * [new branch], then the name of your branch name. This means that this branch has been created in your GitHub repo! It will also contain all the changes you’ve made. It’s time to go back to GitHub.
When you return to your GitHub repo page, you’ll see a notification about the push you just made to your branch. There will be a bright green button in that notification that says “Compare and pull request”. Clicking this will ask GitHub to compare the code on this branch with the version of your code that exists on main. It also kicks off the workflow for adding and notifying reviewers.
Once you’ve clicked that button, you’ll be taken to a new page, which looks like this:
You can use this page to leave comments about your code, expanding upon what you’ve written in your commit.
You’ll also notice that you have the ability to specify a reviewer in the right-hand sidebar. You can do so by clicking “Reviewers” and typing in the GitHub name of the person you want to review the project:
Their name should appear in your dropdown menu. Go ahead and click on it. Once you do, you’ll see that they’ve been added as a reviewer.
Now that you’ve added your comments and specified a reviewer, you’re ready to create that pull request! Go ahead and do so by clicking on the green “Create Pull Request” button. Once again, you’ll be taken to a new page:
You can use this page to add further comments if you need to. You’ll also see a section that says “Review requested” — in this case, you have one pending review. My version of this page is also telling me that my branch has no conflicts with any code on my main branch, and that it’s safe to merge the two branches. However, I want to wait to merge until my reviewer has had a chance to look at the code.
Reviewing and Merging Code
Let’s switch places once again. You’re working as a collaborator with other people, and are filling the role of a code reviewer (it’s your responsibility to double check other programmers code before it’s merged with main). You collaborators will add you as a reviewer when they initiate a new pull request.
Once you’ve been added as a reviewer, you should see a notification about it in your notifications section on GitHub, which you can select using the bell Icon in the upper right hand corner of your screen:
Once you click on it, you’ll be taken to this page:
If you don’t see any notifications about being added as a reviewer, you’ll want to adjust your notification settings to make sure you’re notified in the future.
If you did receive a notification, you can use it to start your new review. If you didn’t however, you can see which pull requests are still pending by viewing the “Pull Requests” tab on your repository’s page:
You can select which pull request to view — if you’ve been added as a reviewer, you’ll see a notification telling you that you’ve been added as a reviewer on that pull request’s page:
Go ahead and click the green “Add your review” button in that notification. You’ll be taken to this page:
If you look at the picture above, you’ll notice a table with rows highlighted by green and red. The table name is the name of a file — in this example, that file is README.md. The rows highlighted in green indicate code that has been added to the file — the rows highlighted in red indicate code that has been deleted from the file.
Once you’ve reviewed the changes made to the file, you can click the green “Review changes” dropdown menu on the right-hand side of the page. This will open up a list of options:
You can either submit a comment without giving explicit approval to merge, explicitly approve the merge and add some comments, or specify essential changes that need to be addressed before merging this branch with main.
If everything looks good, you can select “Approve”, then click “Submit review”.
At this point, you’ll be taken back to the pull request page, but now you’ll see that the changes have been marked as approved:
At this point, you’re ready to merge with main. Go ahead and click “Merge pull request”. You’ll be prompted to confirm the merge, just to make sure:
If you really are ready to merge, select “Confirm merge”. If not, select “Cancel.”
You’ll now see a new message telling you that the pull request successfully merged and closed:
This notification also tells you that you can safely delete the branch you were working on. You don’t have to do this, but if you have no more use for it, it can be useful. Imagine you end up creating hundreds of branches over the course of a project, only some of which are branches you consistently keep using. It might be nice to trim away all the single use branches to keep your repository well organized and clean.
Pulling Down Your Updated Main
At this point, your main branch on GitHub has been updated with your new changes. But, your local main branch on your personal computer hasn’t been. We’ll need to make sure those changes are recorded locally before we move on to working on a different feature.
In your terminal, switch back to your main branch using git checkout main.
Once you’ve verified that you’re on your main branch, use the command git pull origin main to pull down your remote GitHub repository to your local Git repository. Once you’ve successfully run this command, you should see the new changes you’ve made reflected in your local main branch.
Deleting Local Branches
If you want to keep your local repository free of unnecessary branches, you can also delete local branches (let’s say you just pushed up some changes and no longer have any use for that local branch). You can do this by simply writing git branch --delete <branch-name> where <branch-name> is the name of your local branch.
You can also create and use local branches as a sandbox environment — you don’t necessarily have to push the code you write on local branches up to GitHub. Maybe you just wanted to play around with a specific chunk of code for a little while to see how it worked — that’s a great use of a local branch. These branches can also be safely deleted once you’re done with them.
Conclusion
And there you have it! A basic overview of how to use GitHub to work on your own projects and collaborate with other developers. There’s still a lot more to learn about Git and GitHub, but this should give you a good starting point and help you figure out how to set up your GitHub workflow. Happy coding!
P.S.
(Wondering how I included sections that look like this in my writeup? It’s really simple! Medium allows you to use backticks — `` — to specify sections that you want to look like this. You start by typing a backtick into the text editor — then, you just keep typing. Whenever you want your section to end, you just add another backtick, and Medium reverts to normal. Pretty cool, huh? How would you program something like that?)
