elisp-vcs/dvc/texinfo/dvc.texinfo

\input texinfo  @c -*-texinfo-*-  -*- coding: iso-latin-1 -*-
@c %**start of header
@setfilename dvc.info
@settitle DVC - The Emacs interface to Distributed Version Control Systems
@c If this is set, show images in the HTML version
@c @set SHOW_IMAGES
@c %**end of header

@ifinfo
@dircategory Emacs
@direntry
* DVC: (dvc).             The Emacs interface to Distributed Version
                            Control Systems.
@end direntry

Copyright (c) 2004-2005, 2007, 2008 The DVC Development Team
@end ifinfo

@include dvc-version.texinfo

@titlepage
@title DVC User Manual
@subtitle The Emacs interface to Distributed Version Control Systems

@author The DVC Development Team
@page
Copyright @copyright{} 2004-2005 The DVC Development Team

@sp 2
This is the @value{UPDATED} edition
of the User Manual for @cite{DVC} @value{VERSION}.

@sp 2

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the author.

@end titlepage
@page

@c ============================================================================
@node Top, Installation, (dir), (dir)
@chapter DVC

@b{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:

@itemize @bullet
@item dvc-status: Intuitive interface for viewing the status of a
working directory.
@item dvc-log: Log viewer.  Perform actions on specific commits, such as
viewing them and emailing them.
@item dvc-diff: View uncommitted changes in your working directory and
use them to prepare a commit log entry.
@item dvc-bookmarks: Bookmark manager.  Keep your most frequently used
repositories and working directories in your bookmark buffer.  Also,
specify "partner" branches or repositories, whose changes can be
compared with your work.
@item Integration with ediff, which is an excellent visual interface for
changes between multiple files/versions.  This Emacs mode is useful for:
@itemize @bullet
@item Viewing changes made in a local tree.
@item Viewing and resolving conflicts after a merge.
@end itemize
@item dvc-missing: Interface to view missing patches from all your
partners with a single command
@item Send/receive/apply patches via the Gnus email client.
@item Run many version control commands from Emacs (such as init and pull).
@end itemize

Backends supported:

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

   @end table

@c ============================================================================
@menu
* Installation::
* DVC Tla Tour::
* Use cases::
* Trouble Shooting::
* Customization::
* Internals::
* Mailing Lists::
* Wiki::
* Changes::
* The Latest Version::
* The Future::
* Thanks::
* Concept Index::
* Variable Index::
@end menu

@node Installation, DVC Tla Tour, Top, Top
@section Installation
@cindex Installation
@cindex Makefile

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

@ifinfo
@example
     lisp     - the main program code
     texinfo  - the documentation files
     docs     - text documents for hacking DVC
@end example
@end ifinfo

@menu
* Dependencies::
* MS Windows::
* Hooking into GNU Emacs::
@end menu

@c ----------------------------------------------------------------------------
@node Dependencies, MS Windows, Installation, Installation
@subsection Dependencies

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

@itemize @bullet

@item @code{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 @code{ewoc.el}
is included in the distribution until available by an stable version of
XEmacs. It is already included in GNU Emacs 21.

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

You can also install it as a standalone package. The latest version of
@code{tree-widget.el} can be found at
@url{http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/tree-widget.el}

If @code{tree-widget.el} is not in your default @code{load-path}, you
should provide its location with the argument @code{--with-other-dirs}
of the @code{configure} script.

@item @code{smerge-mode.el}: Minor mode to resolve diff3 conflicts.  It
is not essential, but reduces resolving of conflicts to deciding which
version to keep.

The latest version of @code{smerge-mode.el} can be found at
@url{http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/smerge-mode.el}

@end itemize

@node MS Windows, Hooking into GNU Emacs, Dependencies, Installation
@subsection MS Windows
DVC requires a POSIX shell, used to run the backends. On Unix-like
systems, @file{/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 @url{http://mingw.org/}, and see
@url{http://www.venge.net/mtn-wiki/BuildingOnWindows} for excellent
installation instructions.

For Cygwin, see @url{http://cygwin.com/}.

Both MinGW and Cygwin work better with native MS Windows Emacs if
installed to @file{c:/} instead of @file{c:/MinGW} or
@file{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 @file{c:/Cygwin}, it mounts
@file{/} at @file{c:/Cygwin}. Then the file known to Emacs as
@file{c:/Cygwin/bin/make.exe} is known to Cygwin applications as
@file{/bin/make.exe}. Also, the file known to Emacs as
@file{c:/Projects/my_file.text} is known to Cygwin as
@file{/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 @file{c:/}, then it mounts @file{/}
at @file{c:/}. Then the file known to Emacs as @file{c:/bin/make.exe}
is known to Cygwin applications as @file{/bin/make.exe}. Also, the
file known to Emacs as @file{c:/Projects/my_file.text} is known to
Cygwin as @file{/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 @file{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 @emph{both} Cygwin and MinGW at @file{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
@code{explicit-shell-file-name} may help in resolving shell issues.

@c ----------------------------------------------------------------------------
@node Hooking into GNU Emacs,  , MS Windows, Installation
@subsection Hooking into GNU Emacs
@cindex Hooking into GNU Emacs

(There is nothing to do for XEmacs users here, just start using
@b{DVC}, i.e. goto @pxref{DVC Tla Tour})

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

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

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

@example
@code{(load-file "/path/to/dvc/builddir/dvc-load.el")}
@end example

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

@example
@code{(require 'dvc-autoloads)}
@code{(add-to-list 'load-path "/path/to/dvc/lisp/")}
@end example

This will set up @b{DVC}.

@c ============================================================================
@node DVC Tla Tour, Use cases, Installation, Top
@section DVC Tla Tour

This section discusses the basics of @b{DVC} - an overview of the
available commands.

@menu
* A tutorial guide to DVC::
* First contact::               DVC is self documented
* Tla Archive Browsing::        The basics of tla archive browsing
* Editing Files::               Inserting tags, adding change logs
* Committing Files::            How to commit your changes
* Using Bookmarks::             Working in a team
* Transmit patches via email::  Send/apply patches via Gnus
@end menu


@c ----------------------------------------------------------------------------

@node A tutorial guide to DVC, First contact, DVC Tla Tour, DVC Tla Tour
@subsection 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).

@menu
* Register an tla archive::
* Bookmarking a project::
* Creating a branch of a project and getting a project tree::
* Finding and merging missing patches::
* Reviewing and committing your changes::
@end menu

@node Register an tla archive, Bookmarking a project, A tutorial guide to DVC, A tutorial guide to DVC
@subsubsection 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 (@kbd{C-x V A}) and typing @kbd{a r} to register a new archive.
DVC's archive location is currently
@url{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.

@ifhtml
@ifset SHOW_IMAGES
@html
<img src="archives.png">
@end html
@end ifset
@end ifhtml

@node Bookmarking a project, Creating a branch of a project and getting a project tree, Register an tla archive, A tutorial guide to DVC
@subsubsection 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 (@kbd{C-x V b}) and adding a new bookmark with (@kbd{a
b}, or ``add bookmark'').  You should be prompted for a version name,
and you can use tab completion to enter
@code{Matthieu.Moy@@imag.fr--public/dvc--main--0}.  You can give your
bookmark any name you like.

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


@node Creating a branch of a project and getting a project tree, Finding and merging missing patches, Bookmarking a project, A tutorial guide to DVC
@subsubsection 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 (@kbd{C-x V b}), move
the point to your bookmark for DVC and hit @kbd{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
@code{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 @kbd{>}.  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.

@ifhtml
@ifset SHOW_IMAGES
@html
<img src="bookmarks.png">
@end html
@end ifset
@end ifhtml


@node Finding and merging missing patches, Reviewing and committing your changes, Creating a branch of a project and getting a project tree, A tutorial guide to DVC
@subsubsection 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 (@kbd{C-x V b}), move your point
to the bookmark of your DVC branch and hit @kbd{M m}.  A
@code{*tla-missing*} buffer should appear, and show any patches that are
in the mainline but not in your tree.

@ifhtml
@ifset SHOW_IMAGES
@html
<img src="missing.png">
@end html
@end ifset
@end ifhtml

To merge all missing patches from the DVC mainline into your project
tree, move your point to the DVC mainline partner entry and hit @kbd{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 @kbd{M} prefix.  For example, @kbd{r} will replay only the revision
under the point (allowing you to cherry-pick patches), and @kbd{s} will
star-merge all missing patches up to the patch under the point.


@node Reviewing and committing your changes,  , Finding and merging missing patches, A tutorial guide to DVC
@subsubsection Reviewing and committing your changes

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

@ifhtml
@ifset SHOW_IMAGES
@html
<img src="changes.png">
@end html
@end ifset
@end ifhtml

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

@ifhtml
@ifset SHOW_IMAGES
@html
<img src="log.png">
@end html
@end ifset
@end ifhtml

To commit your changes, type @kbd{C-c C-c} from your log buffer.


@node First contact, Tla Archive Browsing, A tutorial guide to DVC, DVC Tla Tour
@subsection First contact

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

There is a @b{DVC} entry in the tools menu which is a good starting
point, and an "Tla-..." menu in most @b{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
@kbd{C-x V} by default. Type @kbd{C-x V C-h} for a list. In each
@b{DVC} specific buffer, other (shorter) keyboard shortcuts are
available. @kbd{C-h m} will give you a list.

To get help about a tla command, @kbd{C-x V h command RET} will show
you the output of @code{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:

@kbd{C-u M-x tla-my-id} (or @kbd{M-x tla-set-my-id RET})

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

@kbd{M-x tla-my-id}

@c ----------------------------------------------------------------------------
@node Tla Archive Browsing, Editing Files, First contact, DVC Tla Tour
@subsection Tla Archive Browsing

It is pretty intuitive, just type @kbd{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 @kbd{C-h m}.

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

@c ----------------------------------------------------------------------------
@node Editing Files, Committing Files, Tla Archive Browsing, DVC Tla Tour
@subsection Editing Files

Adding new files can be done in two ways:

@enumerate

@item Add an arch-tag to the file, by typing @kbd{C-x V t}. Attention,
files used as templates (@code{Makefile.in}) should be added explicitly
instead of using arch-tag lines.

@item Explicitly add it from the inventory view. Type @kbd{C-x V i},
mark the new files by typing @code{m} and finally add them by typing
@kbd{a}.

@end enumerate

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

@c ----------------------------------------------------------------------------
@node Committing Files, Using Bookmarks, Editing Files, DVC Tla Tour
@subsection Committing Files

@enumerate
@item First review your changes by typing @kbd{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
@kbd{T} so that you can distinguish them from the modified files.
While computing, they have the status @code{?}, and this becomes
@code{M} (resp. @code{-}) when the recursively called @code{tla}
process exits if there are some changes (resp. no changes) in the
nested tree.

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

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

@item Finally commit by typing @kbd{C-c C-c}.
@end enumerate


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

@c ----------------------------------------------------------------------------
@node Using Bookmarks, Transmit patches via email, Committing Files, DVC Tla Tour
@subsection Using Bookmarks

@cindex Working in a project
@cindex Finding missing patches

@menu
* Bookmarks basics::
* Using bookmarks for distributed development::
* Bookmarks groups::
@end menu

@node Bookmarks basics, Using bookmarks for distributed development, Using Bookmarks, Using Bookmarks
@subsubsection Bookmarks basics

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

Ah, it's a pain, you have to type the full location, like
@code{Matthieu.Moy@@imag.fr--public/dvc--main--0.1}, or just
@code{Matthieu.Moy@@imag.fr--public/dvc--main}.  No, let's do it the
easy way: Go back to your archive list (@kbd{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 @kbd{t}.

@node Using bookmarks for distributed development, Bookmarks groups, Bookmarks basics, Using Bookmarks
@subsubsection 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 @kbd{m} (unselect with @kbd{u} or
@kbd{M-del}). Make them partners with @kbd{M-p}. Now, with your cursor on
a bookmark, view the uncommited changes, the missing patches from your
archive and from your contributors with @kbd{M}. From this list, you
will usually want to update your tree if some changesets are missing
from your own archive (This is the @kbd{M u} keybinding), or star-merge
from your contributors' archives (This is the @kbd{. S} keybinding).

In this list, DVC will also highlight revisions not merged by other
revisions. You can navigate through them with @kbd{N} and @kbd{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 @kbd{f w} to
write the list of parthers to the file
@code{@{arch@}/=partner-versions}, and your partners will just have to
type @kbd{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 @code{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 @kbd{m}, and type @kbd{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.

@node Bookmarks groups,  , Using bookmarks for distributed development, Using Bookmarks
@subsubsection  Bookmarks groups

Each bookmark can belong to a group of bookmarks. To make a group,
select some bookmarks, and hit @kbd{a g}. Enter a group name. The
selected bookmarks now belong to this group. To select a group, hit
@kbd{* 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 @code{mine}), and one group of
bookmarks for each projects, including his partners' projects (I have a
group @code{dvc}). Then, pressing @kbd{* g mine RET M} will show me all
the missing patches for my projects. @kbd{* g dvc RET M} will tell me if my
partners for @code{dvc} are up-to-date with my archive.

@c ----------------------------------------------------------------------------
@node Transmit patches via email,  , Using Bookmarks, DVC Tla Tour
@subsection 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.

@menu
* Send patches via Gnus::
* Receive/Apply patches via Gnus::
@end menu

@node Send patches via Gnus, Receive/Apply patches via Gnus, Transmit patches via email, Transmit patches via email
@comment  node-name,  next,  previous,  up
@subsubsection 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 @kbd{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:
@code{(((nil "dvc" nil nil nil) ("dvc-el-dev@@gna.org" "dvc")))}

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

@node Receive/Apply patches via Gnus,  , Send patches via Gnus, Transmit patches via email
@comment  node-name,  next,  previous,  up
@subsubsection Receive/Apply patches via Gnus

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

Now the @kbd{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 @code{*article*} buffer.

The two important commands are:
@enumerate
@item @kbd{K t v}: View the changeset
@item @kbd{K t a}: Apply the changeset to one of your working trees
@end enumerate

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

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

@code{(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 @kbd{C-c C-p} inserts a log message that is extracted
from the received mail:
@enumerate
@item The subject is used as the patch summary line
@item The text between the log-start and the log-end markers in the mail specify the rest of the log message
@end enumerate


@node Use cases, Trouble Shooting, DVC Tla Tour, Top
@comment  node-name,  next,  previous,  up
@section How to use DVC depending on your role

@menu
* Anarchic development::
* Star-shaped development::
@end menu


@node Anarchic development, Star-shaped development, Use cases, Use cases
@comment  node-name,  next,  previous,  up
@subsection Using DVC for anarchy-style development

@comment TODO

@node Star-shaped development,  , Anarchic development, Use cases
@comment  node-name,  next,  previous,  up
@subsection 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.

@menu
* Maintainer::
* Missing patches::
* Reviewing patches::
* Patch-log Generation::
* Contributor::
@end menu

@node Maintainer, Missing patches, Star-shaped development, Star-shaped development
@comment  node-name,  next,  previous,  up
@subsubsection 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:

@menu
* Missing patches::
* Reviewing patches::
@end menu

@node Missing patches, Reviewing patches, Maintainer, Star-shaped development
@comment  node-name,  next,  previous,  up
@subsubsection 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 @code{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 @xref{Using
bookmarks for distributed development}, but you can also use the
@code{@{arch@}/=partner-versions} (or the precious version
@code{@{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 @kbd{f w} and @kbd{f r} (for respectively
@code{tla-bookmarks-write-partners-to-file} and
@code{tla-bookmarks-add-partners-from-file}).

You can also run @kbd{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 @kbd{C-h}) to get quickly the fully qualified version name of a
contributor.

@node Reviewing patches, Patch-log Generation, Missing patches, Star-shaped development
@comment  node-name,  next,  previous,  up
@subsubsection Reviewing patches before merging them

A good maintainer should never merge patches blindly.

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

If you are unsure about something, or whish to reject the patch, type
@kbd{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 @kbd{. s} to ``star-merge'' the patches
from the common ancestor to this one. Other merge operators are
available. @kbd{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 @kbd{M-x
tla-revision-sync-tree RET}.

@node Patch-log Generation, Contributor, Reviewing patches, Star-shaped development
@comment  node-name,  next,  previous,  up
@subsubsection Generating patch-logs after merging

DVC can generate the log file automatically after a merge. Just try
@kbd{C-c C-m} in the log buffer. This will generate the body (using
@code{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
@code{summary-format} field for the bookmark corresponding to the
version you're managing (just type @kbd{s} on the bookmark of your
choice in the bookmark buffer). A typical value would be @code{" [%s]"}:
The generated summary line will then look like

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

That you can complete manually to something like

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

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

@node Contributor,  , Patch-log Generation, Star-shaped development
@comment  node-name,  next,  previous,  up
@subsubsection Being a contributor in a star-shaped development

@comment TODO

@c ============================================================================
@node Trouble Shooting, Customization, Use cases, Top
@section 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
@code{ *tla-logs} buffer (you can do that with
@code{tla-open-internal-log-buffer}). You get the list of processes
that have been ran since Emacs was started. Navigate with @kbd{n} and
@kbd{p}, and swith to the corresponding process buffer with @kbd{RET},
to the error buffer with @kbd{e}, and to the buffer from which the
process was started with @kbd{r}. Note that the process and output
buffers are killed after some time if the variable
@code{tla-number-of-dead-process-buffer} is non-nil. You also have a
@code{Tla-Buffers} menu item in the @code{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
@kbd{M-x toggle-debug-on-error} and reproduce the error.  Now submit a
bug report with @kbd{M-x dvc-submit-bug-report} and ensure the content
of the buffer @code{*Backtrace*} is included.

@c ============================================================================
@node Customization, Internals, Trouble Shooting, Top
@section Customization

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

@c ============================================================================
@node Internals, Mailing Lists, Customization, Top
@section Internals

There is a @code{docs} sub-directory in the archive of @b{DVC}
containing information for developers.

@c ============================================================================
@node Mailing Lists, Wiki, Internals, Top
@section Mailing Lists

There is one mailing list for @b{DVC}.

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

See @xref{Known Bugs}. for instructions on submitting bug reports or
feature requests.

@c ============================================================================
@node Wiki, Changes, Mailing Lists, Top
@section The DVC Wiki

A wiki for DVC can be found at

@url{http://www.emacswiki.org/emacs/DistributedVersionControl}.

@c ============================================================================
@node Changes, The Latest Version, Wiki, Top
@section 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.

@c ============================================================================
@node The Latest Version, The Future, Changes, Top
@section The Latest Version

@noindent

Get the bzr repository for @b{DVC}:

@code{# bzr get http://bzr.xsteve.at/dvc}

Users of development versions of @b{DVC} @b{should subscribe} to the
@code{dvc-el-dev} mailing list.  @xref{Mailing Lists}.

@c ============================================================================
@node The Future, Thanks, The Latest Version, Top
@section The Future

The future consists of Bugs and Features.

@menu
* Known Bugs::                  Known Bugs, and how to submit new ones
* TODO List::                   The TODO List
@end menu

@c ----------------------------------------------------------------------------
@node Known Bugs, TODO List, The Future, The Future
@subsection Known Bugs

@enumerate
@item Please file one, that should be listed here!
@end enumerate

Bugs should be submitted to the @code{dvc-el-dev} mailing list
(@pxref{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 @xref{Trouble Shooting}. on how to get it.

Please use @kbd{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.

@c ----------------------------------------------------------------------------
@node TODO List,  , Known Bugs, The Future
@subsection TODO List

@subsubheading Near Future

@itemize @bullet
@item many bug fixes
@end itemize

@subsubheading Not-So-Near Future

@itemize @bullet
@item no need for a command line invocation of @code{tla}.
@end itemize

@c ============================================================================
@node Thanks, Concept Index, The Future, Top
@section Thanks

@c ============================================================================
@node Concept Index, Variable Index, Thanks, Top
@section Concept Index
@printindex cp

@c ============================================================================
@node Variable Index,  , Concept Index, Top
@section Variable Index
@printindex vr

@contents
@bye