DVC - The Emacs interface to Distributed Version Control Systems


Next: , Previous: (dir), Up: (dir)

1 DVC

DVC is an Emacs front end for various Decentralized Version Control systems. It is the successor of Xtla, which was the Emacs front-end to tla (GNU Arch).

The main features are:

Backends supported:

Bazaar (bzr)
http://bazaar-vcs.org/
Darcs
http://darcs.net/
Git
http://git.or.cz/
Mercurial (hg)
http://www.selenic.com/mercurial/
Monotone (mtn)
http://www.venge.net/monotone/
GNU Arch (tla)
http://www.gnu.org/software/gnu-arch/


Next: , Previous: Top, Up: Top

1.1 Installation

This program consists of several groups of files, organized by directory:


Next: , Previous: Installation, Up: Installation

1.1.1 Dependencies

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


Next: , Previous: Dependencies, Up: Installation

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.

For MinGW, see http://mingw.org/, and see http://www.venge.net/mtn-wiki/BuildingOnWindows for excellent installation instructions.

For Cygwin, see http://cygwin.com/.

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.


Previous: MS Windows, Up: Installation

1.1.3 Hooking into GNU Emacs

(There is nothing to do for XEmacs users here, just start using DVC, i.e. goto see DVC Tla Tour)

If you are reading this document the installation of files and setting up the load-path and Info-directory-list was already successful and you just need to load DVC now.

If auto-loading was built correctly you may start with M-x tla-archives RET.

In order to load DVC on Emacs start up you should include the following form in your Emacs configuration file, e.g. ~/.emacs.el:

     (load-file "/path/to/dvc/builddir/dvc-load.el")

