1.1 Installation

1.1.1 Dependencies

Various parts of the DVC require extra packages to be available.
Currently there are the following dependencies:

ewoc.el: a utility to maintain a view of a list of objects
in a buffer. This is essential for dvc and a version of ewoc.el
is included in the distribution until available by an stable version of
XEmacs. It is already included in GNU Emacs 21.

tree-widget.el is required for xtla-browse.el.
The CVS version of GNU Emacs includes tree-widget.el. XEmacs
users should install the latest jde package which includes
tree-widget.el.

1.1.2 MS Windows

DVC requires a POSIX shell, used to run the backends. On Unix-like
systems, /bin/sh should be good. On MS Windows, you will need
to install one. MinGW and Cygwin both work; other POSIX shells are
also available.

Both MinGW and Cygwin work better with native MS Windows Emacs if
installed to c:/ instead of c:/MinGW or
c:/Cygwin. This is because of the way they mount filesystems,
and refer to files not under a mounted directory.

For example, if Cygwin is installed at c:/Cygwin, it mounts
/ at c:/Cygwin. Then the file known to Emacs as
c:/Cygwin/bin/make.exe is known to Cygwin applications as
/bin/make.exe. Also, the file known to Emacs as
c:/Projects/my_file.text is known to Cygwin as
/cygdrive/c/Projects/my_file.text. This causes problems when
using Cygwin make with native Emacs; Emacs can't find the files make
is reporting in error messages.

However, if Cygwin is installed at c:/, then it mounts /
at c:/. Then the file known to Emacs as c:/bin/make.exe
is known to Cygwin applications as /bin/make.exe. Also, the
file known to Emacs as c:/Projects/my_file.text is known to
Cygwin as /Projects/my_file.text. The only difference is the
leading drive letter, which is unnecessary, as long as all files are
on the same drive, which is typical of MS Windows boxes these days.

MinGW has similar file naming conventions.

The Cygwin installer warns that installing Cygwin at c:/ is not
recommended. But if you read the rationale for that in the Cygwin
docs, it is because “you might have other things installed there that
conflict”. While true, that is up to you to control. For example, you
certainly cannot install both Cygwin and MinGW at c:/.

In general, a backend used by DVC should be run by invoking a Windows
executable, not a DOS batch file or other script. The Emacs variable
explicit-shell-file-name may help in resolving shell issues.

1.2.1 A tutorial guide to DVC

The following sections present a step-by-step tutorial guide to using
DVC for some common tasks: registering an archive, bookmarking an
existing project, creating your own local branch, getting a working
tree, merging patches from the main branch and committing changes to
your tree.

For the purposes of this tutorial, we will use the DVC project as an
example of a project you might like to track (humour me).

1.2.1.1 Register an tla archive

The first step in tracking a project's development is to register its
archive in your archive list. You can do this by starting the archive
browser (C-x V A) and typing a r to register a new archive.
DVC's archive location is currently
http://www-verimag.imag.fr/~moy/arch/public/, and the default
value for the archive name will be fine. Having done this, you should
now see the newly-registered archive listed.

1.2.1.2 Bookmarking a project

The normal usage of DVC is to create a bookmark for each version of a
project you are currently interested in. Much of the arch's
functionality is available from the bookmarks buffer, and it is one of
the primary entry points for DVC.

To track DVC's development, you will most likely want to add a bookmark
for its main development line. You can do this by entering the
bookmarks buffer (C-x V b) and adding a new bookmark with (a
b, or “add bookmark”). You should be prompted for a version name,
and you can use tab completion to enter
Matthieu.Moy@imag.fr--public/dvc--main--0. You can give your
bookmark any name you like.

Pressing RET on your newly-added bookmark will show you a revision
list for that version. You can use this list to browse archive logs
(RET again), view changesets (=) and various other tasks.

1.2.1.3 Creating a branch of a project and getting a project tree

Having created a bookmark for the DVC project, you are ready to create
your own branch. Again from the bookmarks buffer (C-x V b), move
the point to your bookmark for DVC and hit M T. You will be
prompted for the tag version to be created for your new branch. Put the
branch somewhere in your default archive (I put mine in
mark@dishevelled.net--2003-mst/dvc--main--0.1.) This will
create a tag of the main DVC project in your own archive and add a
bookmark for it.

Your newly-added bookmark will be marked as a “partner” of your main
DVC bookmark. This records the fact that the two projects are related
so that DVC can show you which patches from the DVC mainline are
missing from your local tree, and other useful stuff (more on this
later).

At this point, you will probably want to get a project tree for your new
branch. You can do this by moving your point to its bookmark in the
bookmark buffer, and hitting >. You will be prompted for a
directory in which to place the project tree, and the revision to get
(the default is fine in this case). Once the project tree has been
fetched, it will be automatically opened in dired.

1.2.1.4 Finding and merging missing patches

Before you start making changes, it is a good idea to see if any new
patches have been added to the mainline since you last checked. DVC is
particularly good at doing this.

