This past week I completed my first group project at Flatiron School. In the project I used my knowledge of programming with Ruby to create a CLI application which helps users discover new breweries across the United States.
One of the largest hurdles throughout the group project was navigating Git and GitHub. In this post, I hope to help explain the workflow we utilized as well as share some commonly used commands at each stage in the process.
Git is a version control system that will help you keep track of the changes and history of your project throughout its lifestyle. I worked through two main components of version control throughout my project:
Branching - allows you to duplicate the source code for yourself. You will then work on your own branch so your edits do not immediately affect the original source code.
Merging - the process of joining your branch with the original source code after complete testing.
GitHub is the service that will host your Git repositories. Think of GitHub like the cloud server that hosts your source code. The repository for your project consists of all branches, commit, merge history, any licensing or readme files, rake/gem files, etc.
The partnership between Git and GitHub grant teams an invaluable asset - any and every modification to code is tracked through the two tools. Therefore, in the case of a mistake the code can efficiently and quickly be rolled back to its previous state prior to the error.
Let's review a simple project workflow and the CLI commands that help us move from one step to the next. Below is a diagram of a workflow including Git & Github. This diagram most closely represents the flow of my group project.
The very first step (not included on diagram) is to clone the repository to your local machine. Be sure to clone the project in a working directory that makes sense so you can easily remember where your local project lives.
git pull origin master
Next, pull down from the remote repository (reminder, this lives on GitHub) to make sure you have up to date information. Believe it or not, changes could have been made by a team member in the time it took you to clone down the repository to your computer.
git checkout -b new_branch_name
Create your own branch! If you’re working in a group project like I was, you will probably want to create a new branch for the feature you are working on. Make sure you are titling your branch according to the standards of your workplace expectations. You now have your own little place to experiment with code without immediately affecting changes on the master branch!
** note: you might not need to create a new branch if you are intentionally editing an existing branch. In that case, be sure you are on the correct branch and not the master prior to making any changes. Always check with your teammates before creating/editing branches.
git add file_name
After your code has been tested and is complete, add your changes to the staging area. This means that your files are tracked by Git, changes are complete, and code is prepped, and ready to be added back to the repository.
Run git status to confirm that your files have been added to the staging area. If the name of the file is listed in green - you're good to go! If not, try adding again.
git commit -m "valuable_but_short_message_here"
Commit your changes back to the repository. Add a brief, but detailed comment about the changes that were made, code that was written, or bug that was fixed. Make it easy for your team members and future team members to understand what the alterations were.
git push branch_name
Next up - push your changes to the repository! You have now transferred your code up to GitHub. The code you've pushed up lives in the current branch you've worked on. We learned (the hard way) how important it is work on your branch and to push to your own branch. If you accidentally push up to the master you run the risk of overwriting code the master branch which lives within GitHub.
Finally, you'll need to create a pull request through GitHub. This may vary depending on the nature of the project. Submitting a pull request will notify the owner of the repository that you are ready to merge your code with the master branch. It is up to the owner to review your code prior to finalizing the merge. In our particular situation we had team members look at the code together as we completed the pull request. Because we were still relatively new to the GitHub process, we wanted to be sure that no code was accidentally overwritten when a branch was merged with the master.
git pull origin master
This command was mentioned above as the first thing you should do after cloning to your machine. Again, you'll need to complete this once the master has been revised. This command gets a honorable mention for playing a critical role in keeping your working version up to date. After the master branch in a repository has been updated from a pull request, be sure to pull down from the repository into your local branches. This will ensure that you are working on the most up to date files moving forward.
I hope that this post helps to explain some of the fundamentals of using both Git and GitHub. Writing this blog was a valuable exercise to me, as I was able to reflect on the processes that challenged my team and learn more about them through further research. Note that there are many common commands that this post didn't cover and I encourage you to look those up as needed. I’d love to hear feedback on this post -comments are welcome! Happy coding!