A shared drive with dated filenames holds a project together while one person edits it. Put a second editor on the same file and the folder stops answering the question that matters at release time: which copy is authoritative, and what separates the two. Dated copies store states and discard reasons. Version control systems store the reasons, and every practice below exists to keep that record usable.
What a repository has to answer
Michael Ernst's Version control concepts and best practices splits the machinery in two. The repository is a database of project versions. The working copy is the personal copy where edits happen. A commit moves a set of changes out of the working copy and into the repository. The GOV.UK service manual defines a commit as making a set of changes permanent, and requires the attached message to describe what changed and why.
The OxRSE version control training material states the guarantee in one line: "Nothing that is committed to version control is ever lost, unless you work really, really hard at it." History survives. Attribution survives. A bad release is reversible.
Three commands carry that guarantee into daily work.
git status
git diff --staged
git commit -m "Reject expired session tokens"
git status lists what has changed. git diff --staged shows the exact lines that will enter history. The message records intent. A commit carrying all three is searchable twelve months later. A commit carrying only the first is a snapshot nobody can explain.
Two rules keep the message useful. The GOV.UK service manual requires a clear message that describes the change and links supporting information such as a bug report or a development story. Ernst's guide adds that each commit to the main branch should serve one purpose and complete it, so a bug fix, a feature, and a typo belong in three commits.
Distributed arithmetic changes the update path
Ernst's guide draws the line between the two families. Centralised version control keeps one repository. Distributed version control gives every user a repository and a working copy.
For a colleague to see your commit in a centralised system, two steps have to complete:
- you commit
- they update
The distributed system spends four steps on the same outcome: commit, push, fetch, update. The extra work buys three things. Every user holds the full history, so a network outage costs nothing. Branching is local and cheap. Merging happens on the contributor's machine before anything reaches the shared repository.
The command set hides that arithmetic. The version control concepts guide notes that git pull runs a fetch and then an update, which makes push and pull unequal operations. Keep the four transfers in mind and the interface stops being confusing.
Conflicts follow from the same arithmetic. Ernst's guide defines a conflict as two users making different changes to the same line. Simultaneity is loose: Change 1 and Change 2 count as simultaneous when each user edits before pulling the other's work in. Push and fetch never produce a conflict on their own. They can leave the repository holding divergent histories, and merge is the explicit operation that reconciles them. A team that pulls daily meets each conflict while the edit is still fresh in memory.
Requirements that hold when a release goes wrong
The HMRC engineering standard on version control, last updated 21 March 2025, sets six requirements. Each one answers a failure that has already happened somewhere.
Building a deployable artefact from source must stay possible at every point on the main branch. Work in progress stays off that branch until it is complete and tested. Feature flags let a merge land while the behaviour stays dormant until configuration switches it on.
Multiple contributors need an agreed route to combine their work. The HMRC standard treats conflict resolution as a skill the team must hold, and notes that the problem scales with contributor count.
Commit signing is enforced on every branch that builds or deploys. Public-key cryptography attaches a signature to each change, and the version control server rejects any change whose signature is missing or invalid.
Direct changes to the main branch are blocked. Reviews and automated tests run before a change reaches it, and no single person can push through alone.
A branching strategy is defined, documented, and followed. Trunk-based and feature-branch workflows both qualify. An undocumented strategy is not a strategy.
Every change arrives with a rollback or fix-forward plan. Rolling back affects users who already hold the updated version and any state externalised to a database. Fixing forward requires a hotfix branch based on a point in history that the main branch no longer matches. The HMRC standard requires that branch to exist before the incident starts.
These six requirements assume a distributed system underneath them. The same GOV.UK service manual recommends distributed version control for three reasons: everyone holds a full copy of the code and its history, branches are easy to create and discard, and developers keep committing when the network is down.
Choosing a system from the constraints you already have
The Sound Software guide to choosing a version control system reduces the decision to three questions: what the people around you already use, where the code will live, and which tools and documentation exist. The same guide names three systems that clear the bar of free, common, and capable.
Git. Distributed. The tool with the widest open-source footprint. Imperial College London's computing guide states that Git is required on some first- and second-year courses and is the recommended default for new group projects. Windows support arrived late; TortoiseGit now covers it.
Mercurial. Distributed. The Sound Software guide reports that the project runs Mercurial hosting for UK audio and music researchers and publishes a desktop client, EasyMercurial. A Windows client, TortoiseHg, exists. Non-Western filenames on Windows remain a known limitation.
Subversion. Centralised. Windows has the most complete client support through TortoiseSVN and SmartSVN. Imperial's guide describes Subversion as a better replacement for CVS. The GitLab guide records that it keeps a project's files on one code line and lets access to subfolders be restricted.
The GitLab guide to version control splits version control systems into four types. Distributed systems place repositories on every machine. Centralised systems keep one repository on a server. Lock-based systems prevent two people opening the same file at once. Optimistic systems give each user a private workspace and merge the results on submission at the server.
Hosting follows from the same three questions. An institution that runs a version control server should be used first, because backups and support come with it and the work stays reachable after you leave. The Sound Software guide describes GitHub as built around forking, which suits speculative and loosely collaborative work, and notes that GitHub charges for private repositories while offering free educational accounts. The same guide records that Bitbucket allows private repositories with up to five users at no cost, which covers a small research team.
Nothing above depends on which system you pick. The GOV.UK service manual puts the requirement first and the tool second. The HMRC standard opens on the same point: "Effective use of a version control system requires agreement around how it will be used." Pick a system your colleagues can run. Write the branching strategy down. Enforce signing on the branches that deploy. Then the history is worth something.
