Mercurial > evolve
changeset 977:cc0f0d94bf30
docs: rewrite index page (including dangling links to future docs)
This has been reviewed to death on the evolve-testers mailing list.
I've made some minor tweaks since the last round of reviews, but the
main content is the same.
author | Greg Ward <greg@gerg.ca> |
---|---|
date | Thu, 05 Jun 2014 21:57:34 -0400 |
parents | bed842762447 |
children | 8328337d23b2 |
files | docs/index.rst |
diffstat | 1 files changed, 80 insertions(+), 141 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/index.rst Fri Jun 06 17:43:45 2014 -0400 +++ b/docs/index.rst Thu Jun 05 21:57:34 2014 -0400 @@ -1,166 +1,105 @@ -.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org> -.. Logilab SA <contact@logilab.fr> - -======================================== -Changeset Evolution Experimentation -======================================== - +.. Copyright © 2014 Greg Ward <greg@gerg.ca> -This is the online documentation of the `evolve extension`_. An experimental -extension that drive the implementation of the `changeset evolution concept`_ for -Mercurial. +================================== +Changeset Evolution with Mercurial +================================== -.. _`evolve extension`: http://mercurial.selenic.com/wiki/EvolveExtension -.. _`changeset evolution concept`: http://mercurial.selenic.com/wiki/ChangesetEvolution +`evolve`_ is an experimental Mercurial extension for safe mutable history. -Here are various materials on planned improvement to Mercurial regarding -rewriting history. +.. _`evolve`: http://mercurial.selenic.com/wiki/EvolveExtension -First, read about what challenges arise while rewriting history and how we plan to -solve them once and for all. - -.. toctree:: - :maxdepth: 2 - - instability - -The effort is split in two parts: +With core Mercurial, changesets are permanent and immutable. You can +commit new changesets to modify your source code, but you cannot +modify or remove old changesets—they are carved in stone for all +eternity. - * The **obsolescence marker** concept aims to provide an alternative to ``strip`` - to get rid of changesets. This concept has been partially implemented since - Mercurial 2.3. +For years, Mercurial has included various extensions that allow +history modification: ``rebase``, ``mq``, ``histedit``, and so forth. +These are useful and popular extensions, and in fact history +modification is one of the big reasons DVCSes (distributed version +control systems) like Mercurial took off. - * The **evolve** Mercurial extension rewrites history using obsolete - *marker* under the hood. - -The first and most important step is by far the **obsolescence marker**. However -most users will never be directly exposed to the concept. For this reason -this manual starts with changeset evolution. +But there's a catch: until now, Mercurial's various mechanisms for +modifying history have been *unsafe*, in that changesets were +destroyed (“stripped”) rather than simply made invisible. -Evolve: A robust alternative to MQ -==================================== - -Evolve is an experimental history rewriting extension that uses obsolete -markers. It is inspired by MQ and pbranch but has multiple advantages over -them: - -* Focus on your current work. +``evolve`` makes things better in a couple of ways: - You can focus your work on a single changeset and take care of adapting - descendent changesets later. - -* Handle **non-linear history with branches and merges** + * It changes the behaviour of most existing history modification + extensions (``rebase``, ``histedit``, etc.) so they use a safer + mechanism (*changeset obsolescence*, covered below) rather than + the older, less safe *strip* operation. -* Rely internally on Mercurial's **robust merge** mechanism. + * It provides a new way of modifying history that is roughly + equivalent to ``mq`` (but much nicer and safer). - Simple conflicts are handled by real merge tools using the appropriate ancestor. - Conflicts are much rarer and much more user friendly. +It helps to understand that ``evolve`` builds on infrastructure +already in core Mercurial: -* Mutable history **fully available all the time**. - - Always use 'hg update' and forget about (un)applying patches to access the - mutable part of your history. - - -* Use only **plain changesets** and forget about patches. Evolve will create and - exchange real changesets. Mutable history can be used in all usual operations: - pull, push, log, diff, etc. + * *Phases* (starting in Mercurial 2.1) allow you to distinguish + mutable and immutable changesets. We'll cover phases early in the + user guide, since understanding phases is essential to + understanding ``evolve``. -* Allow **sharing and collaboration** mutable history without fear of duplicates - (thanks to obsolete marker). - -* Cover all MQ usage but guard. - -.. warning:: The evolve extension and obsolete markers are at an experimental - stage. While using obsolete you willl likely be exposed to complex - implications of the **obsolete marker** concept. I do not recommend - non-power users to test this at this stage. + * *Changeset obsolescence* (starting in Mercurial 2.3) is how + Mercurial knows how history has been modified, specifically when + one changeset replaces another. In the obsolescence model, a + changeset is neither removed nor modified, but is instead marked + *obsolete* and typically replaced by a *successor*. Obsolete + changesets usually become *hidden* as well. Obsolescence is an + invisible feature until you start using ``evolve``, so we'll cover + it in the user guide too. - While numbered 1.0.0, the command line API of this version should - **not** be regarded as *stable*: command behavior, name and - options may change in future releases or once integrated into - Mercurial. It is still an immature extension; a lot of - features are still missing but there is low risk of - repository corruption. - - Production-ready version should hide such details from normal users. +Some of the things you can do with ``evolve`` are: -The evolve extension requires Mercurial 2.5 (older versions supports down to 2.2) - -To enable the evolve extension use:: - - $ hg clone https://bitbucket.org/marmoute/mutable-history -u stable - $ echo '[extensions]\nevolve=$PWD/mutable-history/hgext/evolve.py' >> ~/.hgrc - -You will probably want to use hgview_ to visualize obsolescence. Version 1.7.1 -or later is required. - -.. _hgview: http://www.logilab.org/project/hgview/ + * Fix a mistake immediately: “Oops! I just committed a changeset + with a syntax error—I'll fix that and amend the changeset so no + one sees my mistake.” (While this is possible using existing + features of core Mercurial, ``evolve`` makes it safer.) - - --- - -For more information see the documents below: - -.. toctree:: - :maxdepth: 1 + * Fix a mistake a little bit later: “Oops! I broke the tests three + commits back, but only noticed it now—I'll just update back to the + bad changeset, fix my mistake, amend the changeset, and evolve + history to update the affected changesets.” - tutorials/tutorial - evolve-good-practice - evolve-faq - from-mq - evolve-collaboration - qsync + * Remove unwanted changes: “I hacked in some debug output two + commits back; everything is working now, so I'll just prune that + unwanted changeset and evolve history before pushing.” -Smart changeset deletion: Obsolete Marker -========================================== - -The obsolete marker is a powerful concept that allows Mercurial to safely handle -history rewriting operations. It is a new type of relation between Mercurial -changesets that tracks the result of history rewriting operations. + * Share mutable history with yourself: say you do most of your + programming work locally, but need to test on a big remote server + somewhere before you know everything is good. You can use + ``evolve`` to share mutable history between two computers, pushing + finely polished changesets to a public repository only after + testing on the test server. -This concept is simple to define and provides a very solid base for: - -- very fast history rewriting operations - -- auditable and reversible history rewriting process - -- clean final history - -- share and collaborate on mutable parts of the history + * Share mutable history for code review: you don't want to publish + unreviewed changesets, but you can't block every commit waiting + for code review. The solution is to share mutable history with + your reviewer, amending each changeset until it passes review. -- gracefully handle history rewriting conflicts - -- allow various history rewriting UI to collaborate with a underlying common API +``evolve`` is experimental! +--------------------------- - --- +TODO -For more information, see the documents below - -.. toctree:: - :maxdepth: 1 + * unstable UI + * some corner cases not covered yet - obs-concept - obs-terms - obs-implementation - +Installation and setup +---------------------- -Known limitations and bugs -================================= - -Here is a list of known issues that will be fixed later: - +TODO -* You need to provide to `graft --continue -O` if you started you - graft using `-O`. - - you to manually specify target all the time. - -* Trying to exchange obsolete marker with a static http repo will crash. +Next steps: + * For a practical guide to using ``evolve`` in a single repository, + see the `user guide`_ (coming soon). + * For more advanced tricks, see `sharing mutable history`_ (coming soon). + * To learn about the concepts underlying ``evolve``, see `concepts`_ + (coming soon). + * If you're coming from MQ, see the `MQ migration guide`_ (incomplete). -* Extinct changesets are hidden using the *hidden* feature of mercurial only - supported by a few commands. - - Only ``hg log``, ``hgview`` and `hg glog` support it. Neither ``hg heads`` nor other visual viewers do. - -* hg heads shows extinct changesets. +.. _`user guide`: user-guide.html +.. _`concepts`: concepts.html +.. _`sharing mutable history`: sharing.html +.. _`MQ migration guide`: from-mq.html