Alternatively, you can set your load-path and load the autoload files manually with

     (require 'dvc-autoloads)
     (add-to-list 'load-path "/path/to/dvc/lisp/")

This will set up DVC.


Next: , Previous: Installation, Up: Top

1.2 DVC Tla Tour

This section discusses the basics of DVC - an overview of the available commands.


Next: , Previous: DVC Tla Tour, Up: DVC Tla Tour

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).


Next: , Previous: A tutorial guide to DVC, Up: A tutorial guide to DVC
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.


Next: , Previous: Register an tla archive, Up: A tutorial guide to DVC
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.


Next: , Previous: Bookmarking a project, Up: A tutorial guide to DVC
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.


Next: , Previous: Creating a branch of a project and getting a project tree, Up: A tutorial guide to DVC
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.


Previous: Finding and merging missing patches, Up: A tutorial guide to DVC
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.

To commit your changes, type C-c C-c from your log buffer.


Next: , Previous: A tutorial guide to DVC, Up: DVC Tla Tour

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.

You can execute the following command to set your id:

C-u M-x tla-my-id (or M-x tla-set-my-id RET)

To check your id, call the same command without a prefix argument:

M-x tla-my-id


Next: , Previous: First contact, Up: DVC Tla Tour

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.


Next: , Previous: Tla Archive Browsing, Up: DVC Tla Tour

1.2.4 Editing Files

Adding new files can be done in two ways:

  1. Add an arch-tag to the file, by typing C-x V t. Attention, files used as templates (Makefile.in) should be added explicitly instead of using arch-tag lines.
  2. Explicitly add it from the inventory view. Type C-x V i, mark the new files by typing m and finally add them by typing a.

You are encouraged to add log entries while you are editing. Type C-x V a add your notes.


Next: , Previous: Editing Files, Up: DVC Tla Tour

1.2.5 Committing Files

  1. 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 ^.

  2. Then review the log message by typing c within the *tla-changes* buffer and edit it when needed.
  3. 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.


Next: , Previous: Committing Files, Up: DVC Tla Tour

1.2.6 Using Bookmarks


Next: , Previous: Using Bookmarks, Up: 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!

You can view the details of bookmarks with t.


Next: , Previous: Bookmarks basics, Up: Using Bookmarks
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.


Previous: Using bookmarks for distributed development, Up: Using Bookmarks
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.


Previous: Using Bookmarks, Up: DVC Tla Tour

1.2.7 Transmit patches via email

This section discusses a way to send/receive patches via email. That way you can create patches for a project without the need to create a branch for your contribution.


Next: , Previous: Transmit patches via email, Up: Transmit patches via email
1.2.7.1 Send patches via Gnus

When you are tracking a project via GNU Arch, you can just edit your checked out working copy. When you have done that, just do M-x tla-submit-patch RET.

That command calculates a changeset for your changes. That changeset is archived in a tarball and attached to a new created email.

You can add a description of the changeset to the prepared email. After you have entered your description, just send the mail.

The variable tla-submit-patch-mapping allows you to specify a list of rules to preselect the destination email address.

The default setting for tla-submit-patch-mapping is here: (((nil "dvc" nil nil nil) ("dvc-el-dev@gna.org" "dvc")))

It defines, that every branch of the dvc project should submit patches to dvc-el-dev@gna.org. The entry "dvc" just specifies, that the filename for the patch should start with dvc.


Previous: Send patches via Gnus, Up: Transmit patches via email
1.2.7.2 Receive/Apply patches via Gnus

To hook DVC to Gnus, put the following in your .emacs: (tla-insinuate-gnus)

Now the K t binding is available as prefix key in Gnus summary buffers. This will also buttonize archives, categories, branches, version and revision names in the *article* buffer.

The two important commands are:

  1. K t v: View the changeset
  2. K t a: Apply the changeset to one of your working trees

You can predefine the working tree, where you want to apply certain kind of patches via tla-apply-patch-mapping.

The follwing code specifies "~/work/myprg/dvc-dev/" as default working tree for patches for the DVC project:

(setq tla-apply-patch-mapping '(((nil "dvc" nil nil nil) "~/work/myprg/dvc-dev/")))

When you have applied the patch, you can commit the patch as usual. The new keybinding C-c C-p inserts a log message that is extracted from the received mail:

  1. The subject is used as the patch summary line
  2. The text between the log-start and the log-end markers in the mail specify the rest of the log message


Next: , Previous: DVC Tla Tour, Up: Top

1.3 How to use DVC depending on your role


Next: , Previous: Use cases, Up: Use cases

1.3.1 Using DVC for anarchy-style development


Previous: Anarchic development, Up: Use cases

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.


Next: , Previous: Star-shaped development, Up: Star-shaped development
1.3.2.1 Being a maintainer in a star-shaped development

We call “maintainer” the person in charge of merging patches from contributors in his archive. In the case of a subproject, the maintainer for a subproject is also a contributor for the main project.

DVC can help you in this task:


Next: , Previous: Maintainer, Up: Star-shaped development
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.


Next: , Previous: Missing patches, Up: Star-shaped development
1.3.2.3 Reviewing patches before merging them

A good maintainer should never merge patches blindly.

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.


Next: , Previous: Reviewing patches, Up: Star-shaped development
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

Summary:  [mark@dishevelled.net--2003-mst (patch 6-8)]

That you can complete manually to something like

Summary: Bugfix for regression tests [mark@dishevelled.net--2003-mst (patch 6-8)]

More customization can be done: see the docstring for the variable


Previous: Patch-log Generation, Up: Star-shaped development
1.3.2.5 Being a contributor in a star-shaped development


Next: , Previous: Use cases, Up: Top

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.


Next: , Previous: Trouble Shooting, Up: Top

1.5 Customization

Do a M-x customize-group RET dvc RET and browse the available options and modify them to suite your needs.


Next: , Previous: Customization, Up: Top

1.6 Internals

There is a docs sub-directory in the archive of DVC containing information for developers.


Next: , Previous: Internals, Up: Top

1.7 Mailing Lists

There is one mailing list for DVC.

dvc-dev@gna.org intended for the discussion of development versions of DVC. Users of development versions of DVC should subscribe to this list. Bugs should also be reported to this list.

See See Known Bugs. for instructions on submitting bug reports or feature requests.


Next: , Previous: Mailing Lists, Up: Top

1.8 The DVC Wiki

A wiki for DVC can be found at

http://www.emacswiki.org/emacs/DistributedVersionControl.


Next: , Previous: Wiki, Up: Top

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.


Next: , Previous: Changes, Up: Top

1.10 The Latest Version

Get the bzr repository for DVC:

# bzr get http://bzr.xsteve.at/dvc

Users of development versions of DVC should subscribe to the dvc-el-dev mailing list. See Mailing Lists.


Next: , Previous: The Latest Version, Up: Top

1.11 The Future

The future consists of Bugs and Features.


Next: , Previous: The Future, Up: The Future

1.11.1 Known Bugs

  1. 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.


Previous: Known Bugs, Up: The Future

1.11.2 TODO List

Near Future
Not-So-Near Future


Next: , Previous: The Future, Up: Top

1.12 Thanks


Next: , Previous: Thanks, Up: Top

1.13 Concept Index


Previous: Concept Index, Up: Top

1.14 Variable Index

Table of Contents