mutable-history / docs / obs-terms.rst

Terminology of the obsolete concept

Obsolete markers

The mutable concept is based on obsolete markers. Creating an obsolete marker registers a relation between an old obsoleted changeset and its newer version.

Old changesets are called precursors while their new versions are called successors. A marker always registers a single precursor and:

  • no successor: the precursor is just discarded.
  • one successor: the precursor has been rewritten
  • multiple successors: the precursor were splits in multiple changesets.

Chaining obsolete markers is allowed to rewrite a changeset that is already a successor. This is a kind of second order version control. To clarify ambiguous situations one can use direct precursors or direct successors to name changesets that are directly related.

The set of all obsolete markers forms a direct acyclic graph the same way standard parents/children relation does. In this graph we have:

any precursors:are transitive precursors of a changeset: direct precursors and precursors of precursors.
any successors:are transitive successors of a changeset: direct successors and successors of successors)

Obsolete markers may refer changesets that are not known locally. So, direct precursors of a changeset may be unknown locally. This is why we usually focus on the first known precursors of the rewritten changeset. The same apply for successors.

Changeset in any successors which are not Obsolete are called newest successors..

Note

I'm not very happy with this naming scheme and I'm looking for a better distinction between direct successors and **any successors*.

Possible changesets "type"

The following table describes names and behaviors of changesets affected by obsolete markers. The left column describes generic categories and the right columns are about sub-categories.

Note

I'm not very happy with the naming of:

  • "ok" changeset
  • latecomer
  • troublesome

Any better idea are welcome.

Command and operation name

Existing terms

Mercurial core already uses the following terms:

amend:to rewrite a changeset
graft:to copy a changeset
rebase:to move a changeset

Uncommit

Remove files from a commit (and leave them as dirty in the working directory)

The evolve extension have an uncommit command that aims to replace most rollback usage.

Fold

Collapse multiple changesets into a unique one.

The evolve extension will have a fold command.

Prune

Make a changeset obsolete without successors.

This an important operation as it should mostly replace strip.

Alternative names:

  • kill: shall has funny effects when you forget "hg" in front of hg kill.
  • obsolete: too vague, too long and too generic.

Stabilize

Automatically resolve troublesome changesets (unstable, latecomer and conflicting)

This is an important name as hg pull/push will suggest it the same way it suggest merging when you add heads.

I do not like stabilize much.

alternative names:

  • solve (too generic ?)
  • evolve (too vague)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.