Getting started

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 &c.) 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 &c). 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 also became 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 &c.) 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 to both Git and GitHub. It allowed a proper windows-based 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^†3), also have a wide range of in-house terminology and phrases — things like:

• Push

• Pull

• Repo

• Fork

• 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.

I should say right from the start, that Git and GitHub are designed by geeks for geeks—and it certainly shows. They belong to a bit of a club where those in the club don’t really want to explain it to those outside; they say they do (because it’s open source, liberal and trendy), but they don’t. There is a lot of information about them, but it’s all designed to be a bit intimidating and to make you feel, well, stupid. It reminds me very much of the gramophone sketch by the Not the nine o’clock news team. It’s the same attitude.

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 it 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.

Michael Gledhill
May 2025 — Chester

Footnotes
†1		I worked for one company that shall be nameless (let’s just call them “MonoBar”); they operated a blame-free culture intended to prevent accidents by encouraging people to report the smallest incident. The idea being if you stop the small things, you will prevent the larger things. This was fine for the small things, nobody minds being told to use a coaster for their coffee cup. Bit different when the building burns down.
		It did lead to a bit of a sub-culture: whilst they operated a blame-free policy, they did like to know whose fault it was. ↩

†2		MS DOS 6.22 was a Microsoft operating system that predated Windows. If your curious, or too young to remember, here’s an online emulator: MS DOS 6.22 it comes with pretty cool versions of Doom and Duke Nukem. ↩

†3		I’m English and the word, git has a meaning in England: git [noun] a contemptible, stupid or unpleasant person, usually a man — “You miserable git!”. ↩