Mercurial > evolve
view docs/obs-terms.rst @ 1106:6b0cf1b73693 stable
evolve: replace each obsolete sha1 in the description with its latest successor
Obsolete csets are hidden by default and don't get pushed to the parent repo.
In order to avoid broken references in commit messages, it makes sense to evolve
those references to the latest and greatest successor, as each cset containing
them is evolved. Of course, stale references can still occur if a commit in
branch 'A' references something in branch 'B', and that something in 'B' is
evolved but 'A' isn't subsequently evolved.
This alleviates the user that is evolving a series of commits from having to
1) recognize that there is a hash that needs updating in any one of the series
2) look up the latest successor manually
3) hg amend -e
The regular expression for matching and the logic for replacing are borrowed
from the convert extension [1].
It might be nice for the output to state the reason that the reference couldn't
be updated (it was pruned, split or diverged), but that may be excessive for
something only displayed in verbose mode. (Maybe it should be a ui.status()
instead?)
[1] http://selenic.com/hg/rev/45562379ce4e
| author | Matt Harbison <matt_harbison@yahoo.com> |
|---|---|
| date | Sat, 09 Aug 2014 19:12:16 -0400 |
| parents | 26f76b38f879 |
| children | 6f2c1574eda8 |
line wrap: on
line source
.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org> .. Logilab SA <contact@logilab.fr> ----------------------------------------------------------- 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. .. The *precursors* and *successors* terms can be used on changeset directy: .. :precursors: of a changeset `A` are changesets used as *precursors* by .. obsolete marker using changeset `A` as *successors* .. :successors: of a changeset `B` are changesets used as *successors* by .. obsolete marker using changeset `B` as *precursors* 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. +---------------------+--------------------------+-----------------------------+ | **mutable** | **obsolete** | **extinct** | | | | | | Changeset in either | Obsolete changeset is | *extinct* changeset is | | *draft* or *secret* | *mutable* used as a | *obsolete* which has only | | phase. | *precursor*. | *obsolete* descendants. | | | | | | | A changeset is used as | They can safely be: | | | a *precursor* when at | | | | least one obsolete | - hidden in the UI, | | | marker refers to it | - silently excluded from | | | as precursors. | pull and push operations | | | | - mostly ignored | | | | - garbage collected | | | | | | | +-----------------------------+ | | | | | | | **suspended** | | | | | | | | *suspended* changeset is | | | | *obsolete* with at least | | | | one non-obsolete descendant | | | | | | | | Thoses descendants prevent | | | | properties of extincts | | | | changesets to apply. But | | | | they will refuse to be | | | | pushed without --force. | | | | | | +--------------------------+-----------------------------+ | | | | | | **troubled** | **unstable** | | | | | | | *troubled* has | *unstable* is a changeset | | | unresolved issue caused | with obsolete ancestors. | | | by *obsolete* relations. | | | | | | | | Possible issues are | It must be rebased on a | | | listed in the next | non *troubled* base to | | | column. It is possible | solve the problem. | | | for *troubled* | | | | changeset to combine | (possible alternative name: | | | multiple issue at once. | precarious) | | | (a.k.a. divergent and | | | | unstable) +-----------------------------+ | | | | | | (possible alternative | **bumped** | | | names: unsettled, | | | | troublesome | *bumped* is a changeset | | | | that tries to be successor | | | | of public changesets. | | | | | | | | Public changeset can't | | | | be deleted and replace | | | | *bumped* | | | | need to be converted into | | | | an overlay to this public | | | | changeset. | | | | | | | | (possible alternative names:| | | | mislead, naive, unaware, | | | | mindless, disenchanting) | | | | | | | +-----------------------------+ | | | **divergent** | | | | | | | | *divergent* is changeset | | | | that appears when multiple | | | | changesets are successors | | | | of the same precursor. | | | | | | | | *divergent* are solved | | | | through a three ways merge | | | | between the two | | | | *divergent* , | | | | using the last "obsolete- | | | | -common-ancestor" as the | | | | base. | | | | | | | | (*splitting* is | | | | properly not detected as a | | | | conflict) | | | | | | | | (possible alternative names:| | | | clashing, rival, concurent, | | | | conflicting) | | | | | | +--------------------------+-----------------------------+ | | | | | Mutable changesets which are neither *obsolete* or | | | *troubled* are *"ok"*. | | | | | | Do we really need a name for it ? *"ok"* is a pretty | | | crappy name :-/ other possibilities are: | | | | | | - stable (confusing with stable branch) | | | - sane | | | - healthy | | | | +---------------------+--------------------------------------------------------+ | | | **immutable** | | | | Changesets in the *public* phases. | | | | Rewriting operation refuse to work on immutable changeset. | | | | Obsolete markers that refer an immutable changeset as precursors have | | no effect on the precussors but may have effect on the successors. | | | | When a *mutable* changeset becomes *immutable* (changing its phase from draft| | to public) it is just *immutable* and loose any property of it's former | | state. | | | | The phase properties says that public changesets stay as *immutable* forever.| | | +------------------------------------------------------------------------------+ 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. evolve ``````````````` Automatically resolve *troublesome* changesets (*unstable*, *bumped* and *divergent*) This is an important name as hg pull/push will suggest it the same way it suggest merging when you add heads. alternative names: - solve (too generic ?) - stabilize