LibreOffice Calc & Python Programming: Annex 0 – Version control with Git

This episode of my LibreOffice Calc & Python Programming tutorial is a bit special. It is not about coding python scripts for LibreOffice, yet it is to learn a really useful method to track the different versions of your programs.
We are going to learn using Git for version control.

If you want to be serious about programming, you need to start using version control, and the earlier the better. In this tutorial we will focus on keeping track of different versions of your programs and how to recover a previous version. I will only mention briefly the ‘branching’ method because that method is more useful when working in a team.

Here is the plan for this Annex 0 of the tutorial:

• What is Git?
• Install Git
• How to use Git
• GitHub

What is GIT?

Git is a version control tool. It helps you to keep your programs tidy so that you don’t need for example to keep all the backups of all the different versions of a function within a program. For example, in the first coding tutorial (which is actually part 2 of the series) of this series we wrote a helloworld function within the ‘helloworld.py’ (python) file. Then in the second coding tutorial (part 3…) you may have re-used that same file, like I did and then added the new functions to it, and either deleted or commented the helloworld function within that ‘helloworld.py’ file. Or even create a completely new file like ‘helloworld2.py’.

With Git (or any other version control system) you would ‘add‘ to a ‘Git repository‘ this first version , then you would ‘commit‘ this same first version of ‘helloworld.py’. Once you have done a ‘commit’ of a file you don’t need to worry about it, a version control tool like Git keeps the version safe in an hidden folder.
From then on you can delete the unwanted code in your file without having to make a copy of the file. You then repeat the process (‘add’, ‘commit’) for your second version.

It is important to write a relevant comment when you commit changes of your script/program. Then when you look at the log of the different versions you can choose which one you want to reverse to (check out).
Git is a command line version control system, meaning that you have no fancy colorful windows with menus and gizmos but it is simple, very common and does the work pretty well. There are several other version control systems like CVS, SVN, Mercurial. If you prefer managing your programs’ different versions in a more graphical way there are some GUI available that are based on Git. One of them is an online Git GUI called ‘GitHub‘. The big advantage of Git is that it is 100% compatible with this very famous GitHub. There are also many other online tools like BitBuckets, GitLab. I am personally very happy with Git and GitHub.

Install Git.

As I am Super Busy Daddy, time is precious for me so please accept my apologies for sending you the linode website article on how to install Git.
(You can choose your OS: Mac, Windows or Linux to get the relevant instructions).

Then once you’ve done it we can focus on how to use Git!

How to use Git.

• Create a Git Repository (a ‘Git Repo’ for short) – git init
• Check the Repository status – git status
• Add files to the repo. – git add .
• Commit the changes – git commit -m "My first commit!"
• Check the log – git log
• Checkout a commit id – git checkout xxxxxxx
• Working with branches – git branch
• Compare branches – git diff new-test
• We can merge branches! – git merge new-test

Create a Git Repository (a ‘Git Repo’ for short) – git init

Once you have successfully installed the program Git on your computer it works the same way on all different Operating Systems.

To use Git you have to type command lines within a Terminal. In Windows it’s the ‘CMD’ or ‘Command prompt’ accessible from Start Menu. In Linux and Mac, you need to use the ‘Terminal’:

Open a command prompt in Windows (XP, 7, 10): here we go again, it’s quite late already so instead of writing what other have already written please follow this link to a relevant Lifewire article if you don’t know how to open a terminal in your OS.
Once you have your terminal open , simply use the command line to navigate to where your program is stored.
For example my program helloworld.py is stored in the linux hidden folder '/home/gweno/.config/libreoffice/4/user/Scripts/python/MyPythonLibrary/Tutorial'
If you are using an IDE you can also use the terminal embedded within it like I do with Geany (check the requirements post of this series for more info on IDEs and Geany).
So in the terminal of my Linux Mint System I type:

cd ~/.config/libreoffice/4/user/Scripts/python/MyPythonLibrary/Tutorial

(In linux the ~ is the path for your home folder)
the command ‘cd’ is for ‘change directory’ and is the same for Windows and Mac.

Once you are in the correct folder, where for example ‘helloworld.py’ is,
the way to create a new Git Repository (meaning a new folder where the Git program will store all the versions of your code) in its simplest way is the command line:

git init

That is enough to get started with Version Control of your program files.
Of course there is much more that you can setup (git config). Like your user name, email address, an author name, a link with an online repository (like GitHub) if you have one, and other stuff but the intention here is to keep it simple because this is only an annex to help with LibreOffice/Python programming after all!

Check the Repository status – git status

After initialising your Git Repository, you can check the status of this repository with:

git status

You should see the following message on your screen:

Initialised empty Git repository in /home/gweno/.config/libreoffice/4/user/Scripts/python/MyPythonLibrary/Tutorial/.git/

That is a good start.

Then try to check the status of your new repo:

git status

You should get something like that:

Add files to the repo. – git add .

So let’s add our helloworld in the tracking system with:

git add .

The syntax is quite easy. The ‘.’ above in ‘git add .’ means add all files that are un-tracked. You can also add a specific file by doing ‘git add <file name>’ for example:

git add Helloworld.py

Now a ‘git status’ should give us:

So let’s just create a new empty file in the same directory.
We can call it test.txt and write a single line:

Another ‘git status’ should show us this new file

What GIT is telling us is that for now there is currently 1 file staged for a commit, and the new file ‘test.txt’ that is not staged yet. So the next step is to add this new file with a ‘git add .’ (or ‘git add text.txt’).
Then a new git status should give us:

Commit the changes – git commit -m "My first commit!"

To ‘commit’ these files to the repository, which means to keep them as they are at the time of the commit, we need to do so with a relevant comment that will help to know in the future what were the changes in these files.
The git command is ‘git commit -m “relevant message”, like this example:

