How To Run Your Project in Git Version Control System

Wikipedia’s definition of a VCS (Version Control System) is a bit dry and boring – in fact the whole page is rather nerdy, so I’ll try to sum it up here. Every time you start a project, you spend time on it, and you know better than me that ‘time equals money’. So every project is an investment, and Version Control is an insurance against wasting time. We often turn to tools that help us to work efficiently and save us time. Git is great tool for doing just this.

But why Git? I personally use it because we use it here at MoreNiche. But as a nerd, I love it for the following reasons:

• It’s fast
• It can work on both large and small projects
• Any number of developers can work simultaneously on it
• It can work without a server and a web connection
• It’s open source
• It works better on a command line
• And finally, because Linus Torvalds started the Git project

Before we start, I want to give you an idea of how it works and how you can get the best out of it. The concept is really simple: you can use Git to store a snapshot of your project in a specific moment. Then you can move backwards and forwards in a kind of time-lapse.

Let’s say you are working on a big update but you need to fix a couple of little bugs you’ve just spotted. If you are in the middle of a big project, you can’t fix those little bugs and then release them, as you’ll break everything related to the new code you are still writing. How can you resolve this situation? By using Git!

Git helps you to keep track of your updates on each file, and uses branches to keep more than one commit together in topics or by using tags to identify releases, or stable versions of the repo.

In every repo there is a ‘main branch’ named ‘master’ by default. Let’s say you want to modify your main menu. This is a main update on your website and one which is going to take some days to be completed; it could prevent you from releasing fixes or small updates for days… and you could lose conversions!

With Git you can create a branch named ‘menuUpdates’ to work on the menu, then when you spot a bug you can commit the work you did on ‘menuUpdates’, check out the master branch, fix the bug and release a new tag. Now you can go back to your ‘menuUpdates’ to keep working on it and release it once you are ready.

I know that at this point your brain is suggesting that you keep your old-fashioned method, but keep reading, you’ll discover it’s not that complicated.

The first step is to install Git in your local environment. There are lots of how-tos online but I like this one from Atlassian. Later on I’ll suggest using a command line, but you should know there are some good CLI clients for Git such as SourceTree and GitHub Desktop.

Next you’ll need to create a login on a Git host. I said before that you don’t have to use Git, but if you want to deploy on live servers, share the code, enjoy a web interface to read and check your code, I would say it is essential.

There are a lot of websites offering different solutions for Git users: the most well known is GitHub, but also Bitbucket and GitLab are great too. I personally use them all in different situations. GitHub is probably the fastest one – more updated and attractive, but the subscription is only free for open source projects. On Bitbucket you can run private repos, and GitLab will let you run your own server. I won’t mention all the other ones – you can use Google to look them up.

I will use Bitbucket in my example from now on – while the procedures are different on websites, with regards to the command line, Git works in the same way on all platforms.

Once you are logged in to Bitbucket, click on the ‘plus’ icon in the top left corner, and then ‘Repository’. At this point select yourself as ‘Owner’, insert a name for your repository, check ‘This is a private repository’ and select ‘Git’. As I did here:

If you feel confident, you can click on Advanced settings and select some more options, as I’ve done here:

Now:

• If you can, describe your repository in more detail.
• ‘Allow forks’ if you think a third party will need access to your repo (for example, a freelancer or an agency). Forking is a way of letting someone see and work on your repo without any rights to it. You can update this setting at any time.
• Enable issue tracking if you want to keep track of the issues you have on your project.
• Enable Wiki if you want to document your project (describe the code, the functions, how to use it). This is common for open source projects.
• Select a main language (it’s just a label; you can store each kind of file inside a Git project).
• Enable HipChat if required. HipChat is a group chat facility you can use to work together on the same project. I’ve never used it, but if you are a group of developers working together on the same project, it can be useful.

Click ‘Create Repository’ and this will take you to your project home page. Every Git host has its own way of displaying this, but basically once you sign up as a developer you’ll have your personal home page and on that everyone can see your public projects. That means https://bitbucket.org/erme2 is my page and https://bitbucket.org/erme2/myprojectname is the link to the new project we just created (I’ve made it public for you, but don’t make your projects public until you know what you are doing).

Nerd note: In the folder ‘myProjectName’ which I’ve just created is a copy of ‘Twenty Sixteen’ a free theme from WordPress. If you want to create a theme using another theme as a base, have a look at Child themes. When developing a WP theme using Git it’s a good idea to keep just the theme on the repo, as this will help to keep WP and plugins updates out of your repo.

You should now be looking at the ‘Overview’ page of your project which at this point will be empty. You’ll see in the bottom of the page these starting prompts:

We will see what README and .gitignore files are later, but for now I’ll show you how to work with an existing project.

You can open your console/prompt now. I’ll write some standard commands and you will have to update them replacing the ‘username’ with your username and ‘myProjectName’ with your real project name.

We have to change the directory to our project:
cd Projects/wordpress/wp-content/themes/myprojectname
And create a Git repo:
git init
We will connect our local repo to the online repo we just created:
git remote add origin ssh://git@bitbucket.org/username/myprojectname.git
Now it’s time to add all the files we have in our project to Git (also if it’s an empty new project).
git add .

Are you ready for your first commit? (-m is a param to add a message to the commit, it’s mandatory and a good habit to add a real comment.)
git commit -m 'first commit'

Send the commit to Bitbucket
git push origin master

BOOM!

Your first commit is gone and your master branch is on your Git host. Try to reload your project now and you should see the status, the code and a lot of other information here.

You are now ready to start to work on your project but before you do, you should start to keep note of the tasks you are going to work on. If you’ve never done this before, you can start using the ‘Issues’ function you have in Bitbucket.

