diff -r 0892b91947ef -r abe52cf492ee docs/evolve-faq.rst --- 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 ``. +.. [#] `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 `` to add obsolete +You can use ``hg kill --new `` 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. - - - -