git commit -m "My first git commit! With HelloWorld and a test file"

Try yourself a new git status, you should see no files un-tracked.

Let’s then modify our ‘test.txt’ file:

After saving, another git add, another commit with a relevant message, we then have 2 different versions in the repository but only the last version, the current one is visible, there is only one version of each file visible in the directory. This is normal, the previous version is actually in the hidden git folder.

Check the log – git log

To revert to the previous version or any other version in the log you need first to look at the git log and then ‘checkout’ the commit number:

git log

Checkout a commit id – git checkout xxxxxxx

You don’t need the full commit id number (called a hash number), you only need the 7 first character. So to reverse to the first commit in our case you’ll do:

git checkout f3de45b

As you can see, once I have ‘checked out’ the first version, I need to reload test.txt file. Once reloaded it is indeed back to its first version with only one line of text.

From there you can make some new changes and create a new branch what literally means that you are not going back to the second version.

You can also come back to your latest version by checking out the last commit number like in my case ‘git checkout 70d99b0’.

Working with branches – git branch

There are actually many possibilities and scenarios that can be achieved with git. But let’s keep it simple for now and continue on this new branch also called a ‘Detached HEAD’.
Let’s add a new change in our test.txt file by adding a new line at the end:

Then add the change to git (git add .), commit with a message and you will see that the commit is indeed on a “detached HEAD”. You can even display the branches with this useful git command:

git branch

Which gives a clear idea of where we are:

The star tells on what branch we are. There are currently 2 branches:

• the master one that has you first and second commit
• the new HEAD which is detached from your first commit

Now let’s say that you want to include your new changes with what is the the ‘HEAD’ of the ‘master’ branch, which correspond to the second commit.
To do that we go back to our ‘master branch’

git checkout master

But then oops!

This warning tells us that we also need to make the ‘detached HEAD’ a proper new branch or we could risk losing the changes we made.
To create a new branch a this point:

git branch new-test cc8f9b8

Here the cc8f9b8 is the number of my last commit on the ‘Detached Head’. And ‘new-test’ is the new branch’s name.
Command ‘git branch’ now gives us:

We are on Branch ‘master’ and the other branch is called new-test.
And indeed after reloading file test.txt we are back to our second version, the second commit we did.

Compare branches – git diff new-test

To merge the version in the branch ‘new-test’ with the version in the branch master it is common good practice to first check their differences with this command:

git diff new-test

So we are telling git to show us the differences between the HEAD of current branch (which is ‘master’) with the HEAD of the branch ‘new-test’. That gives us:

It tells us that our current version on ‘master’ has the green line but version on ‘new-test’ doesn’t have it.
Both version have the white line.
The current version on ‘master’ is missing the red line that the version on ‘new-test’ has.

We can merge branches! – git merge new-test

So now we know the differences between the two HEADS, lets merge them!

git merge new-test

Depending on what editor/IDE you are using (see my article) You may have a file opening automatically asking you to write a ‘commit message’ when you merge. Just write something relevant, save and exit the file. This is because a merge is like a commit and it will appears in your ‘git log’.

And now our file on the HEAD of ‘master’ is:

And indeed git status will show you the merge as a new commit.

GitHub

GitHub is an online git repository. GitHub allows you to store your programs and keep their different commits and branches online. It is a great tool to share your work, to work in as a team and to look for other people’s programs. And you can link your git repository with your gitHub repository making it very easy to publish your latest commit online.

So let’s me show you how you do that.
First you need to create an account on gitHub if you haven’t got one. It’s free if you are not bother to have public repositories of your programs, or you can choose a paid option if you want to keep your ‘reps’ private.

Once you have an account, simply find the ‘new’ (repository) button, give it a name, a few basic settings and then the magic can happen,… well after a few settings on your computer’s local git repository as well.

Once you have created your online repository you will get a link like in this example:
https://github.com/Gweno/tutolibro.tech.git

(of course this is my github account and rep so don’t try to recreate it! It won’t work!
just use your own)

Now it is time to go back to your terminal and use git to interact with GitHub.

• Link your GitHub and git repos – git remote ...
• Push your git repo to your GitHub – git push -u origin master
• Clone other people GitHub repos – git clone ...

Link your GitHub and git repos – git remote ...

You are going to use this link on your local repository, there is even instruction on the gitHub webpage to help you set up your rep.
But if your local rep is already set up, you only need to link it with the gitHub rep with this command:

git remote add origin https://github.com/Gweno/lopy-test.git

(you won’t be able to use that one for the same reason as before, it’s mine! This is just an example, use your own)

You can check that your local git repository is attached with your online GitHub repository with this command:

git remote show origin

Push your git repo to your GitHub – git push -u origin master

Now that your local git rep is linked with your online one, your can ‘push’ all your commits from your local rep to your gitHub with this command:

git push -u origin master

You will then be prompt to enter your GitHub user name and password to let git connect directly to your GitHub repository.
And hopefully get a successful log like that one:

Clone other people GitHub repos – git clone ...

Now I can check my GitHub repository and see that all my commits are there with the latest commit being the current state of the files.
And now other people can download your code.
For example you can clone my repository on your local computer with this:

$ git clone https://github.com/Gweno/lopy-test.git

(this time you can use it as is and I encourage you to do so as I am happy to share this rep with you!)

This tutorial only shows a small portion of what is possible to do with git and GitHub. There are a lot of very good articles and websites dedicated to git, GitHub and the likes.
Now I will work on more LibreOffice Python tutorials, I hope this one on git will be useful to you. It is a great tool to me and really helps once you start to write a lot of lines of codes.

This is the link to my repository for this lesson on gitHub.

If you like this tutorial you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!