Test of the hg evolve extension for easier upstreaming * Rationale Currently I rework my code extensively before I push it into upstream SVN. Some of that is inconvenient and it would be nicer to have easy to use refactoring tools.
remove html-tag.
added stronger obsolete notice.
added phases: safe amending.
polish
Test of the hg evolve extension for easier upstreaming
* Rationale
Currently I rework my code extensively before I push it into upstream SVN. Some of that is inconvenient and it would be nicer to have easy to use refactoring tools.
[[http://hg-lab.logilab.org/doc/mutable-history/html/index.html][hg evolve]] might offer that.
This test uses the mutable-hg extension in revision c70a1091e0d8 (24 changesets after 2.1.0). It will likely be obsolete, soon, since mutable-hg is currently moved into Mercurial core by Pierre-Yves David, its main developer. I hope it will be useful for you, to assess the future possibilities of Mercurial today.[fn:obsolete]
[fn:obsolete]: This is not (only) a pun on “obsolete”, the functionality at the core of evolve which allows safe, collaborative history rewriting ☺
* Tests
:PROPERTIES:
:tangle: runtests.sh
:noweb: yes
:END:
#+BEGIN_SRC sh :shebang #!/bin/sh :exports both :results output verbatim :session test-hg-evolve
# Tests for refactoring history with the evolve extension
export LANG=C # to get rid of localized strings
export PS1="$ "
rm -r testmy testother testpublic
#+END_SRC
** Init
/Initialize the repos I need for the test./
We have one public repo and 2 nonpublishing repos.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
# Initialize the test repo
hg init testpublic # a public repo
hg init testmy # my repo
hg init testother # other repo
# make the two private repos nonpublishing
for i in my other
do echo "[ui]
username = $i
[phases]
publish = False" > test${i}/.hg/hgrc
done
#+END_SRC
/note: it would be nice if we could just specify nonpublishing with the init command./
** Prepare
/Prepare the content of the repos./
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
echo "Hello World" > hello.txt
hg ci -Am "Hello World"
hg log -G
cd ..
#+END_SRC
** Amend
/Add a bad change and amend it./
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
sed -i s/World/Evoluton/ hello.txt
hg ci -m "Hello Evolution"
echo
hg log -G
cat hello.txt
# FIX this up
sed -i s/Evoluton/Evolution/ hello.txt
hg amend -m "Hello Evolution" # pass the message explicitely again to avoid having the editor pop up
echo
hg log -G
cd ..
#+END_SRC
** …together
/Add a bad change. Followed by a good change. Pull both into another repo and amend it. Do a good change in the other repo. Then amend the bad change in the original repo, pull it into the other and evolve./
*** Setup
Now we change the format to planning a roleplaying session to have a more complex task. We want to present this as coherent story on how to plan a story, so we want clean history.
First I do my own change.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
# Now we add the bad change
echo "Wishes:
- The Solek wants Action
- The Judicator wants Action
" >> plan.txt
hg ci -Am "What the players want"
# show what we did
echo
hg log -G -r tip
# and the good change
echo "Places:
- The village
- The researchers cave
" >> plan.txt
hg ci -m "The places"
echo
hg log -G -r 1:
cd ..
#+END_SRC
Now my file contains the wishes of the players as well as the places.
We pull the changes into the repo of another gamemaster with whom we plan this game.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
hg -R testother pull -u testmy
hg -R testother log -G -r 1:
#+END_SRC
/note: the revisions numbers are different because the other repo only gets those obsolete revisions which are ancestors to non-obsolete revisions. That way evolve slowly cleans out obsolete revisions from the history without breaking repositories which already have them (but giving them a clear and easy path for evolution)./
He then adds the important people:
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testother
echo "People:
- The Lost
- The Specter
" >> plan.txt
hg ci -m "The people"
echo
hg log -G -r 1:
cd ..
#+END_SRC
*** Fix my side
And I realize too late, that my estimate of the wishes of the players was wrong. So I simply amend it.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
hg up -r -2
sed -i "s/The Solek wants Action/The Solek wants emotionally intense situations/" plan.txt
hg amend -m "The wishes of the players"
hg log -G -r 1:
cd ..
#+END_SRC
Now I amended my commit, but my history does not look good, yet. Actually it looks evil, since I have 2 heads, which is not so nice. The changeset under which we just pulled away the bad change has become unstable, because its ancestor has been obsoleted, so it has no stable foothold anymore. In other DVCSs, this means that we as users have to find out what was changed and fix it ourselves.
Changeset evolution allows us to evolve our repository to get rid of dependencies on obsolete changes.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
hg evolve
hg log -G -r 1:
cd ..
#+END_SRC
Now I have nice looking history without any hassle - and without having to resort to low-level commands.
*** Be a nice neighbor
But I rewrote history. What happens if my collegue pulls this?
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
hg -R testother pull testmy
hg -R testother log -G
#+END_SRC
As you can see, he is told that his changes became unstable, since they depend on obsolete history. No need to panic: He can just evolve his repo to be state of the art again.
But the unstable change is the current working directory, so evolve does not change it. Instead it tells us, that we might want to call it with `--any`. And as it is the case with most hints in hg, that is actually the case.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
hg -R testother evolve
#+END_SRC
/note: that message might be a candidate for cleanup./
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
hg -R testother evolve --any
hg -R testother log -G -r 1:
#+END_SRC
And as you can see, everything looks nice again.
** …safely
/Publishing the changes into a public repo makes them immutable./
Now imagine, that my co-gamemaster publishes his work. Mercurial will then store that his changes were published and warn us, if we try to change them.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testother
hg up > /dev/null
echo "current phase"
hg phase .
hg push ../testpublic
echo "phase after publishing"
hg phase .
cd ..
#+END_SRC
Now trying to amend history will fail (except if we first change the phase to draft with `hg phase --force --draft .`).
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testother
hg amend -m "change published history"
# change to draft
hg phase -fd .
hg phase .
# now we could amend, but that would defeat the point of this section, so we go to public again.
hg phase -p .
cd ..
#+END_SRC
Once I pull from that repo, the revisions which are in there will also switch phase to public in my repo.
So by pushing the changes into a publishing repo, you can get the Mercurial of all contributors to track which revisions are safe to change - and which are not. An alternative is using `hg phase -p REV`.
** Fold
/Do multiple commits to create a patch, then fold them into one commit./
Now I go into a bit of a planning spree.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
echo "Scenes:" >> plan.txt
hg ci -m "we need scenes"
echo "- Lost appears" >> plan.txt
hg ci -m "scene"
echo "- People vanish" >> plan.txt
hg ci -m "scene"
echo "- Portals during dreamtime" >> plan.txt
hg ci -m "scene"
echo
hg log -G -r 9:
cd ..
#+END_SRC
Yes, I tend to do that…
But we actually only need one change, so make it one by folding the last 4 changes changes into a single commit.
Since fold needs an interactive editor (it does not take -m, yet), we will leave that out. The commented commands allow you to fold the changesets.
#+BEGIN_SRC sh :tangle no :exports both :results output verbatim :session test-hg-evolve
cd testmy
# hg fold -r "-1:-4"
# hg log -G -r 9:
cd ..
#+END_SRC
** Split
/Do one big commit, then split it into two atomic commits./
Now I apply the scenes to wishes, places and people. Which is not useful: First I should apply them to the wishes and check if all wishes are fullfilled. But while writing I forgot that, and anxious to show my co-gamemaster, I just did one big commit.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
sed -i "s/The Judicator wants Action/The Judicator wants Action - portals/" plan.txt
sed -i "s/The village/The village - lost, vanish, portals/" plan.txt
hg ci -m "Apply Scenes to people and places."
echo
hg log -G -r 12:
cd ..
#+END_SRC
Let’s fix that: uncommit it and commit it as separate changes. Normally I would just use `hg record` to interactively select changes to record. Since this is a non-interactive test, I manually undo and redo changes instead.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
hg uncommit --all # to undo all changes, not just those for specified files
hg diff
sed -i "s/The village - lost, vanish, portals/The village/" plan.txt
hg amend -m "Apply scenes to wishes"
sed -i "s/The village/The village - lost, vanish, portals/" plan.txt
hg commit -m "Apply scenes to places"
echo
hg log -G -r 12:
cd ..
#+END_SRC
** …as afterthought
/Do one big commit, add an atomic commit. Then split the big commit./
Let’s get the changes from our co-gamemaster and apply people to wishes, places and scenes. Then add a scene we need to fullfill the wishes and clean the commits afterwards.
First get the changes:
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
hg pull ../testother
hg merge --tool internal:merge tip # the new head from our co-gamemaster
# fix the conflicts
sed -i "s/<<<.*local//" plan.txt
sed -i "s/====.*/\n/" plan.txt
sed -i "s/>>>.*other//" plan.txt
# mark them as solved.
hg resolve -m
hg commit -m "merge people"
echo
hg log -G -r 12:
cd ..
#+END_SRC
Now we have all changes in our repo. We begin to apply people to wishes, places and scenes.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
sed -i "s/The Solek wants emotionally intense situations/The Solek wants emotionally intense situations | specter, Lost/" plan.txt
sed -i "s/Lost appears/Lost appears | Lost/" plan.txt
sed -i "s/People vanish/People vanish | Specter/" plan.txt
hg commit -m "apply people to wishes, places and scenes"
echo
hg log -G -r 19:
cat plan.txt
cd ..
#+END_SRC
As you can see, the specter only applies to the wishes, and we miss a person for the action.
Let’s fix that.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
sed -i "s/- The Specter/- The Specter\n- Wild Memories/" plan.txt
sed -i "s/- Portals during dreamtime/- Portals during dreamtime\n- Unconnected Memories/" plan.txt
hg ci -m "Added wild memories to fullfill the wish for action"
echo
hg log -G -r 19:
cd ..
#+END_SRC
Now split the big change into applying people first to wishes, then to places and scenes.
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
# go back to the big change
hg up -r -2
# uncommit it
hg uncommit --all
# Now rework it into two commits
sed -i "s/- Lost appears | Lost/- Lost appears/" plan.txt
sed -i "s/- People vanish | Specter/- People vanish/" plan.txt
hg amend -m "Apply people to wishes"
sed -i "s/- Lost appears/- Lost appears | Lost/" plan.txt
sed -i "s/- People vanish/- People vanish | Specter/" plan.txt
hg commit -m "Apply people to scenes"
# let’s mark this for later use
hg book splitchanges
# and evolve to get rid of the obsoletes
echo
hg evolve --any
hg log -G -r 19:
cd ..
#+END_SRC
You can see the additional commit sticking out. We want to get the history easy to follow, so we just graft the last last change atop the split changes.
/note: We seem to have the workdir on the new changeset instead of on the one we did before the evolve. I assume that’s a bug to fix./
#+BEGIN_SRC sh :exports both :results output verbatim :session test-hg-evolve
cd testmy
hg up splitchanges
hg graft -O tip
hg log -G -r 19:
cd ..
#+END_SRC
/note: We use graft here, because using a second amend would just change the changeset in between but not add another change. If there had been more changes after the single followup commit, we would simply have called evolve to fix them, because graft -O left an obsolete marker on the grafted changeset, so evolve would have seen how to change all its children./
That’s it. All that’s left is finishing plan.txt, but I’ll rather do that outside this guide :)
* Conclusion
Evolve does a pretty good job at making it convenient and safe to rework history. If you’re an early adopter, I can advise testing it yourself. Otherwise, it might be better to wait until more early adopters tested it and polished its rough edges.
/note: hg amend was subsumed into hg commit --amend, so the dedicated command will likely disappear./
/note: This guide was created by [[http://draketo.de][Arne Babenhauserheide]] with [[http://gnu.org/software/emacs][emacs]] [[http://orgmode.org][org-mode]]./