Why you should version control your work

I started using git last year at work and I really like it. I used it sporadically for my own work at home but never for real. Now I use it every day. I recall reading a while ago a blog article somewhere titled "Are you still coding or are your versioning yet?" (I can't find it right now, if I find it againg I'll insert the link here) And actually I think there is some truth in it. Versioning your work is a different paradigm.

Many office workers have had to endure the half-baked measures put in places in (non-tech?) companies when it comes to file naming and project process tracking. Start by writing the date at the beginning of the file name (which format for the year? YYYY or YY?), then an underscore (or maybe a hyphen "-"?), then a concise description of the content (what about Leistungsübersicht Entwurf? Oh, wait, there is a space in the concise description... nevermind), and don't forget your initials to show you're the author of this file... or folder (!). All in all, it can lead to marvels like 20260205_Konzept Tragwerksplanung PS (final-2).txt which completely clutter your path boxes, terminal prompts and chat windows. Good luck finding your way through a project you don't know anything about but you need to find this one piece of information in its latest version (a dimension, a concrete grade). Is the newest file the one with the newest date in the name, or the one that has indeed been modified last according to the file explorer?

Happily I only rarely have to deal with such obfuscated file names (the privilege of working in a one-man team). And versioning is the silver bullet against those file naming monstrosities.

In fact, more than just solving the file naming problem, version controlling (and git in particular)

• helps structuring work in coherent blocks
• encourages experimentation by branching forth and back
• makes it easier to track the incremental change in a project
• can maybe even help to bill and plan future projects better, as the time and work allocated to each task is transparently displayed in the commit history

This might be clear for code-based professions like developers, but I think these are important aspects also for civil engineers. In a bid to systematise and automate my work (this is especially useful in highly parametrisable shapes like a container tank or a bridge, but it works also for high-rise buildings), I have been working almost exclusively with text-based programmes for years now: SOFiSTiK, R and LaTeX.

Structure your work

First, version control helps the engineer structure his work. Regularly committing to a repository (my project) forces me to complete tasks until they're done rather than leaving a part of it aside. Let's say I've been working on the system, so the file sofistik/system.dat is shown as modified in the index. I go on and document the changes made to the system, so I open the file tex/system-description.Rnw¹ and modify it. And if there are some new appendices for the documentation, I add them in the file tex/appendix.Rnw and it shows in the index of the tree. As I commit the changes, I can clearly describe my thoughts in the commit message, and this closes my work unit. Calculate, report (for your client), document (for your colleagues). So easy, how could I forget that?

But let's be honest, working that straight-forward is rare. You start to tune some mechanical parametres in sofistik/aqua.dat, which leads you to renumbering your cross sections, then you notice that your node numbering system is not quite OK, so you start dealing with that as well in sofistik/system.dat, and here you see that you can quickly correct that one typo in the documentation tex/system-description.Rnw... After an hour and a half, you've made changes all around the system and it's a mess to recall what path your thoughts were following. But git can help here, too:

1. Check what you've been doing with git diff <file>
2. Commit only parts of a file with git add -p <file>
3. Keep a temporary commit message commit.txt where you record your changes and commit using this file as a draft with git commit -Fe commit.txt

And dont forget to branch.

Branch and experiment

Branching is so dumb but so powerful that it's silly to think not to work with this feature.

Let's say I want to try to change my loads from line to area loads. OK, let's copy sofistik/wind-loads.dat to sofistik/wind-loads-area.dat, then comment this one line in sofistik/main.dat and add this here:

$ +apply .\wind-loads.dat
+apply .\wind-loads-area.dat

No, stop! STOP!

With git, you just modify the content of your sofistik/wind-loads.dat and if you're not happy with the results, you just use git restore --file sofistik/wind-loads.dat to go back where you started your experiment. And all the changes are gone. Even though you saved your file and ran wps.exe on it.

If you realise that it's getting a bit twisted, as you again started to deviate and modify a few files left and right, then create a branch on the fly with git checkout -b wind-loads-area. If it's too fishy to work on now but you'd like to keep it for later experimentations, go back to your main branch with git checkout main. And the beautiful in this is: no change is lost. Halleluja! You've got your messy work on the wind-loads-area branch, but once you git checkout main, all the modified files in your project directory come back to the state where you left them before.

Branching in git is the digital equivalent of drawing a new page from your paper block, starting to write on it, then crumple it and ditch it if you're not satisfied with the outcome. But you always know where that crumpled paper lies next to your desk and you can always have a look at it, embed it back into your work, or finally burn it forever.

Track every change

As you commit (and branch), you describe your changes to the project. Because everything is stored in the history of the project, it's possible to see what happened to every line you wrote. Start with git log <file> and see how the file was modified since you started the project. But you can also check for particular changes in your project.

Let's say I've changed a variable (maybe a partial safety factor) at some point in the past and want to know more about that change. Currently the line looks like this in my input file main.dat:

LET#GAMMA_B 1.00

So I go with

git log -p -S"LET#GAMMA_B " sofistik/main.dat

and I get a list of all the commits where the line containing LET#GAMMA_B was added or removed (i.e. modified) from the file, I see the context in the file and see the commit message, where I duly described the reason for changing this variable. Of course.

Plan better

At any time, I can use git log to check the date and the content of each commit, so I can answer following questions:

• When was the model ready?
• When were the loads ready?
• When were the loading combinations ready?
• When were the design checks ready?
• How long did it take to document the fatigue checks?

In the best case, I've worked only on this project lately and I can measure the time for each task by simple date substraction. But even if I'm working on several projects simultaneously, as I have a timestamp for each commit across my projects, I can reconstruct the time needed for a step in one particular project.

Collaborative work a thing?

The few points I made here are solely focused on my last few projects, which I worked on my own. The wild thing with git is apparently collaborative work, as all changes from anyone are logged. This means that several different persons can work on the same project simultaneously, or sequentially, without any loss of information, as it's contained in the comments in the code and in the commit messages.

I can't say much about that (yet?) but even if you're working on your own, it's nice to have this meticulous project history at hand if you need to delve back into it at short notice or just to get some inspiration for a similar project later on. And if you happen to be ill or away from the office, your colleagues will be able to jump into the project, follow its development and find the information they need.