Start by entering the bookmarks buffer (C-x V b), move your point
to the bookmark of your DVC branch and hit M m. A
*tla-missing* buffer should appear, and show any patches that are
in the mainline but not in your tree.

To merge all missing patches from the DVC mainline into your project
tree, move your point to the DVC mainline partner entry and hit M
s. You will be prompted for the path of your local project tree, and
after the patches have been merged a changes buffer should be displayed.

If you don't want to merge all the missing patches, you can leave off
the M prefix. For example, r will replay only the revision
under the point (allowing you to cherry-pick patches), and s will
star-merge all missing patches up to the patch under the point.

1.2.1.5 Reviewing and committing your changes

After making changes to your project tree, you are ready to commit. You
can review your changes by typing C-x V = from within your project
tree, and a *tla-changes* buffer should appear with diff output.
Before committing, you might also like to tree-lint your local tree by
hitting C-x V l (but this is done automatically if tla
changes fails and suggests a tree-lint).

Once you are satisfied with your changes, you can create a log file by
hitting C-x V c (or simply c from your *tla-changes*
buffer). Many users prefer to write their log file incrementally, and
you can always save this file and hit C-x V c to return to it
later. You can also add a ChangeLog-style entry by hitting C-x V
a from the project tree file you are currently visiting.

1.2.2 First contact

DVC is self documented, so this manual will be very short. We suppose
you understand tla basics.

There is a DVC entry in the tools menu which is a good starting
point, and an "Tla-..." menu in most DVC-related modes. Once you
have learnt the keyboard shortcuts, you will not need the menus anymore.

The most important commands have global keybindings. The prefix is
C-x V by default. Type C-x V C-h for a list. In each
DVC specific buffer, other (shorter) keyboard shortcuts are
available. C-h m will give you a list.

To get help about a tla command, C-x V h command RET will show
you the output of tla command -H. Since DVC is nothing more
than a wrapper around tla, this is a very good way to get help !

Before starting, you will need to set your ID if you have not already
done so.

1.2.3 Tla Archive Browsing

It is pretty intuitive, just type C-x V A and investigate the
menu bar (Hmm, many people usually deactivate the menu bar, but please,
enable it while learning DVC ;-) You'll remove it afterwards) and the
mode help by C-h m.

If you have no archives registered yet, type a r and provide the
location of an archive.

1.2.5 Committing Files

First review your changes by typing C-x V =.

If your tree contains nested trees, then DVC will display the list of
nested trees at the top of the changes buffer. They are marked with a
T so that you can distinguish them from the modified files.
While computing, they have the status ?, and this becomes
M (resp. -) when the recursively called tla
process exits if there are some changes (resp. no changes) in the
nested tree.

To view the details of the changes, type RET on a nested tree
entry to open the corresponding changes buffer. To come back to the
root of the project, type ^.

Then review the log message by typing c within the
*tla-changes* buffer and edit it when needed.

Finally commit by typing C-c C-c.

If you want to commit only changes made to a given number of files,
select them with m in the *tla-changes* buffer (this also works from
the *tla-inventory* buffer) before typing c. The list of files used
for the selected files commit is the list of selected files in the
buffer in which you typed c, at the time you press C-c C-c to
commit. So, if you change your mind, you can go back and select/unselect
some files before committing.

1.2.6 Using Bookmarks

1.2.6.1 Bookmarks basics

Bookmarks are primarily used to keep a list of the most visited arch
locations. Type C-x V b will show you the bookmarks
buffer. It should be empty for now, but you can add some by typing a.

Ah, it's a pain, you have to type the full location, like
Matthieu.Moy@imag.fr--public/dvc--main--0.1, or just
Matthieu.Moy@imag.fr--public/dvc--main. No, let's do it the
easy way: Go back to your archive list (M-x tla-archives RET),
select the archive you want, then the category, branch, version. Now,
just select Set a bookmark here in the menu, type the name, and that's
it!

1.2.6.2 Using bookmarks for distributed development

Arch makes distributed development easy. Once you know that someone
has a patch for you in their archive, you can very easily merge it
with tla star-merge, or tla apply-changeset. But when several
developers are working on the same project, it's a pain to check
manually the missing patches in each archive.

OK, we've got what you need!

Add your own projects, and your contributors' projects too. Select
several related projects with m (unselect with u or
M-del). Make them partners with M-p. Now, with your cursor on
a bookmark, view the uncommited changes, the missing patches from your
archive and from your contributors with M. From this list, you
will usually want to update your tree if some changesets are missing
from your own archive (This is the M u keybinding), or star-merge
from your contributors' archives (This is the . S keybinding).

In this list, DVC will also highlight revisions not merged by other
revisions. You can navigate through them with N and P. It
is recommended to merge these patches first, because merging a
revision A, and later merging a revision B which is a merge of A often
results in conflicts.

Note that if you want to share your list of partners with all the
people having access to the project, you can just type f w to
write the list of parthers to the file
{arch}/=partner-versions, and your partners will just have to
type f r to read the list from this file. Note that using this
file, you will also be able to share your partner list with aba
users, and potentially others in the future.

