|
Size: 5287
Comment: improved grammar
|
Size: 4990
Comment: big rework
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| = Changesets Evolution Concept = | = Changesets Evolution = |
| Line 7: | Line 7: |
| /!\ this feature is experimental and only partially implement in core Changesets evolution allows for safe rewriting of Mercurial history. This has a close relationship with [[Phases]] * Presentation of the concept: http://hg-lab.logilab.org/doc/mutable-history/html/ * Related experimental extension (usable): http://bitbucket.org/marmoute/mutable-history/overview == Core principle == * Store an explicit obsolescence marker between new and old version of rewritten changeset. * This marker is *not* part of the changeset (should not alter the hash). * People are able to collaborate on evolving changeset == Additional idea == * Store final delta in a real and autonomous changeset. * The Obsolescence markers are exchangeable without rewritten changeset. * Easily allow other extension to manipulate such relation (and to hook on such operation) == handled situation == * Rewriting content of a changeset, * delete/kill a changeset. * split a single changeset into multiple ones, * collapse multiple changeset into a single one, * change changeset order, * adding (eg pulling) a changeset evolution that conflicts with another one. * adding (or adding in general ) new changesets on one which already evolved (or evolving a changeset that have descendant) |
Changeset Evolution is a set of feature to gracefully handle history rewriting operation. It offers a **safe** and **simple** way to refines changesets. Results of your local history rewriting operations can be propagated to other clone in a *solid* way. It is even possible for multiple people to rewrite the same part of the history in a distributed way. |
| Line 38: | Line 14: |
| == Changeset Obsolescence == | /!\ The changeset evolution concept is still being implemented. Most of it is disabled by default. == Rewriting history == Mercurial offers multiple commands to rewrite history hg commit --amend:: can adds more changes into a commit hg rebase:: can move changesets around in your graph (requires the RebaseExtension) hg histedit:: can performs rewrite operation on some of your changesets (require the HisteditExtension) The Experimental EvolveExtension adds more commands that will eventualy moved into core hg uncommit:: can removes changes from a commit a put them back in your working directory hg fold:: can squash multiple change set together as a single new commit hg prune:: can removes changesets from your history. All those operations are **very safe to use**, even for Mercurial rookies. Mercurial will actively prevent you to rewrite part of the history which are not safe to rewrite. Reads about [[Phases]] concept for details. == Tracking and sharing rewriting == |
| Line 48: | Line 45: |
| :hg:`hg phases` for details). | `hg phases` for details). |
| Line 50: | Line 47: |
| Obsolescence is tracked using "obsolete markers", a piece of metadata tracking which changesets have been made obsolete, potential successors for |
Obsolescence is tracked using "obsolescence markers", a piece of metadata that tracks which changesets have been made obsolete, potential successors for |
| Line 63: | Line 60: |
| == Current feature status == | == Automatic detection and resolution arising troubles == |
| Line 65: | Line 62: |
| This feature is still at an early stage of development. While several core behaviors have been adjusted to take obsolescence markers into account, some parts of Mercurial are still unaware of the new concept. |
Exchanging mutable changesets an inherent *troubles* that we must be prepare to deal with. Most people will never run into them but Mercurial is able to detect and solve them automatically. |
| Line 69: | Line 66: |
| We do not recommend using this feature with version 2.4 of Mercurial unless you are an experienced user aware of the limitation of the current implementation. == State of the concept in version 2.4 == Commit --amend, rebase and histedit can now create obsolescence marker instead of stripping. This behavior is disable by default. You need to explicitly enable Obsolescence support to get this behavior. Some part of Mercurial comply with obsolescence marker, enforcing behavior as outlined below: Changesets marked as obsolete are: * hidden from log, * excluded from push, pull, clone, * selected by the 'obsolete()' revset. |
There is three kind of **troubled changesets** |
| Line 86: | Line 69: |
| obsolete changesets. Such changesets are said to be "unstable": | obsolete changesets. Such changesets are said to be "unstable". |
| Line 88: | Line 71: |
| * push will refuse to push them without --force, * the 'unstable()' revset will select them, * their obsolete ancestors are displayed by log. |
In some other situation you may have successors for changesets which are now [[immutable||Phases]]. In such case the obsolescence marker does not apply and the unlucky successors are said to be "bumped". |
| Line 92: | Line 73: |
| In some other situation you may have successors for changeset who are now [[immutable||Phases]]. In such case the obsolescence marker does not apply and the unlucky successors are said to be "bumped": | Finally when multiple changesets claim to be the successors of changesets they are said "divergent". |
| Line 94: | Line 75: |
| * push will refuse to push them without --force, * the 'bumped()' revset will select them, |
When Mercurial detect such *troubles* it will warn the user and prevent push by default. You can use the ``hg evolve`` command to automatically resolve them. |
| Line 97: | Line 77: |
| This command is partially implemented in the EvolveExtension. | |
| Line 98: | Line 79: |
| Obsolete changesets with no non-obsolete descendants are said to be "extinct" and will appear when querying the "extinct()" revset. |
== Current implementation state (Mercurial 2.5.1) == Most history rewritting commands can now create obsolescences markers instead of stripping. * commit --amend, * rebase * histedit This behavior is disabled by default. You need to explicitly enable obsolescence support using EvolveExtension to get this behavior. When using obsolescence markers, thoses commandes are allowed to rewrite an arbitrary part of the history leaving untouched descendant behind as unstable. log --graph will display use 'x' instead of 'o' to display obsolete changesets. Obsolete changesets with no non-obsolete descendants are said to be "extinct" and are hidden to all mercurial commands and changesets exchanged. a `--hidden` switch is added globally to have them accessible again. |
| Line 105: | Line 101: |
| log --graph will display use 'x' instead of 'o' to display obsolete changesets. Successors of a changeset are seen as valid destination for bookmarks. == Experimental use == /!\ This feature is experimental! Do not try it unless you are an experienced Mercurial user. A set of extension experimenting around the obsolescence concept is provided by Logilab. It has prototype implementation for most of the final feature. See its documentation for details: http://hg-lab.logilab.org/doc/mutable-history/html/ |
Successors of a changeset are seen as valid destinations for bookmarks. |
| Line 119: | Line 105: |
| * Initial presentation at Copenhagen: http://public.octopoid.net/talk.pdf * First tutorial, written by Peter Arrenbrecht: http://arrenbrecht.ch/mercurial/evolution/ |
* Initial presentation at Copenhagen: http://public.octopoid.net/talk.pdf * First tutorial, written by Peter Arrenbrecht: http://arrenbrecht.ch/mercurial/evolution/ |
Changesets Evolution
Contents
Changeset Evolution is a set of feature to gracefully handle history rewriting operation. It offers a **safe** and **simple** way to refines changesets. Results of your local history rewriting operations can be propagated to other clone in a *solid* way. It is even possible for multiple people to rewrite the same part of the history in a distributed way.
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
The changeset evolution concept is still being implemented. Most of it is disabled by default.
1. Rewriting history
Mercurial offers multiple commands to rewrite history
hg commit --amend:: can adds more changes into a commit hg rebase:: can move changesets around in your graph (requires the RebaseExtension) hg histedit:: can performs rewrite operation on some of your changesets (require the HisteditExtension)
The Experimental EvolveExtension adds more commands that will eventualy moved into core
hg uncommit:: can removes changes from a commit a put them back in your working directory hg fold:: can squash multiple change set together as a single new commit hg prune:: can removes changesets from your history.
All those operations are **very safe to use**, even for Mercurial rookies. Mercurial will actively prevent you to rewrite part of the history which are not safe to rewrite. Reads about Phases concept for details.
2. Tracking and sharing rewriting
Obsolescence markers make it possible to mark changesets that have been deleted or superseded in a new version of the changeset.
Unlike the previous way of handling such changes, by stripping the old changesets from the repository, obsolescence markers can be propagated between repositories. This allows for a safe and simple way of exchanging mutable history and altering it after the fact. Changeset phases are respected, such that only draft and secret changesets can be altered (see hg phases for details).
Obsolescence is tracked using "obsolescence markers", a piece of metadata that tracks which changesets have been made obsolete, potential successors for a given changeset, the moment the changeset was marked as obsolete, and the user who performed the rewriting operation. The markers are stored separately from standard changeset data can be exchanged without any of the precursor changesets, preventing unnecessary exchange of obsolescence data.
The complete set of obsolescence markers describes a history of changeset modifications that is orthogonal to the repository history of file modifications. This changeset history allows for detection and automatic resolution of edge cases arising from multiple users rewriting the same part of history concurrently.
3. Automatic detection and resolution arising troubles
Exchanging mutable changesets an inherent *troubles* that we must be prepare to deal with. Most people will never run into them but Mercurial is able to detect and solve them automatically.
There is three kind of **troubled changesets**
In some situation you may have non-obsolete changesets descending from obsolete changesets. Such changesets are said to be "unstable".
In some other situation you may have successors for changesets which are now immutable. In such case the obsolescence marker does not apply and the unlucky successors are said to be "bumped".
Finally when multiple changesets claim to be the successors of changesets they are said "divergent".
When Mercurial detect such *troubles* it will warn the user and prevent push by default. You can use the hg evolve command to automatically resolve them.
This command is partially implemented in the EvolveExtension.
4. Current implementation state (Mercurial 2.5.1)
Most history rewritting commands can now create obsolescences markers instead of stripping.
- commit --amend,
- rebase
- histedit
This behavior is disabled by default. You need to explicitly enable obsolescence support using EvolveExtension to get this behavior. When using obsolescence markers, thoses commandes are allowed to rewrite an arbitrary part of the history leaving untouched descendant behind as unstable.
log --graph will display use 'x' instead of 'o' to display obsolete changesets.
Obsolete changesets with no non-obsolete descendants are said to be "extinct" and are hidden to all mercurial commands and changesets exchanged. a --hidden switch is added globally to have them accessible again.
Obsolescence markers will be exchanged between repositories that explicitly assert support for the obsolescence feature (this can currently only be done via an extension).
Successors of a changeset are seen as valid destinations for bookmarks.
5. Older materials
* Initial presentation at Copenhagen: http://public.octopoid.net/talk.pdf * First tutorial, written by Peter Arrenbrecht: http://arrenbrecht.ch/mercurial/evolution/