History¶
Every time SampleKit writes to a project, it first keeps what the project held. You can then see what changed and when, put a file back as it was, read the whole project as it stood on a given day, and find out where an exported table or a figure came from. This page says what the history keeps, when, and what it is not.
Why SampleKit keeps a history of its own¶
A value changed by mistake, a computation run over the wrong samples, a figure in a manuscript that nobody can trace back to its data: these are the losses that cost most, and they happen to careful people. Git would answer them, but many researchers do not use Git, and those who do do not commit after every command. So SampleKit keeps the history itself, without asking you for anything: no Git to install, nothing to set up, and it cannot be turned off.
What it is¶
The history lives in .samplekit/history/, beside the project's
.samplekitrc. A project, that is a folder with a .samplekitrc, is needed:
a folder of samples without one has no history, and a command that asks for
it says so.
A snapshot is the state of the project at one moment:
Kept in a snapshot |
Not kept |
|---|---|
|
a sample's own files (photos, reports, raw data) |
every sample file of the project, in every subfolder |
exports and figures |
the model's source files, even when they sit outside the project |
the Python environment |
What is not kept is either not data SampleKit reads, or can be large, or can be made again. Exports and figures are not kept, but they are recorded: see Where a file came from.
The history is a Git repository, so any git can read it if you have one.
It is SampleKit's own: your own Git repository, if the project has one, never
sees it (it ignores itself) and is never changed by it.
Each file is written once and never changed. A snapshot writes each version of a file whole, named by its content, and removes nothing: that is what lets git or a synchroniser carry the history between computers without a conflict. A year of daily work on a collection of seventy samples is about 35 MB; where git holds the history, it packs it in its own repository.
Reading it without SampleKit¶
Your data never depends on SampleKit being there to read it. The samples
are Markdown files any editor opens, and the history is an ordinary Git
repository: should SampleKit one day stop running on your computer, or stop
existing, git reads every snapshot, and gives back any state the project
was in.
.samplekit/history/is a bare Git repository: its files are git's own, and no copy of your samples sits beside them.A snapshot is a commit. Its files are the project's at that moment,
.samplekitrc, the samples and the model's source, at the paths they have in the project; its message is the command that made it, or changed outside SampleKit; its date is when it was taken.Each computer's snapshots are a branch, named by the computer's identifier, so that
--allreads every computer's.Tags named
trace/…hold the record of which formula computed which value; nothing in your samples needs them to be read.
From the project's folder, with git installed:
$ git --git-dir=.samplekit/history log --all --format="%h %ad %s" --date=short
5452402 2026-10-06 samplekit compute --write
0d4bf40 2026-10-06 samplekit samples/steel-01.md set thickness.readings=1.991,1.994,1.989 --write
246d92a 2026-10-06 samplekit samples compute --write
e84eab2 2026-10-06 the project as SampleKit first kept it
Each line is a snapshot: its identifier, the start of the one samplekit log
gives, its day, and the command that made it. With it:
To |
Run |
|---|---|
see what a snapshot changed |
|
compare two snapshots, line by line |
|
read one file as it was |
|
get a whole snapshot back, in a folder of its own |
|
A clone holds the files of the snapshot checked out, as the project had them:
the samples, .samplekitrc and the model. Nothing in it is SampleKit's own
format. A computed value is in its sample file as SampleKit wrote it, beside
a short record of what it was computed from, which you can ignore: the
numbers are there, with their uncertainties and their units.
samplekit log --export -o HISTORY.md --write, while SampleKit runs, writes
the same account as a Markdown file anyone reads: each snapshot, its date,
its computer, the command, and the files it changed.
When a snapshot is taken¶
After each write: a command run with
--write, a change written in the TUI, a restore. Its message is the command line as you typed it, or the TUI's action.A change made outside SampleKit, in your text editor for example, is kept as a snapshot of its own, changed outside SampleKit, just before the next write. So an edit is never credited to the command that follows it.
A change to the model is a snapshot of its own before that one, the model changed, naming the formulas that changed when a computation follows (the model changed: young_modulus). The snapshot keeps the model as it was, so what an earlier version of a formula computed can be read, and computed again, from it.
A Python script's writes are one snapshot, kept when the script ends, named by its command line, with the script's source:
samplekit log --script Nprints the script as it ran.sk.keep("message")keeps what the script has written so far as a snapshot of its own. A script that writes an export or a figure file is a snapshot too; one that only prints, or only shows a figure in a window, is not.A script of the model run by
samplekit runis a snapshot named by its command, with what it asked withinput()and the answers it was given: samplekit run scale --write — answered 'Factor?' 0.5.A write that changed nothing leaves no trace.
Each command keeps its own files. Two commands writing at once, a long
compute --writeand asetin another terminal, each keep a snapshot of the files they wrote, under their own names.A write that was interrupted, the command killed or the power cut, is kept by the next write under its own name, marked interrupted. Ctrl-C during
tagorrestoreends the file being written and stops there, saying which files were written.
A snapshot that fails is a warning, and the write it follows stands: the history never stands in the way of the data.
Looking back¶
To… |
Command line |
TUI |
Python |
|---|---|---|---|
list the snapshots |
|
|
|
see what changed, value by value |
|
|
|
put files back |
|
|
|
read the project as it was |
any reading command with |
||
trace an exported file |
|
log lists the snapshots, newest first and numbered from 1: when, what
wrote, which files changed. Given a file or a folder, it lists only the
snapshots that changed it, with the same numbers. From a folder above several
projects, it lists each project's history under its name; a number is then
one project's, so --at, --from and --to name the project too, samplekit cast log --at 1 (several projects).
diff compares two states value by value, in the project's units
and precisions, not line by line: area 25.056 ± 0.053 mm² → 24.918 ± 0.028 mm². Alone,
it shows the last change kept; diff --from 1 shows what changed since the
last snapshot, such as an edit in your editor.
A state is named by now, a number from log, the start of a snapshot's id,
or a date: 2026-09-12 (the end of that day) or '2026-09-12 14:30'. A date
names the last snapshot at or before it. Tab completes them.
restore puts files back. Without --at, it takes back the last
change SampleKit wrote on your computer in what you name, value by value:
what was changed since, by hand or by a colleague whose work you pulled,
stays. Where one of those later changes touched a value that change wrote,
nothing is taken back, and restore names the value. A file you name that you
deleted, or changed outside SampleKit, comes back as it was last kept. With
--at, it puts the files back as that snapshot held them, every change since
included. Like every command that writes, it shows the change
first and asks before writing it; --write writes without asking. A restore is itself a snapshot, so it can be
taken back too.
In the TUI, u takes back the last change of the session, and once the
session's changes are all taken back, goes on with the project's history: the
last change SampleKit kept, even from yesterday, or from the command line.
The project as it was¶
--at runs a reading command over the project as a snapshot held it: its
samples, its .samplekitrc and its model then.
$ samplekit -c material,tensile_strength --at 2026-10-06
$ samplekit export paper --at 3 -o results-then.tex --write
$ samplekit samples/steel-01.md explain area --at 3
Your project is not changed: what the command writes goes where -o says.
An export made again this way is the same file, byte for byte. A figure is
drawn from the same data, settings and model, and with the same matplotlib
it is the same file too; matplotlib itself may have changed since, so it can
differ in small ways. Commands that change the
project (set, new, tag, remove, rename, compute, run, init)
refuse --at.
Where a file came from¶
An export, a table written with -o, or a figure written to a file is
recorded in the history when it is written: what wrote it, when, where,
and from which samples. The file itself is not kept, only a digest of its
exact content. So samplekit explain finds it again, even copied into a
manuscript's folder and renamed:
$ samplekit ../paper/figure-3.pdf explain
../paper/figure-3.pdf is kept by the project in .
../paper/figure-3.pdf
made 2026-10-06 20:36, by samplekit plot curves -o curves.pdf --write
written curves.pdf
from snapshot #3, 3 samples
since then
samples/steel-01.md
curve.force[24] 11.07 kN → 11.2 kN
curve.stress[24] 441.8 MPa → 447.0 MPa
it is not current — samplekit plot curves -o curves.pdf --write makes it again
made again as it was, from the project's folder: samplekit plot curves -o curves.pdf --write --at 388c00c
It says what changed since in what the file was made from, and so whether the
file is still current, and gives the command that makes it again, as it was
(--at) or as the project is now. A file changed since, cropped or converted,
no longer matches its digest; a figure also carries its snapshot's number in
its metadata, which survives some of these changes. A figure saved from
matplotlib's window was not written by SampleKit, and is not recorded.
A folder made a project¶
A project keeps the history of the files it holds itself: a folder below it
with a .samplekitrc of its own is a project of its own, with its own
history. The snapshots the project above took of that folder's files, from
before it was a project, come with it: the first command that reaches the
folder (a read, a write, log, the TUI opening it, a script saving there)
copies them into its history and says so. Here samples/aluminium was given a
.samplekitrc of its own:
$ samplekit samples/aluminium log
3 snapshots of samples/aluminium brought from the history of ., a project of its own now
# when what changed
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1 2026-10-06 20:37 the folder made a project of its own .samplekitrc, @model/specimen.py
2 2026-10-06 20:37 samplekit samples/aluminium/aluminium-01.md set grade=6082-T6 --write aluminium-01
3 2026-10-06 20:37 samplekit samples/aluminium/aluminium-01.md tag add reference --write aluminium-01
4 2026-10-06 20:37 changed outside SampleKit aluminium-01
Each copy keeps its date, its message and its computer, and holds that
folder's files alone; one more snapshot, the folder made a project of its
own, keeps its configuration as it now is. The project above keeps them all,
and shows none of them any more: samplekit samples/aluminium log reads them.
Nothing is asked, and nothing above is rewritten, so that no other computer's
history, no --at and no record of a file written changes. A command run
from the project above that changes samples of the one below is kept in the
history of the one below.
Several machines¶
A project you work on from two computers, or with a colleague, keeps one
history. Each computer writes its snapshots on a line of its own in
.samplekit/history/, and never writes another's.
So the history can travel with the project, by a synchronised folder
(Syncthing, a shared drive) or by git (Share a
project), without two computers ever writing
the same file of it.
SampleKit never merges samples: whatever carries your files does (git, Syncthing). It only notices when they have arrived. When your computer takes its next snapshot and your files already hold what the other computer kept, the snapshot joins the two lines. What came from the other computer is not recorded again as changed outside SampleKit. If the other computer's snapshots have arrived but its files have not yet, nothing is joined: your computer goes on writing its own line, and joins at a later snapshot.
log then lists every computer's snapshots together, newest first, with a
machine column that names the computer and says where one joined the
other. Your own computer is you:
$ samplekit log
# when machine what changed
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1 2026-10-06 20:36 you, joins ana samplekit samples/steel-01.md tag add reference --write steel-01
2 2026-10-06 20:36 ana, joins you samplekit samples/copper-01.md set grade=C10100 --write copper-01
3 2026-10-06 20:36 you samplekit samples/steel-01.md set grade=S275 --write steel-01
4 2026-10-06 19:58 you samplekit samples compute --write aluminium-01, copper-01, steel-01
5 2026-10-06 19:58 you the project as SampleKit first kept it aluminium-01, copper-01, steel-01, .samplekitrc, model/specimen.py
A history only one computer wrote has no such column. The numbers are places
in the list: a snapshot arriving from the other computer takes its place by
date and moves the numbers below it, as every new snapshot does. The start of
a snapshot's id never moves; use it when a number might have. diff,
restore and --at read every computer's snapshots. Undo (u in the
TUI) and restore without --at take back only a change made on your
computer; take back another computer's with restore --at.
Each computer is told apart by an identifier SampleKit draws the first
time it writes, and keeps in its own state folder (~/.local/state/samplekit/
on Linux), so that two computers set up from one disk image, which share a
host name, keep two lines. Another computer is shown by its host name
(toms-macbook for Toms-MacBook.local), or by the name you give it in the
TUI's history (H), which asks when a computer it does not know yet has
written: that name stays on your computer. SAMPLEKIT_MACHINE, if you set it,
is used instead of the identifier and of the host name. A line rc.1 kept
under your host's name is shown as another computer's, by that name, and
your next write joins it (Upgrade); nothing in the
history is rewritten.
To give an account of the history to someone without SampleKit, samplekit log --export writes it as readable Markdown: each snapshot with its date, its
computer by host name, what wrote it, the files it changed, and the script that made it.
Common mistakes¶
Expecting a history in a folder without
.samplekitrc. Make it a project first (samplekit init).Expecting photos or exports to be restored. They are not kept; exports can be made again with
--at.Treating the history as a backup. It sits beside your samples, on the same disk. Back up the whole folder,
.samplekit/included, as you would anything else.Expecting a join before the files arrive. A join waits until your files hold what the other computer kept; until then,
loglists its snapshots, but your computer does not build on them.Changing the history's folder by hand. Let git or the synchroniser carry it whole; never merge or edit its files.
Where to go next¶
Practised on the home page.
log,diff,restore,explain,--at: Command line reference; the TUI's history screen: TUI reference.