diff -r 24346b78cd99 -r 4e3f25ba5401 doc/evolve-faq.rst --- a/doc/evolve-faq.rst Wed Mar 21 11:57:03 2012 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,197 +0,0 @@ -======================================== -Introduction to the evolution extension -======================================== - -An history rewriting extension - -* Using the obsolete marker concept - -* Inspired from mq - -it is simple to enable:: - - $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/mutable-history/ - $ mutable-history/enable.sh > ~/.hgrc - - - -Quick Guide -===================================================================== - - - -Add a changeset: ``commit`` ------------------------------------------------------------- - -Just use commit as usual. - -Rewrite a changeset: ``amend`` ------------------------------------------------------------- - -A new command ``hg amend`` is added by the extension. it write a new changeset -combining working-directory parent changes and working directory parent changes. - -To understand what the result of amend will be I do use the two following -aliases [#]_:: - - # diff what amend will look likes - pdiff=diff --rev .^ - - # status what amend will look likes - pstatus=status --rev .^ - -It take various options to choose the user, the date and the branch of the -result. see ``hg help amend for detail`` - -This command can be invoqued on any mutable changeset even changeset with -children ! - - -.. note:: the amend command is very similar to mq's ``qrefresh``, a ``refresh`` - alias for amend is also available. But note that contrary to - ``qrefresh``, ``amend`` does not exclude changes on file not specified - on the command line. - - XXX add idank example - - -.. [#] (added by enable.sh) - - - -Move a changeset: ``graft`` ------------------------------------------------------------- - -the graft command introduced in 2.0 allows to "copy changes from other branches -onto the current branch" - -The graft command have been altered to be able to create an obsolete marker from -the copy result to the copy source, acting like changeset movement operation. -This is achieved using a new flag `-O` (or `old-obsolete`) [#]_. - - -XXX example - -.. warning:: when using graft --continue after conflict resolution you **MUST** - pass `-O` or `-o` flag again because they are not saved for now - - -.. [#] add this `-O` to graft instead of a dedicated command is probably - abusive. But this was very convenient for experimental purpose. - This will likely change in non experimental release. - -Delete a changeset: ``kill`` ------------------------------------------------------------- - -A new ``kill`` command allow to remove a changeset. - -Just use ``hg kill ``. - -Moving within the history: ``up`` ``gdown`` and ``gup`` ------------------------------------------------------------- - -While working on mutable part of the history you often need to move between -mutable commit. - -You just need to use standard update to work with evolve. For convenience, you -can use ``hg gup`` to move to children commit or ``hg gdown`` to move to working -directory parent commit. - -.. note:: those command only exist for the convenience of getting qpush and qpop - feeling back. - - They are - -collapse changesets: ``amend`` ------------------------------------------------------------- - -you can use amend -c to collapse multiple changeset in a single one. - -Move multiple changesets: ``rebase`` ------------------------------------------------------------- - -You can still use rebase to move whole part of the changeset graph at once. - -.. warning:: Beware that rebasing obsolete changeset will result in new - conflicting version. - -Stabilize history: ``stabilize`` ------------------------------------------------------------- - -When you rewrite changeset with children without rewriting those children you -create *unstable* changeset and *suspended obsolete* changeset - -.. warning:: ``hg stabilize`` have no --continue to use after conflict - resolution. is conflict occurs use:: - - $ hg up -C . # cancel the failed merge - $ hg stabilize -n # go get a command to execute - -.. warning:: stabilization does not handle deletion yet. - -.. warning:: obsolete currently rely on secret changeset to not exchange - obsolete and unstable changeset. - - XXX details issue here - - -Fix my history afterward: ``kill -n`` ------------------------------------------------------------- - -sometime you need to create obsolete marker by hand. This may happen when -upstream applied some of you patches for example. - -you can use ``hg kill --new `` to add obsolete -marker. - -export to mq: ``synchronize`` ------------------------------------------------------------- - -Another extension allows to export - -view change to your file ------------------------------------------------------------- - -Another extension allows to export - -view diff from the last amend ------------------------------------------------------------- - -an odiff alias have been added by enable.sh - -:: - [alias] - odiff = diff --rev 'limit(obsparents(.),1)' --rev . - -view obsolete marker ------------------------------------------------------------- - -hgview is the only viewer that support this feature. you need an experimental -version available here: - - $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/ - -Prevent my unfinished changeset to get published ------------------------------------------------------------- - -The easiest way is to set them in the private phase - -Important Note -===================================================================== - -view change to your file ------------------------------------------------------------- - -extinct changeset are hidden using the *hidden* feature of mercurial. - -only hg log and hgview support it. hg glog or other visual viewer don't. - - - - - - - - - -