So you have started a git repository and you are using good practices to have version control on your new project, that’s great! But now, you want to work with someone else on their project, and not just pair programming. You both want to be able to work on different parts of the project, then you want to squish them together when you are done! Well thankfully git can help with this too!
Here I will walk you through how multiple people can work on the same project AND I will provide a project so that you and your friends can get together and practice working through git control together! (And you might make a something really cool in the process)
There a few things to go over before we get to the meat and potatoes. I made another blog post here that is an introduction to git and version control. If you are unfamiliar with git, check it out first. Now let’s review a few of the commands in git.
Repository — A repository is where all of the different versions of your project that you have saved along the way have been stored. There can be local repositories that are saved on your machine and there are remote repositories that are saved online. Remote repositories are often held by services like GitHub, GitLab, or BitBucket
Commit — If you read my last article you should already be familiar with commits. They are the snapshots of your project at a certain time that are saved in your repository, make sure to make commits often and make sure they have good descriptive comments.
Push —When you push your repository, you are pushing your changes on your local machine to the remote repository, so that the remote repository will match the changes on your local repository.
Fork — Forking is the first step in working on a project we find on GitHub. When you fork a project on GitHub, a copy of the project is made, and a remote repository is added to your GitHub. You can then clone this project and start playing with it on your local machine. To learn more about Forking and Cloning, check out my older blog here.
Contributing to a Project!
Alright! Now that we have reviewed the basics from last time, let’s check out what’s next. So we can follow along with an example, I am going to be using a project I have been working on called Game Room. It is a fun application, who’s whole purpose is to let fresh developers practice their skills in pair programming, front end development, logic, and finally, git. It is designed to have multiple users create new pages, which they will add to the master copy of the project. The pages could be games like Tic Tac Toe, or they could just be neat contraptions someone thought of in React. All of these pages are then combined on one git repository, so that individuals can learn these skills of teamwork, git, and project management in a low stress relaxed environment. You can check out what I am doing in the project here!
So if you find a project (maybe a project like Game Room that is linked above), the first step is to fork and clone the repository onto your own machine so you can open the project in your own text editor. Then we somehow have to tell git that the repository you are working in, is linked to the master repository. To contribute our changes, we have to tell git where to contribute these changes. This is called the upstream remote.
The upstream remote is where we will eventually have our changes contributed to. We also want to be able to update our local code, based off of this upstream remote. To add an upstream remote, you have to run the following line of code in your console AFTER you have forked and cloned the repository.
$ git remote add upstream URL
The URL in the line above, is the same URL you will have used when cloning the repository. You can run the following line of code, to check to make sure it worked.
git remote -v
This command will list the remotes associated with your local repository. You should see one that says origin and one that says upstream. The origin is your personal remote repository on your GitHub page, that was created when you forked the project.
A final note with your upstream remote. If you want to keep your origin remote up to date with the upstream remote, you can run the following line of code to have any changes in the upstream reflected in your code.
$ git pull upstream master
It is good practice to do this when you can, so that you know that the changes made in your remote, will not conflict with the changes made in the upstream remote.
Once we have our upstream remote set, then we need to make a branch.
Branch — A branch is a divergent line of commits from the main project (the main project can also be called the master branch). So what that means is, I can branch off from the main project at a certain point (this certain point will be a certain commit in the master branch), and any new commits to the master branch will not affect the current branch I am working on.
So our branch will describe what feature or issue we are working on. When we make a new branch, we can work on our feature, without the work our teammates are doing affecting our copy of the code. To make a branch, type the following line of code into the console
$ git checkout -b YOUR_BRANCH_NAME
This will create your new branch and transfer you into the new branch. These are another few useful commands to know for navigating branches in the command line.
//Show all local branches
$ git branch//switch to a different branch without creating a new branch
$ git checkout BRANCH_YOU_ARE_SWITCHING_TO//create a new branch WITHOUT switching into it
$ git branch YOUR_NEW_BRANCH
So in my example, I wanted to create a new page in Game Room that lets the user play Checkers. I would probably create a branch with a name like create_checkers
You can see in my console that the red text changes to signify that I switched from the master branch to the create_checkers branch!
Now we can go ahead, and start making the changes in our code to add the new features we want from our branch. Commit along the way, and when you think you have completed your changes, you can do what is called a pull request!
Pull Request — Pulling is when you pull the changes from one repository into another. This is done every time you update your repository from the upstream remote, but if you want the changes to go the other way (from your origin remote to the upstream remote), we have to request the owner of that remote to approve the changes.
So we have to request permission for the changes to be accepted (aka pulled) into the upstream remote (reminder, the upstream remote will most likely be the master repository that holds the final version of the project). To do this, first push your commits up to your origin remote, then navigate to the repository on GitHub and you should be able to press a button that says “New pull request”.
When you create a pull request, make sure to leave insightful and descriptive comments on what changes you made. You want it to be clear so that the owner of the upstream remote, will not have to wonder what was changed. Then the changes you made could be accepted, rejected, or they might want some revisions. There are lots of handy places for users to leave comments and start discussions to resolve all the issues in the pull request before it is finally merged into the master.
A final note on these pull requests. If there are changes that are requested of you, then you don’t have to submit another pull request once you make the changes. As long as the commits you made to fix the issues are in the same branch as the origin pull request, then that pull request will reflect those changes!
In an upcoming blog, I will go over more details on merging branches, communicating through GitHub, and what happens on the other side of the Pull Request. There is a lot to cover there so it deserves its own post.
In the meantime, there is no better way to learn something than by practicing. If all of these commands and practices seems daunting, and you want to practice check out this GitHub repository I made with an empty Game Room project. This is a great space to work together with a colleague on using the skills outlined in this article. I encourage you to try it out so you can see how powerful and easy git can be once you get the hang of it. Just fork and clone your own copy of the above repository and make that the master branch of your Game Room project. Then you can have friends, partners, or colleagues fork and clone your copy, then set it as their upstream remote. This will provide a low consequence and relaxed place to practice these skills.
Have fun playing and creating in Game Room and make sure to keep practicing safe version control!
If you enjoyed this article, or if you created something fun in your own copy of Game Room, please share it with me! I would love to see what you all create.