Words used here

spicemine is for people who version code and for people who version everything else - drafts, layers, takes, masters. Those two groups do not share a vocabulary, so every term on these pages carries an (i): hover it, or tap it, and it explains itself. Here they all are at once.

The engines, explained

repository

One project and its entire history: every version of every file, with who changed what and why. Not a folder of latest files - a folder remembers only now. A repository remembers the manuscript before the edit, the photograph before the crop, and lets you stand in either moment.

commit

One saved moment in a repository's history, with a note saying what changed. Fossil calls it a check-in. Committing is not the same as saving a file: you save often and commit when the work has reached a state you might want to come back to.

clone

Your own complete copy of a repository, history and all, taken from here onto your machine. Every one of these engines is distributed, which means your clone is not a checkout of ours - it is a whole repository, and it keeps working when this server does not.

push

Sending commits from your clone back to here, so other people - and the next machine you sit at - can see them. Pushing needs a token, never your browser session: the two are kept apart so that a stolen cookie cannot change anyone's work.

branch

A line of history that leaves the main one and may later rejoin it. It is how two versions of the same thing exist at once without either being lost: the cut you are trying and the cut you have agreed on, both real, both kept.

timeline

The list of recent commits on a repository's page: when, who, what, and the revision each one is. It is the fastest way to see whether a repository is alive and what it has been doing.

revision

The name of one exact commit - a long string of letters and digits, shown shortened. It is derived from the content itself, so it cannot be reassigned: quote a revision and you have named one unambiguous state of the work, for as long as the repository exists.

space

Where repositories live, and who may touch them. Everyone gets one named after themselves the moment they sign up; a second kind belongs to a group instead, can have members, and outlives any one person's involvement. They are the same shape, so a solo project becomes a team project by adding a member rather than by moving.

member

Somebody a space has added, in one of three roles. A member reads every repository in the space that is not private - members only included. A writer also pushes, creates repositories and writes on private ones. An admin also adds and removes people and changes who can see a repository. Everyone is the admin of the space named after them.

visibility

Who can see a repository. Private: only the writers and admins of its space. Members only: anyone can find it in its space and read its showcase - the title, the description, the public journal posts - and the files, history and clone address are for members of the space. Public: anyone at all, everything. New repositories are private, because a store that holds unreleased work should not be the kind of place where something escapes by accident. What you may not see is not listed at all - not greyed out, not refused.

showcase

A repository's front page: the project in its own words - a title, a byline, a line or two, an image, its journal - written by its writers rather than taken from its files. Everyone who can see the repository sees it. For a members-only repository it is the whole of what somebody outside the space sees.

engine

The version control system that actually keeps a repository: fossil, git, hg, jj or lore. spicemine hosts them rather than replacing them, so your own tools talk to the real thing and nothing here is a dialect you would have to learn.

session

What signs this browser into these pages, held in a cookie that no page script can read. It expires after thirty days of being unused, it is listed in your settings with the device it belongs to, and you can end any of them - including this one - from there. A session can read and change your account; it can never push.

token

A long secret string that signs a program - a command line, an editor, a phone app - into the API and into clone and push over HTTPS. You name each one after the device that will hold it, so when a laptop goes missing you revoke that one thing and nothing else. It is shown once, because only a hash of it is kept here.

scope

What a token may reach, written on the token when it is made: one repository (repo:space/name) or one whole space (space:name), each with a verb, read or write. write includes read - a token that may push may also clone - so one scope per place is enough. A scoped token can clone and push and nothing else: it cannot create or delete a repository, and it never reaches more than your own account can. A token with no scope at all is your whole account, which you have to ask for by name.

SSH key

A key pair your machine holds, whose public half you can store here. spicemine accepts, checks and lists them, and uses them for nothing yet - it speaks HTTPS today. The page says so rather than taking your key and quietly ignoring it.

invite

A single-use link, good for seven days, that lets one person make an account. This instance sends no mail, so an admin mints the link and passes it along by whatever channel they already trust. It is shown once; after that only a hash of it exists here.

README

The file a repository's page shows as its front page, if there is one at the top of the default branch. Write it for the person arriving without context: what this is, who it is for, and what to do first.