Version Control
One of the big strugles when programming in a company vs. on your own project is that you’re not alone. Of course, this has a lot of upsides since you can learn from your co-workers and you might not master all technologies involved in the project. The downside is that you need to make sure that the code you are writing is compatible with the code written by your team.
This is done by using “version control” such as Git that allow you to share code and that prevent your work from erasing other’s code. Think of it as a Google Drive but with some security layers on top. You have your local folder, and it gets synchronized online when you execute some command. One of the big advantage of Github is the ability to revert back to a previous version of your application, if your latest change of the app brought a bug for example.
On Git, your project is called a repository, which gathers the code of your application. This repository has branches. Branches are quite similar versions of the application with minor changes on each branch. There is a main branch, usually the version of the application exposed to the end customer, called Master, and each developer can create a branch from this main branch, i.e. a duplicate at a fixed point in time, to modify something on the application, for example adding a feature or improving an algorithm.
When you finished adding your changes, we say that you merge your changes to the application on the main branch, and make the branch you created disapear. This process usually implies a code review when you do pair programming, i.e. another developer will look at the code and see if something is wrong before merging it into the final version of the application.
Each feature you add to the application should have its own branch dedicated, (this is a good habit for agile approaches if you have heard of them) with one or few developers working on it. When several developers work on the same branch, and at some point the same file, this might bring conflicts. Conflicts happen when two versions of the application co-exist, the one existing on the branch and the one you are trying to overwrite. To avoid conflicts, you need to make sure that you work on different parts of the code, and that you have pulled the latest version of the branch, meaning that you have downloaded the latest version of the branch you are working on before editing anything.
Once your changes on the application are ready to be put on the branch corresponding to the feature, you can commit your changes, i.e. write them on a registery of the changes, and push them, i.e. make them avaialable for everybody on the branch.
Once the branche has collected all the changes from all the developers working on the feature, as explained before, the branch is merged into the main branch.
How to use Github
Git is a distributed version control tool that can manage a development project’s source code history, while GitHub is a cloud based platform built around the Git tool.
Github’s technology has been acquired by Microsoft a few years back. Millions of developers use Github for their team projects, for open-source contributions or for personal projects. On Github, you can browse state-of-the-art repositories when made available publically, but you can also host the code of your company’s applicaiton privately. All languages are supported on Github (bash, Python, R, C, C++, JS, …). Other version control tools exist, such as Gitlab and Bitbucket.
You can also download code and projects directly from Github. This is a good starting point for any project.
We have installed git in the setup article before, using command line. Now, head to https://github.com/. Create an account (it’s free), and we will create your first repository. Hit the “+” button at the top.
Call your repository “my_application”, and create the repository:
You’ll land on a page with code snippets given to you.
echo "# my_application" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin https://github.com/maelfabien/my_application.git
git push -u origin master
Go to your root from your terminal. In my case, it’s Users/maelfabien. This is usually where you put your projects. The command given can be executed through your terminal. It will create a new folder that contains the code of your application, create a README (a simple text file that describes your application and the files it contains), add those changes to the commit history, commit those changes (meaning that we mark them in the registery), and push those changes online.
Now, if you refresh your Github page, you will see that your repository now contains a single file called README.md. The .md extension stands for Markdown, an alternative to .txt files you might know and HTML, which includes some layout. We’ll get back to this in a further article.
Alright, we have now pushed our first article online. It is available publically. Our changes are made on the “Master” branch, meaning that we work directly on the final branch exposed to a customer if we were to build an application. This is only a simple tutorial, which is why we’re doing this.
Suppose a friend of yours also works on the project and you want to pull the changes he made, i.e. download the changes he made on the application. From the right folder in the terminal, simply type:
git pull
This will pull the latest changes. Now, you have made some changes on the application (e.g. updated the README.md file). You need to add your changes and commit them.
git add .
git commit -m "Update of the README"
The add . means that we add all changes that have been made yet. The commit writes these changes to the registry, and we add a message (-m) to let other developers know what we modified. Commits should be small enough so that the message summarizes well what it contains.
Finally, we need to push changes online, and make it available to our friend (who will git pull your changes), using:
git push
These 4 git commands are fundamental. They allow you to work alone with organized code on a repository, or on small projects with other developers. Then, you will need to start using branches.
Suppose that the master branch contains the latest version of the application. You want to add a feature and need to create a branch. If another developer already created the branch before you, simply use :
git checkout other_branch_name
The checkout will allow you to move to that branch. This will automatically update the content of your local files ! You need to have all you changes commited before checking out. Otherwise, if you need to create the branch, simply use:
git branch -b other_branch_name
This will create a duplicate of the branch you were on (the Master), and allow you to make changes safely before merging it back into Master.
Finally, if you notice a nice repository on Github and wish to download it on your own computer to test it, simply click on the right menu of the repo “Download”. This will give you the choice between downloading it as a zipped file, or as a link. To clone a project from a link, use this simple command line on your terminal:
git clone https://github.com/link_to_package
With these 7 commands, you should be able to handle 95% of your Github use cases. Some important notes on Git:
- You can use Git to browse repositories and look for scientific paper implementations for example, or open source project’s source code
- I think it’s safe to say that 99% of programming teams worlwide use Git (Github, Gitlab, Bitbucket…). Don’t skip it, you’ll end up regreting it.
- do not push files of more than 100 Mb., you will have to use Git Large File System otherwise
- Git is therefore not made to host databases, but simply code (a complete application should be a few dozen Mb. at most)
- Use Git to show your projects, this is highly valued by recruiters
- Make your code understandable, and write a full Readme
- Use git from the start of your project, this is a good habit, and makes tracking your changes easier. Plus, it shows how active you are on your Github account