# Document Title
You have 2 free member-only stories left this month. Sign up for Medium and get an extra one
A Simple Story to Explain Version Control to Anyone
Let’s build a house together… using git.
Julia Di Russo
Julia Di Russo
Feb 18, 2020·6 min read
Photo by Yancy Min on Unsplash
When I started using Version Control in my projects, the concept was difficult to understand. I saw many people, including myself, running commands such as git pull, git push and applying processes that I did not understand. Why did I need to both commit and push? Why did every new feature require a new branch? After working several months in a project using Git daily, the concept became very clear to me and I could finally understand the full potential for collaboration using Version Controlling, and more specifically, Git.
During the last two weeks of December, I was asked to give a workshop about Version Control and more specifically how to use git in projects. As the workshop would be attended by people with diverse backgrounds, I thought of a small story to illustrate the way Version Control works and its advantages in projects.
Let’s build a house together
In this beautiful collaboration project, we are trying to build a house together. To keep it simple, we are only two people working on that house. We are not the owner of the house, and we work on its content for someone else, a stakeholder, who tells us what he wants and where he wants it.
Disclaimer: I am in no way an architect and I have very little knowledge about actually building a REAL house. Keep in mind, this is just a story to help people follow the Version Controlling concept easily.
Photo by bantersnaps on Unsplash
We have 4 walls — Our Master Branch
We start with 4 walls (and a roof?), that are sturdy, resistant and perfectly fine. These four walls represent our Master branch. They are currently standing, implemented and will not be removed. The stakeholder approved these four walls, he might even have chosen them himself and he wants to keep them. All we need to do is improve these four walls and build on top or around them. In any case, anything we will build will have these four walls as foundation.
The owner wants a living room and a kitchen — Feature branches
As I evoked earlier, two people are working on this project, myself and another guy that we will call Bob, as I have zero imagination for names. Each room is a feature. In this case, to maximize outcome, Bob and I will work on different features. I will design the living room, and Bob will design the kitchen. So far so good. Simple.
We both create one feature branch. We also know that we must use conventions to name our branches. So we will start with our first name, what we are working on (in this case, a new feature) and the name of that feature.
    Julia/feature/living_room
    Bob/feature/kitchen
(There are several conventions to name branches. This is just a suggestion.)
We both create our feature branches from the Master branch. So we both start with the same 4 walls. However, our feature branches are entirely independent copies of the Master branch and have no direct influence on the content of the Master branch. This ensures that if Bob or I completely screws up one of the main wall, the Master branch, containing our 4 walls, is still standing, and is there there to fall back on.
I want to save my design locally — git commit
Committing is like saving your changes locally. Each new commit has a number and also represents a saved points you can return to, just like in a quest game where you can return to a previous save point. So when Bob built the kitchen cabinets, he can commit them in order not to loose his changes and to have a commit to go back to if the next part he builds endangers the quality of the cabinets.
Each commit also requires a message and since it is good practice to write something about your commit in order for everyone to know what this “save point” includes, sweet Bob writes “created red kitchen cabinets”.
I want to save my design in a safe place, on the repository — git push
Your repository is the place where all branches are stored, including the master branch. It is like a folder with all files about your project including their revision history.
Git push takes all your commits and sends them to the remote version of your branch, which is available in your online repository, where all the developers involved can see the changes made to your branch. Therefore, Bob pushes his commits to his remote branch and I can now see Bob’s commits about the red cabinets.
My Living Room is done. Now what?- The development branch & merge request
Our development branch is a place for integration of our rooms (or features). This is the place where we try to combine our designs (or features) together and see if our living room and kitchen function well together.
If I want to add my living room to the development branch, I must do a merge request (or pull request, depending on the platform you are using). In general, at least one other developer must approve your merge request before the merge happens on the remote branch.
Bob’s kitchen is done. Our designs do not match. — Merge conflicts
I am trying to merge Bob’s new changes to my branch. But what happens if I did not make the wall properly on the side of the open kitchen of Bob? Our design (which represents code, remember?) have a conflict. Git can resolve some conflicts automatically, but not all. Git sometimes needs your help to figure out which changes should be kept since some of them are conflicting. In other words, it needs to know whose “design” (or code) is the right one to keep.
Let’s say I am the one that made the mistake (let’s not blame poor Bob). I can tell Git to keep Bob’s part of the design when it comes to the kitchen wall, and not mine.
When can we add our kitchen and living room to the Master branch?
This part of the project usually involves tests, stakeholders and approvals (at least). Once our designs were thoroughly tested, meaning that they also function well together and our stakeholder, the house owner approves the designs, we can decide to merge our changes to the Master branch. This means that from now on, the stable version of our house will also include our living room and kitchen. So all new branches should at least include these rooms.
In some cases, a smart approach might involve keeping each former version of the Master branch in a different branch as a previous release. However, the right approach to deal with a Master branch depends on the needs or guidelines that your team and company might have. (I am keeping this story simple. Not every team or company deals with the Master branch the same way.)
In conclusion, Version Control is at the heart of easy and safe collaboration.
Using Git in a group project allows for several developers to work on the same project independently without constantly interfering with each other’s input. Each developer can get an independent version of the code that they can modify without taking the risk of destroying a stable version of the code.
The ability to duplicate the code and work independently on a different version of it makes Git a good option for anyone building an application, even a developer working alone. It gives you the opportunity to keep several versions of your code and keep track of all characteristics of each change, such as who did the change and when.
Thanks for reading!

 // why `add .` warns instead of adding everything? how do i add everything?

 - user must track renamed file

.git
.DS_Store