Xtla is an Emacs front end for tla/baz (GNU Arch client), the next generation of version control software.
The main features are:
This file documents Xtla, version
1.2 (Matthieu.Moy@imag.fr--public/xtla--main--1.2--version-0)
This program consists of several groups of files, organized by directory:
Various parts of the Xtla 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 xtla 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.
You can also install it as a standalone package. The latest version of
tree-widget.el can be found at
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/tree-widget.el
If tree-widget.el is not in your default load-path, you
should provide its location with the argument --with-other-dirs
of the configure script.
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 smerge-mode.el can be found at
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/smerge-mode.el
(There is nothing to do for XEmacs users here, just start using Xtla, i.e. goto see Xtla 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 Xtla now.
If auto-loading was built correctly you may start with M-x
tla-archives RET.
In order to load Xtla on Emacs start up you should include the following
form in your Emacs configuration file, e.g. ~/.emacs.el:
(require 'xtla-autoloads)
This will set up Xtla.
This section discusses the basics of Xtla - an overview of the available commands.
The following sections present a step-by-step tutorial guide to using Xtla 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 Xtla project as an example of a project you might like to track (humour me).
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 T A) and typing a r to register a new archive. Xtla'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.
The normal usage of Xtla 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 Xtla.
To track Xtla'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 T 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/xtla--main--0.1. 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.
Having created a bookmark for the Xtla project, you are ready to create
your own branch. Again from the bookmarks buffer (C-x T b), move
the point to your bookmark for Xtla 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/xtla--main--0.1.) This will
create a tag of the main Xtla project in your own archive and add a
bookmark for it.
Your newly-added bookmark will be marked as a “partner” of your main Xtla bookmark. This records the fact that the two projects are related so that Xtla can show you which patches from the Xtla 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.
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. Xtla is particularly good at doing this.
Start by entering the bookmarks buffer (C-x T b), move your point
to the bookmark of your Xtla 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 Xtla mainline into your project tree, move your point to the Xtla 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.
After making changes to your project tree, you are ready to commit. You
can review your changes by typing C-x T = 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 T 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 T 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 T c to return to it
later. You can also add a ChangeLog-style entry by hitting C-x T
a from the project tree file you are currently visiting.
To commit your changes, type C-c C-c from your log buffer.
Xtla is self documented, so this manual will be very short. We suppose you understand tla basics.
There is a Xtla entry in the tools menu which is a good starting point, and an "Tla-..." menu in most Xtla-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 T by default. Type C-x T C-h for a list. In each Xtla 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 T h command RET will show
you the output of tla command -H. Since Xtla 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
It is pretty intuitive, just type C-x T A and investigate the menu bar (Hmm, many people usually deactivate the menu bar, but please, enable it while learning Xtla ;-) 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.
Adding new files can be done in two ways:
Makefile.in) should be added explicitly
instead of using arch-tag lines.
m and finally add them by typing
a.
You are encouraged to add log entries while you are editing. Type C-x T a add your notes.
If your tree contains nested trees, then Xtla 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 ^.
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.
Bookmarks are primarily used to keep a list of the most visited arch locations. Type C-x T 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/xtla--main--0.1, or just
Matthieu.Moy@imag.fr--public/xtla--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.
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, Xtla 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.
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 xtla). Then, pressing * g mine RET M will show me all
the missing patches for my projects. * g xtla RET M will tell me if my
partners for xtla are up-to-date with my archive.
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.
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 "xtla" nil nil nil) ("xtla-el-dev@gna.org" "xtla")))
It defines, that every branch of the xtla project should submit patches
to xtla-el-dev@gna.org. The entry "xtla" just specifies,
that the filename for the patch should start with xtla.
To hook Xtla 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:
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/xtla-dev/" as default
working tree for patches for the Xtla project:
(setq tla-apply-patch-mapping
'(((nil "xtla" nil nil nil) "~/work/myprg/xtla-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:
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.
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.
Xtla can help you in this task:
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
Xtla, 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.
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.
Xtla 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
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 Xtla 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 tla-submit-bug-report and ensure the content
of the buffer *Backtrace* is included.
Do a M-x customize-group RET xtla RET and browse the available options and modify them to suite your needs.
There is a docs sub-directory in the archive of Xtla
containing information for developers.
There is one mailing lists for Xtla.
xtla-el-dev@gna.org intended for the discussion of development
versions of Xtla. Users of development versions of Xtla 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.
A wiki for Xtla can be found at
This site is also the location of the GNU Arch wiki
http://wiki.gnuarch.org/FrontPage
Development of Xtla 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 Xtla distribution.
Tarballs of Xtla can be found at the following URL:
http://download.gna.org/xtla-el/
Development versions of Xtla can be obtained from a public archive of one of the developers, e.g. from the initiator of Xtla:
xtla-browse.el, ...
Users of development versions of Xtla should subscribe to the
xtla-el-dev mailing list. See Mailing Lists.
The future consists of Bugs and Features.
Bugs should be submitted to the xtla-el-dev mailing list
(see Mailing Lists). To assist the developers, please include the
version numbers of Xtla 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 tla-submit-bug-report RET for submitting or at least to get a template for the report which you copy to your favorite MUA.
tla.