If you are managing several projects at the same time (or one real
project and several personal configuration directory), select several
bookmarks with m, and type M to view all the missing
patches from all contributors.

The idea is that you will usually want to leave your office in the
evening with an empty list here, and check for new items when you come
back in the morning.

1.2.6.3 Bookmarks groups

Each bookmark can belong to a group of bookmarks. To make a group,
select some bookmarks, and hit a g. Enter a group name. The
selected bookmarks now belong to this group. To select a group, hit
* g and enter the group you want to select.

Developers will typically have one group for all the projects he or she
has write access to (for example, group mine), and one group of
bookmarks for each projects, including his partners' projects (I have a
group dvc). Then, pressing * g mine RET M will show me all
the missing patches for my projects. * g dvc RET M will tell me if my
partners for dvc are up-to-date with my archive.

1.3 How to use DVC depending on your role

1.3.1 Using DVC for anarchy-style development

1.3.2 Using DVC for star-shaped development

By “star-shaped development”, we mean a patch flow in which each
contributor only submit his patches to one version. This can be a
completely centralized solution, with one master version, or a
completely decentralized solution, with one master version for each
subprojects (potentially hierarchic), the main version for the full
project merging from the versions of the subprojects.

1.3.2.2 Getting the list of missing patches

Unless merge requests are processed only on-demand, it is very usefull
to know the list of patches committed by your contributors that you
didn't merge already. This is done with the command tla
missing. Usually, there is a list of regular contributors from which
you often merge, and you may want to keep this list somewhere. In
DVC, the best way to do it is probably through bookmarks See Using bookmarks for distributed development, but you can also use the
{arch}/=partner-versions (or the precious version
{arch}/+partner-versions) file for that: It is a list of
newline separated versions from which you often merge. The advantage
of this solution is that it is also implemented by aba and potentially
other tla front-ends in the future. Fortunately, you can keep it in
sync with your bookmarks from the bookmark buffer, with the key
sequences f w and f r (for respectively
tla-bookmarks-write-partners-to-file and
tla-bookmarks-add-partners-from-file).

You can also run C-u M-x tla-missing RET to view manually the
list of missing patches for a given version, off course, and you can
use the keybindings available in the name reading engine (Get the list
with C-h) to get quickly the fully qualified version name of a
contributor.

1.3.2.3 Reviewing patches before merging them

From a revision list buffer, RET will open the log file,
= will display the changeset.

If you are unsure about something, or whish to reject the patch, type
M-x tla-revision-send-comments RET to send a mail to the author
of the patch.

The usual way to merge is to put your cursor on the patch up to which
you want to merge, and type . s to “star-merge” the patches
from the common ancestor to this one. Other merge operators are
available. C-h m and the menubar will give you a list.

You can use “sync-tree” to reject a patch: After merging patches up
to the direct ancestor of the patch to be rejected, type M-x
tla-revision-sync-tree RET.

1.3.2.4 Generating patch-logs after merging

DVC can generate the log file automatically after a merge. Just try
C-c C-m in the log buffer. This will generate the body (using
tla log-for-merge), and a summary line is also generated. The
default format for the summary line should be good for a simple
contributor, but it is highy recommanded to change it if you are the
maintainer: The simplest way to do it is to set the
summary-format field for the bookmark corresponding to the
version you're managing (just type s on the bookmark of your
choice in the bookmark buffer). A typical value would be " [%s]":
The generated summary line will then look like

1.3.2.5 Being a contributor in a star-shaped development

1.4 Trouble Shooting

Due to some reasons TLA might fail. In order to investigate the reason
you can switch to the buffers containing TLA output. Switch to the
*tla-logs buffer (you can do that with
tla-open-internal-log-buffer). You get the list of processes
that have been ran since Emacs was started. Navigate with n and
p, and swith to the corresponding process buffer with RET,
to the error buffer with e, and to the buffer from which the
process was started with r. Note that the process and output
buffers are killed after some time if the variable
tla-number-of-dead-process-buffer is non-nil. You also have a
Tla-Buffers menu item in the DVC menu, on in your
menu-bar on arch-related buffers to navigate between those.

If you encounter an internal lisp error, enable backtrace generation by
M-x toggle-debug-on-error and reproduce the error. Now submit a
bug report with M-x dvc-submit-bug-report and ensure the content
of the buffer *Backtrace* is included.

1.8 The DVC Wiki

1.9 Changes in this Version

Development of DVC used to be very active, but has slowed down as the
users seem happy with the current version. The mailing list is a good
place learn about new features, but see also the docs/ANNOUNCEMENT file
in the DVC distribution.

1.11 The Future

1.11.1 Known Bugs

Please file one, that should be listed here!

Bugs should be submitted to the dvc-el-dev mailing list
(see Mailing Lists). To assist the developers, please include the
version numbers of DVC and tla and how to reproduce the bug. Further
the content of process buffers or in case of a lisp error a backtrace
might be helpful, see See Trouble Shooting. on how to get it.

Please use M-x dvc-submit-bug-report RET for submitting or at least
to get a template for the report which you copy to your favorite MUA.