[Monotone-devel] xmtn: Emacs integration via DVC

[Christian Ohler]

DVC, an Emacs package that provides a generic interface to distributed
version control systems, now has a monotone backend.  This backend is
called xmtn.

See http://download.gna.org/dvc/ for additional information on DVC.
Mailing lists can be found at http://gna.org/projects/dvc .

Much of DVC's documentation applies only to the tla/baz/bzr backends, so
please refer to docs/xmtn-readme.txt (in the DVC distribution) instead.

(xmtn hasn't been tested with monotone 0.34 yet.)


Why another Emacs integration package?

monotone.el works OK (except for some annoying window flashing, which
isn't hard to fix), but is too simplistic to be worth extending much.
It has few features beyond what the DVC core provides for free once the
DVC backend API is implemented.

e-monotone seems to be an experiment with displaying graphviz revision
graphs in Emacs.  It accesses the db directly, which makes it hard to
maintain.  Like monotone.el, it didn't seem to be useful as a starting
point for DVC integration.

Both lack essential infrastructure like a basic_io parser and an
interface to automate.


xmtn is more heavyweight than monotone.el but provides a better
foundation for implementing features that are more sophisticated.

For a partial list of features, see the excerpt from xmtn-readme.txt below.

Enjoy.
Christian.



* General

xmtn is an Emacs Lisp package that provides a DVC backend for monotone
(the distributed version control system) as well as general facilities
for interacting with monotone from Emacs Lisp.

For more information about monotone, see http://monotone.ca/ .

xmtn's facilities for interacting with monotone are meant to be
reusable by code that is unrelated to DVC, even though they currently
depend on the subprocess handling utilities that DVC provides.



* Download and installation

Follow the download and installation instructions for DVC.  xmtn is
part of DVC.

In addition, the variable `xmtn-executable' needs to point to the
monotone executable.  It defaults to "mtn", which will be sufficient
if mtn is in your PATH.  Depending on your configuration, the PATH
that Emacs sees can differ from the PATH that you see in your shell.
Try M-x getenv RET PATH RET if in doubt.

You may wish to set `dvc-debug' to nil; DVC tends to be a bit chatty.



* Brief tutorial

(DVC's tutorial does not apply to xmtn, it seems to be specific to
tla.)

Start Emacs.  Visit a file that is under version control by monotone.
Modify the file.  While in the file's buffer, press C-x V d to see the
diff for this file.

Pressing C-x V = will bring up the tree diff buffer.  (What monotone
calls a "workspace" is called a "tree" in DVC.)  This buffer shows the
list of all modified files in the tree as well as the diffs for those
files.  Use j to jump back and forth between the name of a file in the
list and the diffs for that file.  Use RET with point inside a diff
hunk to go to the corresponding file at the corresponding position.

Like many other DVC buffers, the contents of the tree diff buffer can
be refreshed using g.

In the tree diff buffer, files to commit can be marked and unmarked
with m and u.  Pressing c lets you commit the selected files; it will
bring up a log edit buffer where you can enter a commit message.

In the log edit buffer, the commit can be executed by pressing C-c
C-c.  To abort the commit, simply don't press C-c C-c -- just switch
away from the buffer or kill it.  The log edit buffer edits the file
_MTN/log.

To bring up the log edit buffer without going through the tree diff
buffer, use C-x V c.

To view the revision history, use C-x V l or C-x V L.  The former
shows the full commit message for each revision, while the latter only
shows the first line.  The resulting buffer is a so-called revlist
buffer.  In revlist buffers, use cursor up/down to move between
revisions, RET to show details on the revision at point, = to show its
diff from its parent.  Revisions can be marked and unmarked with m and
u.

M-x xmtn-view-heads-revlist shows a revlist buffer with just the heads
of the default branch of your tree.  To update your tree to one of the
revisions in a revlist buffer, move point to it and use M-x
xmtn-revlist-update.  To merge two head revisions, mark them and use
M-x xmtn-revlist-explicit-merge.

M-x xmtn-view-revlist-for-selector prompts for a monotone selector and
shows a revlist buffer with all matching revisions.

C-x V u performs mtn update.  C-x V m shows a revlist buffer with the
revisions that mtn update would apply to your tree.

C-x V f a performs mtn add.  M-x dvc-ignore-files and M-x
dvc-ignore-file-extensions can be used to add entries to .mt-ignore.
These commands can also be used from dired buffers.

C-x V s shows the status buffer.  This currently shows modified,
renamed and unknown files.  I don't use it much, C-x V = seems
preferable.

C-x V a can be used to add a ChangeLog entry to _MTN/log.

There are other useful operations, but these should be enough to get
started.