It’s really important to keep track of your work, because if you need to go back or check your code, the messages on the commit and the connection to a tasks system can save you a lot of time in remembering or understanding why and how you wrote that code.

So click on ‘Issues’ in the left-hand menu and ‘Create issue’ in the top right corner.

You can now:

• Assign it to a dev in your organisation (or yourself as I did)
• Specify if it’s a bug, an enhancement, a proposal or a task
• Specify a priority level
• Attach some screenshots or other files to better describe the issue

I’ve created a couple of issues to give you an example of how you can work on different issues using different branches.

If you look at the ‘Issues’ page after you have created a couple of them, you’ll see something like this:

What’s interesting is the first column I’ve marked in red: every issue has a unique ID, and that’s important because you can use it to name unique new branches. That will link back every branch to a specific ‘issue’, so you can keep track of why you started that branch.

Using the theory above, I didn’t spot issue #2, until I’d started working on issue #1, so keeping to that plan I’ll start to work on issue #1.

git checkout master
git pull origin master
git checkout -b issue#1

The first line will move Git to the master branch and the second will extract the last version of the master from Bitbucket (origin). This is a good habit to develop because Git is used for collaboration on a project and someone else could have merged some new code on the master. So when you create a new branch, it’s better to use the last version of the master to avoid conflicts.

The third line will create a new branch (using the -b param) and will place the Git repo on it. I named the new branch ‘issue#1’ to highlight the connection between the issue I created on the issue tracker and the branch.

You can now start working on your menu as I’ve done, updating and saving some files. This is the moment when we spot the bug and we have a blocking issue to work on.

Ok, don’t panic, you can save your work:
git status

On branch issue#1
Changes not staged for commit:
(use "git add ..." to update what will be committed)
(use "git checkout -- ..." to discard changes in working directory)

modified: header.php
Will show you which are the files you updated but are not committed.

git add header.php
Will add the header.php file to the list of the files you want to commit.

git add .
Will add all the files you updated; in this case they are all relevant, but if you update ten files, you could use ‘git add’ to select just some files.

Nerd note: to see all the differences, you could use ‘git diff’, but I prefer to use the ‘git diff’ tool that almost all the php or HTML editors have. I personally use phpStorm but Netbeans, Atom and Eclipse are valid and free alternatives with a good Git support/plugin.

git commit -m 'updating menu, to be completed'

The commit will freeze your updates locally; a good non-mandatory practice is to save the commit on the Git host.

git push origin issue#1

This is the new situation from a commits point of view:

But let’s fix the button:

git checkout master
git pull origin master
git checkout -b issue#2

The first two lines will get all the updates from Bitbucket and ensure we are branching out from the last master. Then we can create a second new branch using the ‘checkout’ command and the ‘-b’ param.

We can now fix the bug on the button and check the Git status:

On branch issue#2
Changes not staged for commit:
(use "git add ..." to update what will be committed)
(use "git checkout -- ..." to discard changes in working directory)

modified: css/editor-style.css
modified: index.php

We can add all the files using:
git add .

Ready for commit and push:
git commit -m 'hiding pagination buttons'
git push origin issue#2

This is the new situation from a commits point of view:

As you can see from the green tree on the left, the two commits are not in the same branch. Nerd note: try to keep this tree as simple as you can.

We can merge the issue#2 branch in the master now, and tag and release a patch to fix our website. Open the branches link from the left-hand menu on your repo page and click on ‘issue#2’. Now click on ‘Create pull request’ in the right top corner.

You can add some notes, keep note of who reviewed the code and then click on ‘Create pull request’.

The next page will describe the process, and you can review the code you are committing to the master branch here by looking at the bottom of the page. If everything looks fine, just click on the ‘Merge’ button, but if you see some errors, you can ‘Decline’ or even ‘Edit’ the commit.

I clicked on ‘Merge’.

You could keep the ‘Close source branch’ selected, but I usually don’t delete merged branches for a couple of weeks in order to keep a record for a reasonable time. Meanwhile I can check what I did commit on this branch/issue.

We are ready to tag our first version:
git checkout master
git pull origin master
git tag -a 00.0000 -m 'issue#2'
git push --tags

This is the new situation from a commits point of view:

Bitbucket is now referring to the last tag to show us the current version of the repo (not the main branch) and is hiding all the unmerged branches. You can click on ‘Show all’ which I’ve marked in red to gain a full idea of the situation.

You can now release your update onto your server.

If you are on a managed host service, you should have a Git app or wizard to load a Git tag or a Git commit (also the tag is a commit). The commit ID you want to load is the one I’ve marked in green on the screenshot ‘db869d0’ above. If you can’t see it because it’s faded (Bitbucket fades it because you should use the tag name), just click on it and you’ll see it on the following page, near your name:

If you have access to the Unix shell on the server, the command to checkout the tag is:

git checkout tags/00.0000

Where 00.0000 is the tag name. To be faster you can write an sh script. To do it you can create a file release.sh with this content:

#!/usr/bin/env bash

# preparing git to checkout
git stash

# getting the last tag and checking it out
git pull --tags

#guessing the last tag name
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)

#checkout the last tag
git checkout tags/$latestTag

#echoing the last tag you just loaded (just to confirm)
git describe

I added the release.sh file in my last tag [00.0001] in my project; please feel free to copy it.

Now you can save the file as release.sh and if you can execute it calling it with the sh command:
sh release.sh

That single command will load the last version of your repo.

That’s pretty much it. Hopefully you should now be able to run your own project in Git. Give it a try and let me know how you get on. If you have any questions I’m always here to help!