Overview

traditional save patterns without git

Traditionally we may save a file in-place, or to a new file.

Saving in place is destructive: it does not preserve the old version.

Saving to a new file is not destructive, but leads to another challenge: managing multiple versions of a file, including managing the name and the location. Doing this manually is cumbersome and error-prone.

saving a project's snapshot

Software projects are made of multiples files, that live in nested directories.

As such, if we want to save a project as to how it was at one point in time, we must save the whole file tree as a snapshot.

The simplest way to save a file tree is to archive it as-is, but it leads to heavy storage footprint, and it clutters the filesystem with duplicates. It requires naming each snapshot with a distinct name, and navigating between different snapshots manually.

what we want from a versioning software

We want an approach that is more efficient in terms of storage and more convenient in that we don't name or navigate between snapshots manually. We also want the ability to store metadata related to a snapshot, such as a message that describes the changes made compared to the previous snapshot, the snapshot's date and unique ID.

The snapshots must not be stored as-is but instead be stored in a more granular way. The software ensure files are not duplicated: it manages, stores and retrieves files in way that does not require duplication.

The software ensures the snapshot may be reconstructed on-demand.

The software ensure we may conveniently browse and load old snapshots.

lightweight snapshot: a declarative list of files

We store the snapshot as a declarative list of files (their names) that make up its content, like a shopping list. The software may reconstruct the snapshot based on the list.

In this pattern, the files may live anywhere, for example in a storage area. This allows files to be referred to by several snapshots, and to only be stored once.

When needed, the software fetches the files from the storage and place them (a copy) in a given directory, effectively reconstructing the snapshot.

edit area

The local directory where we make changes is called the working directory or working tree.

We want the latest snapshot (or rather a copy of its content) to be, by default, present in the working tree so that we may easily edit it and submit a new snapshot for save.

terminology

to commit means to intentionally save a snapshot. A commit as a name is the term that refers to a given snapshot. Technically it's an object that stores references and metadata.

staging area, also called the index, represents a tentative snapshot, that is yet to be committed.