Skip to content
Documentation Background

Version control systems

A version control system (VCS) records every change to a set of files over time: what changed, who changed it, when, and why. It lets several people work on the same files without overwriting each other, and it lets anyone go back to any earlier state.

Version control isn’t only for application code. Infrastructure definitions, configuration, documentation and pipeline files all belong in it. In GitOps, the repository is the description of the running system.


TermMeaning
RepositoryThe store of all files and their full history
Working copy (working tree)Your local, editable copy of the files at some version
CommitA recorded change: a snapshot plus author, time and message. Commits are atomic: they’re stored completely or not at all
BranchAn independent line of development. Work on a branch doesn’t affect others until it’s merged
Trunk / mainThe primary branch that other branches start from and merge back into. Subversion calls it trunk; Git repositories usually call it main
MergeCombining the changes from one branch into another
ConflictTwo changes to the same lines that the tool can’t combine on its own. A person has to choose
TagA fixed, human-readable name for one specific version, such as v1.4.0. Unlike a branch, a tag doesn’t move
Clone / checkoutGetting a copy of a repository (distributed) or of a version of it (centralised)

Versions are kept on one machine, in a local database of changes or simply as copied folders (report-v2-final-FINAL/). There’s no collaboration, and one disk failure loses the whole history. RCS was the classic tool.

One server holds the repository. Each developer checks out a working copy, and every commit goes straight to the server.

flowchart TB
    S[(Central server<br/>full history)]
    A[Developer A<br/>working copy] <--> S
    B[Developer B<br/>working copy] <--> S
    C[Developer C<br/>working copy] <--> S
  • Examples: Subversion (SVN), CVS, Perforce.
  • Strengths: one obvious source of truth, fine-grained access control per path, simple mental model, good with very large binary files (Perforce is common in game development).
  • Weaknesses: the server is a single point of failure. Without a network connection you can’t commit or see history.

Every clone is a full copy of the repository, history included. Developers commit locally and then push and pull changes between repositories.

flowchart TB
    S[(Shared remote<br/>full history)]
    A[(Developer A<br/>full history)] <--> S
    B[(Developer B<br/>full history)] <--> S
    A <-.-> B
  • Examples: Git, Mercurial.
  • Strengths: work offline, fast local operations, every clone is a backup, cheap branching.
  • Weaknesses: more concepts to learn (local vs remote, push vs commit). Large binary files need extensions such as Git LFS.

The shared remote (GitHub, GitLab, a self-hosted server) is a convention, not a technical requirement. Any clone can serve as the source for another.


Linus Torvalds wrote Git in 2005 for Linux kernel development, and its design reflects that project’s needs:

PropertyWhat it means in practice
SpeedCommits, diffs, logs and branch switches are local operations
Cheap branchingA branch is a pointer to a commit, so creating thousands is normal
Full distributionEvery clone has the entire history and can work offline
IntegrityEvery object is addressed by a hash of its content, so history can’t change silently
ScaleIt handles very large histories, like the Linux kernel’s

Its real dominance came from the ecosystem built on it: GitHub, GitLab, pull requests, and CI/CD systems that trigger on pushes. Almost every DevOps tool assumes Git.


ToolModelWhen it fits
Subversion (SVN)CentralisedOrganisations that want path-level permissions and a single central repository, or that already have large SVN histories
Mercurial (hg)DistributedSimilar to Git with a simpler command set. Still maintained, but far less common than Git
Perforce (Helix Core)CentralisedVery large repositories with big binary assets, such as games and media

For new projects, Git is the default choice unless there’s a specific reason above.


  • Application source code and tests.
  • Infrastructure as code (Terraform, Ansible), Kubernetes manifests, Helm values, pipeline definitions.
  • Documentation, runbooks and architecture decision records.
  • Secrets only in encrypted form (for example with SOPS). Never in plaintext, even in a private repository, because history keeps every version forever.

What doesn’t belong: build outputs, dependencies you can re-download, local editor settings and anything machine-specific. List those in .gitignore, but check what you ignore. An ignored file that a rebuild needs is a file that only exists on one laptop.