[Monotone-devel] pretty pretty pictures (for some value of pretty)

[Nathaniel Smith]

So Jack Cummings asked on IRC yesterday about tools for drawing ASCII
revision graphs, and I, of course, said that I just type them by hand
(practice helps), but it got me thinking, and...
   http://frances.vorpus.org/~njs/nvm-heights.txt

That's net.venge.monotone plus all merged-in branches, generated by
a little python script which has been checked into mainline as
contrib/asciik.py.  The ordering is the same as log, i.e., the newest
revisions are at the top.  The algorithm used is very very stupid,
which is a feature -- the python script takes ~1/2 a second to
generate that file, and the output is fully incremental, you don't
have to wait for it to think before it outputs the first line (cf.
graphviz).

Despite that, the layout is really quite plausible looking.  It also
has the nice property that while by default it puts a node every other
line, it is very easy to stretch that space arbitrarily without
disrupting the layout.  This means that we can easily put arbitrary
annotations for each node on the right.

What would you think if the next time you ran "mtn log" you got
something like (using some fictionalized history from "chryn", an
async IO library):

*   more notes on DNS stuff (address@hidden)
|       8517a0622bbe in org.vorpus.chryn
*   merge in async resolver (address@hidden)
|\      62c1ff933236 in org.vorpus.chryn
* | build into a .a file (address@hidden)
| |     f4e48407d9de3 in org.vorpus.chryn
| o use c-ares for name resolution (address@hidden)
| |     c184f47b00090 in org.vorpus.chryn.c-ares
| o import c-ares (address@hidden)
|/      bbe06ff7eefc3 in org.vorpus.chryn.c-ares
|       tag: t:import-c-ares-1.04
*   update docs (address@hidden)
|       1835a700e6e6 in org.vorpus.chryn

?

This is assuming we adopt the convention that the first line of a
commit message is a summary of the message (monotone's history
violates this right now, oh well).  The * vs. o thing is meant to make
it obvious what is on mainline vs. what is not -- the idea being that
* is used for revisions that are in your current branch, o for
revisions that are not.

It's a little cluttered, maybe we want to put blank lines between
annotations?

*   more notes on DNS stuff (address@hidden)
|       8517a0622bbe in org.vorpus.chryn
|
*   merge in async resolver (address@hidden)
|\      62c1ff933236 in org.vorpus.chryn
| |
* | build into a .a file (address@hidden)
| |     f4e48407d9de3 in org.vorpus.chryn
| |
| o use c-ares for name resolution (address@hidden)
| |     c184f47b00090 in org.vorpus.chryn.c-ares
| |
| o import c-ares (address@hidden)
|/      bbe06ff7eefc3 in org.vorpus.chryn.c-ares
|       tag: t:import-c-ares-1.04
|
*   update docs (address@hidden)
|       1835a700e6e6 in org.vorpus.chryn

Lots of options.  Is this kind of layout useful?  It seems like an
_excellent_ way to get users "thinking in monotone", i.e., thinking
in terms of a dag-of-tree-snapshots, even if they skipped over the
"concepts" section of the manual.

I'm not sure if this is the right summary information -- anything else
that should be added?  Is showing a shorter form of log by default
the right idea?  (Presumably you could use 'mtn log --full' to get
something more like what we have today.)  Maybe the revid could be
deemphasized a bit.  Maybe keyids should be listed next to branches,
rather than next to the commit message summary?

An interesting problem is how to reduce the revision graph when that's
needed.  Restricted log, for instance, would have some trouble
showing a graph.  Same for --no-merges, and even forward log (because
the graph drawer currently assumes that every node has at most 2
successors; though I have some idea how to fix that).  It would also
be very useful to have some sort of "stay on branch" mode, that elided
or compressed any revisions that are off the branch.  (In particular,
this would help a lot with some of the really wide bits in that graph
of nvm.)  monotone-viz actually has logic to do this sort of graph
reduction; we should look at that.

If we have this kind of capability, it might be good to use it more
widely, as a conventional language for showing this sort of thing...
How about a command "mtn whereami", that shows what revision will be
created if you hit "commit" in the current workspace?  Seems like it
would be better to show this with old revisions on top, new ones on
the bottom:

$ mtn whereami
*   update docs (address@hidden)
|\      1835a700e6e6 in org.vorpus.chryn
| o import c-ares (address@hidden)
| |     bbe06ff7eefc3 in org.vorpus.chryn.c-ares
| |     tag: t:import-c-ares-1.04
| o use c-ares for name resolution (address@hidden)
| |     c184f47b00090 in org.vorpus.chryn.c-ares
* | build into a .a file (address@hidden)
|/      f4e48407d9de3 in org.vorpus.chryn
*   merge in async resolver (address@hidden)
|\      62c1ff933236 in org.vorpus.chryn
* | more notes on DNS stuff (address@hidden)
| |     8517a0622bbe in org.vorpus.chryn
o | first pass at win32 support (address@hidden)
: |     6c32d3ce72b4 in org.vorpus.chryn.win32
: |
: @ WORK IN PROGRESS, in org.vorpus.chryn

This also adds the idea of showing visually where information has been
elided, with ":" to suggest ellipsis... it would be cool to have a
convention for that in general, re-used for graph reductions, to show
that there is more history outside a window of interest (or, by
contrast, that there is not -- perhaps the bottom "o" there was a
head, we could show that graphically by leaving out the trailing
colons).

For that matter, there's no law that says that "status" may only show
changes:

$ mtn status
| o use c-ares for name resolution (address@hidden)
| |     c184f47b00090 in org.vorpus.chryn.c-ares
* | build into a .a file (address@hidden)
|/      f4e48407d9de3 in org.vorpus.chryn
*   merge in async resolver (address@hidden)
|\      62c1ff933236 in org.vorpus.chryn
* | more notes on DNS stuff (address@hidden)
: |     8517a0622bbe in org.vorpus.chryn
: |
: @ WORK IN PROGRESS, in org.vorpus.chryn:
:       patched TODO
:       patched include/chryn/address.hh
:       patched src/address.cc

Could even use it other places...

$ mtn heads -b net.venge.monotone
mtn: branch 'net.venge.monotone' has 2 heads:
: :
* :  monotone.el: Modify keymap (address@hidden
|\:      9edbe23f03c5 in net.venge.monotone
| |
| o  Merge from mainline (address@hidden)
| |      253bfd56ffb4 in 
net.venge.monotone.experiment.performance.xdelta-speedup
| |
| @  Turn static_casts back into widens (address@hidden)
|        43ed84710678 in net.venge.monotone
|                    and 
net.venge.monotone.experiment.performance.xdelta-speedup
|
@    Fix tests/basic_invocation_and_options (address@hidden)
         0907cc981030 in net.venge.monotone

-- Nathaniel

-- 
The Universe may  /  Be as large as they say
But it wouldn't be missed  /  If it didn't exist.
  -- Piet Hein