--- a/docs/evolve-faq.rst Wed May 09 12:43:45 2012 +0200
+++ b/docs/evolve-faq.rst Wed May 09 13:08:46 2012 +0200
@@ -3,8 +3,6 @@
Evolve How To
---------------------------------------------------------------------
-
-
Add a changeset: ``commit``
------------------------------------------------------------
@@ -13,10 +11,9 @@
Rewrite a changeset: ``amend``
------------------------------------------------------------
-A new command ``hg amend`` is added by the extension. It writes a new
-changeset combining working-directory parent changes and parent. It
-will work on any `draft` or `secret` changeset. It will not work on
-`public` changesets.
+A dedicated command ``hg amend`` is added by the extension. It writes a new
+changeset combining working-directory parent changes and parent. It will work on
+any `draft` or `secret` changeset. It will not work on `public` changesets.
To understand what the result of amend will be I use the two following
aliases [#]_::
@@ -33,13 +30,15 @@
This command can even be invoked on changesets with children (provided
none is public) !
-.. note:: the amend command is very similar to mq's ``qrefresh``, a ``refresh``
+.. 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
+.. warning:: The `hg commit --amend` switch does **not** lay obsolete marker
+ down yet. You should always prefer the dedicated command.
.. [#] (added by enable.sh)
@@ -52,13 +51,13 @@
branches onto the current branch".
The graft command has been altered to allow the creation of an
-obsolete marker indicating both the result cset and its source
+obsolete marker between both the result cset and its source
(actually recording changeset movements).
This is achieved using a new flag `-O` (or `old-obsolete`) [#]_.
-XXX example
+XXX Need a few examples here.
.. warning:: when using graft --continue after conflict resolution you **MUST**
pass `-O` or `-o` flag again because they are not saved for now
@@ -68,13 +67,17 @@
abusive. But this was very convenient for experimental purposes.
This will likely change in non experimental release.
+
Delete a changeset: ``kill``
------------------------------------------------------------
-A new ``kill`` command allows removing a changeset.
+A new ``kill``[#]_ command allows removing a changeset.
Just use ``hg kill <some-rev>``.
+.. [#] `kill` is a terrible name. **NEVER** forget to add `hg` in front of it
+ until we find a better name.
+
Moving within the history: ``up`` ``gdown`` and ``gup``
------------------------------------------------------------
@@ -91,12 +94,16 @@
Collapse changesets: ``amend``
------------------------------------------------------------
-you can use amend -c to collapse multiple changeset in a single one.
+You can use amend -c to collapse multiple changeset in a single one.
+
+
+.. note:: This is a terrible UI. `hg collapse` should be ported to obsolete
+ marker for this purpose.
Split a changeset
-----------------------
-There is no official command to split a changeset. However is it easily achieved
+There is no official command to split a changeset [#]_ . However is it easily achieved
by manual operation::
### you want to split changeset A: 42
@@ -112,6 +119,8 @@
# current changeset (.) and previous one (.^) replace A (42)
$ hg kill --new . --new .^ 42
+.. [#] Yet
+
Update my current work in progess after a pull
----------------------------------------------
@@ -119,10 +128,14 @@
Whenever you are working on some changesets, it is more likely that a pull
will, eventually, import new changesets in your tree.
-And it is likely that you will want your work in progress changsets to be
+And it is likely that you will want your work in progress changesets to be
rebased on the top of this newly imported subtree.
-Doing so is only a matter of rebasing.
+Doing so is only a matter of rebasing. Rebase have been wrapped to lay obsolete
+marker down.
+
+
+XXX Add an example here.
@@ -131,7 +144,7 @@
You can still use rebase to move a whole segment of the changeset graph together.
-.. warning:: Beware that rebasing obsolete changesets will result in
+.. warning:: Beware that rebasing changesets already obsolete by others will result in
conflicting versions of the changesets.
Stabilize history: ``stabilize``
@@ -146,15 +159,17 @@
newest version. This is not done automatically to avoid the
proliferation of useless hidden changesets.
-.. warning:: ``hg stabilize`` have no --continue to use after conflict
+.. warning::
+
+ * ``hg stabilize`` have no --continue to use after conflict
resolution
-.. warning:: stabilization does not handle deletion yet.
+ * stabilization does not handle deletion yet.
-.. warning:: obsolete currently relies on changesets in secret phase
- to avoid exchanging obsolete and unstable changesets.
+ * stabilization does not handle rewriting conflict yet.
- XXX details issue here
+ * obsolete currently relies on changesets in secret phase
+ to avoid exchanging extinct() changesets.
Fix my history afterward: ``kill -n``
@@ -163,18 +178,17 @@
Sometimes you need to create an obsolete marker by hand. This may happen when
upstream has applied some of your patches for example.
-you can use ``hg kill --new <new-changeset> <old-changeset>`` to add obsolete
+You can use ``hg kill --new <new-changeset> <old-changeset>`` to add obsolete
marker.
-Export to mq: ``synchronize``
+Export to mq: ``qsync``
------------------------------------------------------------
-Another extension allows to export.
+Another extension allows to export mutable changeset to mq. See the
+`enable-qsync.sh` to enable it and read module documentation for details.
-View change to your file
-------------------------------------------------------------
+If you do not work at Logilab. You probably do not need it.
-Another extension allows to export.
View diff from the last amend
------------------------------------------------------------
@@ -185,6 +199,9 @@
[alias]
odiff = diff --rev 'limit(obsparents(.),1)' --rev .
+The qt viewer `hgview` displays obsolete data and allows to see diff again
+obsolete parent.
+
View obsolete markers
------------------------------------------------------------
@@ -195,22 +212,9 @@
-Important Note
-=====================================================================
-
-View change to your file
-------------------------------------------------------------
-
-Extinct changesets are hidden using the *hidden* feature of mercurial.
-
-Only ``hg log`` and ``hgview`` support it. ``hg glog`` or other visual viewer don't.
-
-
-
-