About Mastering Github

I am by profession an engineer, I build and programme control systems for a living (industrial machinery, pharmaceutical manufacturing, even tritium handling systems for nuclear reactors). The software that goes in these systems is (usually) rigorously tested and anything that goes into a regulated environment (pharmaceutical, nuclear, safety systems etc.) has quite stringent version control and traceability requirements.

Version control is important, particularly when the reactor melts-down and you want to know who to blame ^†1 . It’s also important when you’ve completely messed things up and you need to back to an earlier, less messed-up version.

Now I write industrial software and these applications usually have their own development environments and version tracking mechanisms that are particular to the product being used (Siemens, ABB etc.). Other things such as documents and drawings are controlled by the in-house version control system that we operate in the office.

At some point I started my own website, The Practical Series of Publications, which I originally intended to contain some obscure engineering texts in the form of a web-based book that might have been useful to other engineers.

When I started the Practical Series website, I wanted some form of version control. It was just me working on it, so I didn’t need anything too ambitious—and in the early days I just kept increasing the revision number and backing up everything each time I did so.

This was fine, up to a point. Websites are not particularly massive things, a few megabytes; and having multiple copies doesn’t tax a modern hard drive particularly.

So, what was the problem?

Well the main problem was that I wasn’t documenting the revisions properly; the website has a lot of files (way over a thousand) and while I had a copy of every file at every revision, I didn’t necessarily know which files had changed from one revision to another.

It was also a very inefficient mechanism; there were probably some files in there (images for example) that were in at the first revision and were backed up without change in every subsequent revision up to the latest (there were over 150 revisions when I stopped).

It became more complicated when I wanted to work on two different things at once; I might for example be correcting typos in one section that had just been proofread, while developing a new section from scratch. It was difficult to keep track of each.

So while what I had worked, sort of — I could always go back to an earlier version. It was laborious; I would have to guess which revision I wanted, unzip it and then look at the file I wanted to see if it was the right version, if it wasn’t I had to guess another revision and do the same until I found the one I was looking for. This was OK in the early days; but at the point where I switched over to proper version control, I had 78,000 files in 35,000 folders and 150 zipped revisions. The whole thing was taking up 7 GB most of which was identical copies of files that hadn’t changed between revisions.

It was at this point that I decided I needed some proper version control and while I could have used the office system, that didn’t feel right. My website was nothing to do with my work (more an expensive hobby really) and I didn’t want to take advantage. Neither did I want to buy the office version for home use, it was just two expensive and way over the top for what I needed.

So I had a look around. There are lots of different version control systems out there; some are free, some are commercial applications. The question is: which one to use?

One thing that gave me a clue was the software I had used in developing the website. I had used various open-source software files (some CSS files, some Java Script code etc.) that improved or added functionality to the website (things like lightbox images and formulae on web pages). I noticed as I researched these things, that virtually all of the people developing these applications used GitHub as their version control system.

So I decided to have a look at GitHub and I realised that this was the online version of Git, Git being a local version control system that runs on a PC or Mac.

I had a couple of goes at it and gave up each time — Git and GitHub have a pretty steep learning curve, especially Git (the application that runs on a local machine rather than GitHub that is web based). Git is driven through a command line terminal emulator (just like MS-DOS^†2 and those text adventures from the eighties) and is virtually impossible to use without having a reference book open.

My conclusion was that both Git and GitHub are complicated and very difficult to understand.

In the end I came to terms with them both, then I found Visual Studio Code (a text editor developed by Microsoft and use by pretty much everybody) that provided a decent front end and interface to both Git and GitHub. It allowed a proper windows-based (GUI^†3) approach to be taken with both applications and it was much more intuitive.

Git and GitHub, apart from having peculiar (and slightly rude sounding names^†4), also have a wide range of in-house terminology and phrases — things like:

• Push

• Pull

• Repo

• Fork

• Branch

• Checkout

• Rebase

• Tag

• Release

• Gist

• Flirt

Ok, I made the last one up, but you wouldn’t necessarily know.

It is all very confusing and not that well explained.

It takes a long time to get to grips with Git and GitHub — to such an extent that I had to make lots of notes, do a lot of reading around the subject, try a lot of different things and experiment with them until I had an understanding of what it all meant and how it worked.

And since I had written it all down, I thought it might be useful to other people — so I decided to publish it as a website, and here it is, dear reader, use it wisely.