« back to all changes in this revision
Viewing changes to dvc/texinfo/dvc.texinfo
- browse files at revision 9
- compare with another revision
- download diff
- download tarball
- view history from revision 9
- Committer: Aaron Gallagher
- Date: 2010-10-06 19:58:21 UTC
- Revision ID: habnabit@gmail.com-20101006195821-r6ccvbwr1zhsxubf
Adding more stuff.
- files added:
- color-moccur.el
- dvc
- dvc/++build
- dvc/++build/lisp
- dvc/++build/texinfo
- dvc/autom4te.cache
- dvc/debian
- dvc/debian/source
- dvc/docs
- dvc/lisp
- dvc/lisp/contrib
- dvc/lisp/tests
- dvc/scripts
- dvc/tests
- dvc/texinfo
- dvc/www
- files modified:
- .bzrignore
added
removed
dvc/texinfo/dvc.texinfo
1
\input texinfo @c -*-texinfo-*- -*- coding: iso-latin-1 -*-
2
@c %**start of header
3
@setfilename dvc.info
4
@settitle DVC - The Emacs interface to Distributed Version Control Systems
5
@c If this is set, show images in the HTML version
6
@c @set SHOW_IMAGES
7
@c %**end of header
8
9
@ifinfo
10
@dircategory Emacs
11
@direntry
12
* DVC: (dvc). The Emacs interface to Distributed Version
13
Control Systems.
14
@end direntry
15
16
Copyright (c) 2004-2005, 2007, 2008 The DVC Development Team
17
@end ifinfo
18
19
@include dvc-version.texinfo
20
21
@titlepage
22
@title DVC User Manual
23
@subtitle The Emacs interface to Distributed Version Control Systems
24
25
@author The DVC Development Team
26
@page
27
Copyright @copyright{} 2004-2005 The DVC Development Team
28
29
@sp 2
30
This is the @value{UPDATED} edition
31
of the User Manual for @cite{DVC} @value{VERSION}.
32
33
@sp 2
34
35
Permission is granted to make and distribute verbatim copies of this
36
manual provided the copyright notice and this permission notice are
37
preserved on all copies.
38
39
Permission is granted to copy and distribute modified versions of
40
this manual under the conditions for verbatim copying, provided that
41
the entire resulting derived work is distributed under the terms of a
42
permission notice identical to this one.
43
44
Permission is granted to copy and distribute translations of this
45
manual into another language, under the above conditions for modified
46
versions, except that this permission notice may be stated in a
47
translation approved by the author.
48
49
@end titlepage
50
@page
51
52
@c ============================================================================
53
@node Top, Installation, (dir), (dir)
54
@chapter DVC
55
56
@b{DVC} is an Emacs front end for various Decentralized Version Control
57
systems. It is the successor of Xtla, which was the Emacs front-end to
58
tla (GNU Arch).
59
60
The main features are:
61
62
@itemize @bullet
63
@item dvc-status: Intuitive interface for viewing the status of a
64
working directory.
65
@item dvc-log: Log viewer. Perform actions on specific commits, such as
66
viewing them and emailing them.
67
@item dvc-diff: View uncommitted changes in your working directory and
68
use them to prepare a commit log entry.
69
@item dvc-bookmarks: Bookmark manager. Keep your most frequently used
70
repositories and working directories in your bookmark buffer. Also,
71
specify "partner" branches or repositories, whose changes can be
72
compared with your work.
73
@item Integration with ediff, which is an excellent visual interface for
74
changes between multiple files/versions. This Emacs mode is useful for:
75
@itemize @bullet
76
@item Viewing changes made in a local tree.
77
@item Viewing and resolving conflicts after a merge.
78
@end itemize
79
@item dvc-missing: Interface to view missing patches from all your
80
partners with a single command
81
@item Send/receive/apply patches via the Gnus email client.
82
@item Run many version control commands from Emacs (such as init and pull).
83
@end itemize
84
85
Backends supported:
86
87
@table @dfn
88
@item Bazaar (bzr)
89
@url{http://bazaar-vcs.org/}
90
@item Darcs
91
@url{http://darcs.net/}
92
@item Git
93
@url{http://git.or.cz/}
94
@item Mercurial (hg)
95
@url{http://www.selenic.com/mercurial/}
96
@item Monotone (mtn)
97
@url{http://www.venge.net/monotone/}
98
@item GNU Arch (tla)
99
@url{http://www.gnu.org/software/gnu-arch/}
100
101
@end table
102
103
@c ============================================================================
104
@menu
105
* Installation::
106
* DVC Tla Tour::
107
* Use cases::
108
* Trouble Shooting::
109
* Customization::
110
* Internals::
111
* Mailing Lists::
112
* Wiki::
113
* Changes::
114
* The Latest Version::
115
* The Future::
116
* Thanks::
117
* Concept Index::
118
* Variable Index::
119
@end menu
120
121
@node Installation, DVC Tla Tour, Top, Top
122
@section Installation
123
@cindex Installation
124
@cindex Makefile
125
126
This program consists of several groups of files, organized by directory:
127
128
@ifinfo
129
@example
130
lisp - the main program code
131
texinfo - the documentation files
132
docs - text documents for hacking DVC
133
@end example
134
@end ifinfo
135
136
@menu
137
* Dependencies::
138
* MS Windows::
139
* Hooking into GNU Emacs::
140
@end menu
141
142
@c ----------------------------------------------------------------------------
143
@node Dependencies, MS Windows, Installation, Installation
144
@subsection Dependencies
145
146
Various parts of the @b{DVC} require extra packages to be available.
147
Currently there are the following dependencies:
148
149
@itemize @bullet
150
151
@item @code{ewoc.el}: a utility to maintain a view of a list of objects
152
in a buffer. This is essential for dvc and a version of @code{ewoc.el}
153
is included in the distribution until available by an stable version of
154
XEmacs. It is already included in GNU Emacs 21.
155
156
@item @code{tree-widget.el} is required for @code{xtla-browse.el}.
157
The CVS version of GNU Emacs includes @code{tree-widget.el}. XEmacs
158
users should install the latest @b{@code{jde}} package which includes
159
@code{tree-widget.el}.
160
161
You can also install it as a standalone package. The latest version of
162
@code{tree-widget.el} can be found at
163
@url{http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/tree-widget.el}
164
165
If @code{tree-widget.el} is not in your default @code{load-path}, you
166
should provide its location with the argument @code{--with-other-dirs}
167
of the @code{configure} script.
168
169
@item @code{smerge-mode.el}: Minor mode to resolve diff3 conflicts. It
170
is not essential, but reduces resolving of conflicts to deciding which
171
version to keep.
172
173
The latest version of @code{smerge-mode.el} can be found at
174
@url{http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/smerge-mode.el}
175
176
@end itemize
177
178
@node MS Windows, Hooking into GNU Emacs, Dependencies, Installation
179
@subsection MS Windows
180
DVC requires a POSIX shell, used to run the backends. On Unix-like
181
systems, @file{/bin/sh} should be good. On MS Windows, you will need
182
to install one. MinGW and Cygwin both work; other POSIX shells are
183
also available.
184
185
For MinGW, see @url{http://mingw.org/}, and see
186
@url{http://www.venge.net/mtn-wiki/BuildingOnWindows} for excellent
187
installation instructions.
188
189
For Cygwin, see @url{http://cygwin.com/}.
190
191
Both MinGW and Cygwin work better with native MS Windows Emacs if
192
installed to @file{c:/} instead of @file{c:/MinGW} or
193
@file{c:/Cygwin}. This is because of the way they mount filesystems,
194
and refer to files not under a mounted directory.
195
196
For example, if Cygwin is installed at @file{c:/Cygwin}, it mounts
197
@file{/} at @file{c:/Cygwin}. Then the file known to Emacs as
198
@file{c:/Cygwin/bin/make.exe} is known to Cygwin applications as
199
@file{/bin/make.exe}. Also, the file known to Emacs as
200
@file{c:/Projects/my_file.text} is known to Cygwin as
201
@file{/cygdrive/c/Projects/my_file.text}. This causes problems when
202
using Cygwin make with native Emacs; Emacs can't find the files make
203
is reporting in error messages.
204
205
However, if Cygwin is installed at @file{c:/}, then it mounts @file{/}
206
at @file{c:/}. Then the file known to Emacs as @file{c:/bin/make.exe}
207
is known to Cygwin applications as @file{/bin/make.exe}. Also, the
208
file known to Emacs as @file{c:/Projects/my_file.text} is known to
209
Cygwin as @file{/Projects/my_file.text}. The only difference is the
210
leading drive letter, which is unnecessary, as long as all files are
211
on the same drive, which is typical of MS Windows boxes these days.
212
213
MinGW has similar file naming conventions.
214
215
The Cygwin installer warns that installing Cygwin at @file{c:/} is not
216
recommended. But if you read the rationale for that in the Cygwin
217
docs, it is because ``you might have other things installed there that
218
conflict''. While true, that is up to you to control. For example, you
219
certainly cannot install @emph{both} Cygwin and MinGW at @file{c:/}.
220
221
In general, a backend used by DVC should be run by invoking a Windows
222
executable, not a DOS batch file or other script. The Emacs variable
223
@code{explicit-shell-file-name} may help in resolving shell issues.
224
225
@c ----------------------------------------------------------------------------
226
@node Hooking into GNU Emacs, , MS Windows, Installation
227
@subsection Hooking into GNU Emacs
228
@cindex Hooking into GNU Emacs
229
230
(There is nothing to do for XEmacs users here, just start using
231
@b{DVC}, i.e. goto @pxref{DVC Tla Tour})
232
233
If you are reading this document the installation of files and setting
234
up the @code{load-path} and @code{Info-directory-list} was already
235
successful and you just need to load @b{DVC} now.
236
237
If auto-loading was built correctly you may start with @code{M-x
238
tla-archives RET}.
239
240
In order to load @b{DVC} on Emacs start up you should include the following
241
form in your Emacs configuration file, e.g. @code{~/.emacs.el}:
242
243
@example
244
@code{(load-file "/path/to/dvc/builddir/dvc-load.el")}
245
@end example
246
247
Alternatively, you can set your load-path and load the autoload files
248
manually with
249
250
@example
251
@code{(require 'dvc-autoloads)}
252
@code{(add-to-list 'load-path "/path/to/dvc/lisp/")}
253
@end example
254
255
This will set up @b{DVC}.
256
257
@c ============================================================================
258
@node DVC Tla Tour, Use cases, Installation, Top
259
@section DVC Tla Tour
260
261
This section discusses the basics of @b{DVC} - an overview of the
262
available commands.
263
264
@menu
265
* A tutorial guide to DVC::
266
* First contact:: DVC is self documented
267
* Tla Archive Browsing:: The basics of tla archive browsing
268
* Editing Files:: Inserting tags, adding change logs
269
* Committing Files:: How to commit your changes
270
* Using Bookmarks:: Working in a team
271
* Transmit patches via email:: Send/apply patches via Gnus
272
@end menu
273
274
275
@c ----------------------------------------------------------------------------
276
277
@node A tutorial guide to DVC, First contact, DVC Tla Tour, DVC Tla Tour
278
@subsection A tutorial guide to DVC
279
280
The following sections present a step-by-step tutorial guide to using
281
DVC for some common tasks: registering an archive, bookmarking an
282
existing project, creating your own local branch, getting a working
283
tree, merging patches from the main branch and committing changes to
284
your tree.
285
286
For the purposes of this tutorial, we will use the DVC project as an
287
example of a project you might like to track (humour me).
288
289
@menu
290
* Register an tla archive::
291
* Bookmarking a project::
292
* Creating a branch of a project and getting a project tree::
293
* Finding and merging missing patches::
294
* Reviewing and committing your changes::
295
@end menu
296
297
@node Register an tla archive, Bookmarking a project, A tutorial guide to DVC, A tutorial guide to DVC
298
@subsubsection Register an tla archive
299
300
The first step in tracking a project's development is to register its
301
archive in your archive list. You can do this by starting the archive
302
browser (@kbd{C-x V A}) and typing @kbd{a r} to register a new archive.
303
DVC's archive location is currently
304
@url{http://www-verimag.imag.fr/~moy/arch/public/}, and the default
305
value for the archive name will be fine. Having done this, you should
306
now see the newly-registered archive listed.
307
308
@ifhtml
309
@ifset SHOW_IMAGES
310
@html
311
<img src="archives.png">
312
@end html
313
@end ifset
314
@end ifhtml
315
316
@node Bookmarking a project, Creating a branch of a project and getting a project tree, Register an tla archive, A tutorial guide to DVC
317
@subsubsection Bookmarking a project
318
319
The normal usage of DVC is to create a bookmark for each version of a
320
project you are currently interested in. Much of the arch's
321
functionality is available from the bookmarks buffer, and it is one of
322
the primary entry points for DVC.
323
324
To track DVC's development, you will most likely want to add a bookmark
325
for its main development line. You can do this by entering the
326
bookmarks buffer (@kbd{C-x V b}) and adding a new bookmark with (@kbd{a
327
b}, or ``add bookmark''). You should be prompted for a version name,
328
and you can use tab completion to enter
329
@code{Matthieu.Moy@@imag.fr--public/dvc--main--0}. You can give your
330
bookmark any name you like.
331
332
Pressing @kbd{RET} on your newly-added bookmark will show you a revision
333
list for that version. You can use this list to browse archive logs
334
(@kbd{RET} again), view changesets (@kbd{=}) and various other tasks.
335
336
337
@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
338
@subsubsection Creating a branch of a project and getting a project tree
339
340
Having created a bookmark for the DVC project, you are ready to create
341
your own branch. Again from the bookmarks buffer (@kbd{C-x V b}), move
342
the point to your bookmark for DVC and hit @kbd{M T}. You will be
343
prompted for the tag version to be created for your new branch. Put the
344
branch somewhere in your default archive (I put mine in
345
@code{mark@@dishevelled.net--2003-mst/dvc--main--0.1}.) This will
346
create a tag of the main DVC project in your own archive and add a
347
bookmark for it.
348
349
Your newly-added bookmark will be marked as a ``partner'' of your main
350
DVC bookmark. This records the fact that the two projects are related
351
so that DVC can show you which patches from the DVC mainline are
352
missing from your local tree, and other useful stuff (more on this
353
later).
354
355
At this point, you will probably want to get a project tree for your new
356
branch. You can do this by moving your point to its bookmark in the
357
bookmark buffer, and hitting @kbd{>}. You will be prompted for a
358
directory in which to place the project tree, and the revision to get
359
(the default is fine in this case). Once the project tree has been
360
fetched, it will be automatically opened in dired.
361
362
@ifhtml
363
@ifset SHOW_IMAGES
364
@html
365
<img src="bookmarks.png">
366
@end html
367
@end ifset
368
@end ifhtml
369
370
371
@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
372
@subsubsection Finding and merging missing patches
373
374
Before you start making changes, it is a good idea to see if any new
375
patches have been added to the mainline since you last checked. DVC is
376
particularly good at doing this.
377
378
Start by entering the bookmarks buffer (@kbd{C-x V b}), move your point
379
to the bookmark of your DVC branch and hit @kbd{M m}. A
380
@code{*tla-missing*} buffer should appear, and show any patches that are
381
in the mainline but not in your tree.
382
383
@ifhtml
384
@ifset SHOW_IMAGES
385
@html
386
<img src="missing.png">
387
@end html
388
@end ifset
389
@end ifhtml
390
391
To merge all missing patches from the DVC mainline into your project
392
tree, move your point to the DVC mainline partner entry and hit @kbd{M
393
s}. You will be prompted for the path of your local project tree, and
394
after the patches have been merged a changes buffer should be displayed.
395
396
If you don't want to merge all the missing patches, you can leave off
397
the @kbd{M} prefix. For example, @kbd{r} will replay only the revision
398
under the point (allowing you to cherry-pick patches), and @kbd{s} will
399
star-merge all missing patches up to the patch under the point.
400
401
402
@node Reviewing and committing your changes, , Finding and merging missing patches, A tutorial guide to DVC
403
@subsubsection Reviewing and committing your changes
404
405
After making changes to your project tree, you are ready to commit. You
406
can review your changes by typing @kbd{C-x V =} from within your project
407
tree, and a @code{*tla-changes*} buffer should appear with diff output.
408
Before committing, you might also like to tree-lint your local tree by
409
hitting @kbd{C-x V l} (but this is done automatically if @code{tla
410
changes} fails and suggests a @code{tree-lint}).
411
412
@ifhtml
413
@ifset SHOW_IMAGES
414
@html
415
<img src="changes.png">
416
@end html
417
@end ifset
418
@end ifhtml
419
420
Once you are satisfied with your changes, you can create a log file by
421
hitting @kbd{C-x V c} (or simply @kbd{c} from your @code{*tla-changes*}
422
buffer). Many users prefer to write their log file incrementally, and
423
you can always save this file and hit @kbd{C-x V c} to return to it
424
later. You can also add a ChangeLog-style entry by hitting @kbd{C-x V
425
a} from the project tree file you are currently visiting.
426
427
@ifhtml
428
@ifset SHOW_IMAGES
429
@html
430
<img src="log.png">
431
@end html
432
@end ifset
433
@end ifhtml
434
435
To commit your changes, type @kbd{C-c C-c} from your log buffer.
436
437
438
@node First contact, Tla Archive Browsing, A tutorial guide to DVC, DVC Tla Tour
439
@subsection First contact
440
441
@b{DVC} is self documented, so this manual will be very short. We suppose
442
you understand tla basics.
443
444
There is a @b{DVC} entry in the tools menu which is a good starting
445
point, and an "Tla-..." menu in most @b{DVC}-related modes. Once you
446
have learnt the keyboard shortcuts, you will not need the menus anymore.
447
448
The most important commands have global keybindings. The prefix is
449
@kbd{C-x V} by default. Type @kbd{C-x V C-h} for a list. In each
450
@b{DVC} specific buffer, other (shorter) keyboard shortcuts are
451
available. @kbd{C-h m} will give you a list.
452
453
To get help about a tla command, @kbd{C-x V h command RET} will show
454
you the output of @code{tla command -H}. Since DVC is nothing more
455
than a wrapper around tla, this is a very good way to get help !
456
457
Before starting, you will need to set your ID if you have not already
458
done so.
459
460
You can execute the following command to set your id:
461
462
@kbd{C-u M-x tla-my-id} (or @kbd{M-x tla-set-my-id RET})
463
464
To check your id, call the same command without a prefix argument:
465
466
@kbd{M-x tla-my-id}
467
468
@c ----------------------------------------------------------------------------
469
@node Tla Archive Browsing, Editing Files, First contact, DVC Tla Tour
470
@subsection Tla Archive Browsing
471
472
It is pretty intuitive, just type @kbd{C-x V A} and investigate the
473
menu bar (Hmm, many people usually deactivate the menu bar, but please,
474
enable it while learning DVC ;-) You'll remove it afterwards) and the
475
mode help by @kbd{C-h m}.
476
477
If you have no archives registered yet, type @kbd{a r} and provide the
478
location of an archive.
479
480
@c ----------------------------------------------------------------------------
481
@node Editing Files, Committing Files, Tla Archive Browsing, DVC Tla Tour
482
@subsection Editing Files
483
484
Adding new files can be done in two ways:
485
486
@enumerate
487
488
@item Add an arch-tag to the file, by typing @kbd{C-x V t}. Attention,
489
files used as templates (@code{Makefile.in}) should be added explicitly
490
instead of using arch-tag lines.
491
492
@item Explicitly add it from the inventory view. Type @kbd{C-x V i},
493
mark the new files by typing @code{m} and finally add them by typing
494
@kbd{a}.
495
496
@end enumerate
497
498
You are encouraged to add log entries while you are editing. Type
499
@kbd{C-x V a} add your notes.
500
501
@c ----------------------------------------------------------------------------
502
@node Committing Files, Using Bookmarks, Editing Files, DVC Tla Tour
503
@subsection Committing Files
504
505
@enumerate
506
@item First review your changes by typing @kbd{C-x V =}.
507
508
If your tree contains nested trees, then DVC will display the list of
509
nested trees at the top of the changes buffer. They are marked with a
510
@kbd{T} so that you can distinguish them from the modified files.
511
While computing, they have the status @code{?}, and this becomes
512
@code{M} (resp. @code{-}) when the recursively called @code{tla}
513
process exits if there are some changes (resp. no changes) in the
514
nested tree.
515
516
To view the details of the changes, type @kbd{RET} on a nested tree
517
entry to open the corresponding changes buffer. To come back to the
518
root of the project, type @code{^}.
519
520
@item Then review the log message by typing @kbd{c} within the
521
*tla-changes* buffer and edit it when needed.
522
523
@item Finally commit by typing @kbd{C-c C-c}.
524
@end enumerate
525
526
527
If you want to commit only changes made to a given number of files,
528
select them with @kbd{m} in the *tla-changes* buffer (this also works from
529
the *tla-inventory* buffer) before typing @kbd{c}. The list of files used
530
for the selected files commit is the list of selected files in the
531
buffer in which you typed @kbd{c}, at the time you press @kbd{C-c C-c} to
532
commit. So, if you change your mind, you can go back and select/unselect
533
some files before committing.
534
535
@c ----------------------------------------------------------------------------
536
@node Using Bookmarks, Transmit patches via email, Committing Files, DVC Tla Tour
537
@subsection Using Bookmarks
538
539
@cindex Working in a project
540
@cindex Finding missing patches
541
542
@menu
543
* Bookmarks basics::
544
* Using bookmarks for distributed development::
545
* Bookmarks groups::
546
@end menu
547
548
@node Bookmarks basics, Using bookmarks for distributed development, Using Bookmarks, Using Bookmarks
549
@subsubsection Bookmarks basics
550
551
Bookmarks are primarily used to keep a list of the most visited arch
552
locations. Type @kbd{C-x V b} will show you the bookmarks
553
buffer. It should be empty for now, but you can add some by typing @kbd{a}.
554
555
Ah, it's a pain, you have to type the full location, like
556
@code{Matthieu.Moy@@imag.fr--public/dvc--main--0.1}, or just
557
@code{Matthieu.Moy@@imag.fr--public/dvc--main}. No, let's do it the
558
easy way: Go back to your archive list (@kbd{M-x tla-archives RET}),
559
select the archive you want, then the category, branch, version. Now,
560
just select Set a bookmark here in the menu, type the name, and that's
561
it!
562
563
You can view the details of bookmarks with @kbd{t}.
564
565
@node Using bookmarks for distributed development, Bookmarks groups, Bookmarks basics, Using Bookmarks
566
@subsubsection Using bookmarks for distributed development
567
568
Arch makes distributed development easy. Once you know that someone
569
has a patch for you in their archive, you can very easily merge it
570
with tla star-merge, or tla apply-changeset. But when several
571
developers are working on the same project, it's a pain to check
572
manually the missing patches in each archive.
573
574
OK, we've got what you need!
575
576
Add your own projects, and your contributors' projects too. Select
577
several related projects with @kbd{m} (unselect with @kbd{u} or
578
@kbd{M-del}). Make them partners with @kbd{M-p}. Now, with your cursor on
579
a bookmark, view the uncommited changes, the missing patches from your
580
archive and from your contributors with @kbd{M}. From this list, you
581
will usually want to update your tree if some changesets are missing
582
from your own archive (This is the @kbd{M u} keybinding), or star-merge
583
from your contributors' archives (This is the @kbd{. S} keybinding).
584
585
In this list, DVC will also highlight revisions not merged by other
586
revisions. You can navigate through them with @kbd{N} and @kbd{P}. It
587
is recommended to merge these patches first, because merging a
588
revision A, and later merging a revision B which is a merge of A often
589
results in conflicts.
590
591
Note that if you want to share your list of partners with all the
592
people having access to the project, you can just type @kbd{f w} to
593
write the list of parthers to the file
594
@code{@{arch@}/=partner-versions}, and your partners will just have to
595
type @kbd{f r} to read the list from this file. Note that using this
596
file, you will also be able to share your partner list with @code{aba}
597
users, and potentially others in the future.
598
599
If you are managing several projects at the same time (or one real
600
project and several personal configuration directory), select several
601
bookmarks with @kbd{m}, and type @kbd{M} to view all the missing
602
patches from all contributors.
603
604
The idea is that you will usually want to leave your office in the
605
evening with an empty list here, and check for new items when you come
606
back in the morning.
607
608
@node Bookmarks groups, , Using bookmarks for distributed development, Using Bookmarks
609
@subsubsection Bookmarks groups
610
611
Each bookmark can belong to a group of bookmarks. To make a group,
612
select some bookmarks, and hit @kbd{a g}. Enter a group name. The
613
selected bookmarks now belong to this group. To select a group, hit
614
@kbd{* g} and enter the group you want to select.
615
616
Developers will typically have one group for all the projects he or she
617
has write access to (for example, group @code{mine}), and one group of
618
bookmarks for each projects, including his partners' projects (I have a
619
group @code{dvc}). Then, pressing @kbd{* g mine RET M} will show me all
620
the missing patches for my projects. @kbd{* g dvc RET M} will tell me if my
621
partners for @code{dvc} are up-to-date with my archive.
622
623
@c ----------------------------------------------------------------------------
624
@node Transmit patches via email, , Using Bookmarks, DVC Tla Tour
625
@subsection Transmit patches via email
626
627
This section discusses a way to send/receive patches via email. That way
628
you can create patches for a project without the need to create a branch
629
for your contribution.
630
631
@menu
632
* Send patches via Gnus::
633
* Receive/Apply patches via Gnus::
634
@end menu
635
636
@node Send patches via Gnus, Receive/Apply patches via Gnus, Transmit patches via email, Transmit patches via email
637
@comment node-name, next, previous, up
638
@subsubsection Send patches via Gnus
639
640
When you are tracking a project via GNU Arch, you can just edit your
641
checked out working copy. When you have done that, just do @kbd{M-x
642
tla-submit-patch RET}.
643
644
That command calculates a changeset for your changes. That changeset is
645
archived in a tarball and attached to a new created email.
646
647
You can add a description of the changeset to the prepared email. After
648
you have entered your description, just send the mail.
649
650
The variable tla-submit-patch-mapping allows you to specify a list of
651
rules to preselect the destination email address.
652
653
The default setting for tla-submit-patch-mapping is here:
654
@code{(((nil "dvc" nil nil nil) ("dvc-el-dev@@gna.org" "dvc")))}
655
656
It defines, that every branch of the dvc project should submit patches
657
to @code{dvc-el-dev@@gna.org}. The entry @code{"dvc"} just specifies,
658
that the filename for the patch should start with @code{dvc}.
659
660
@node Receive/Apply patches via Gnus, , Send patches via Gnus, Transmit patches via email
661
@comment node-name, next, previous, up
662
@subsubsection Receive/Apply patches via Gnus
663
664
To hook DVC to Gnus, put the following in your .emacs:
665
@code{(tla-insinuate-gnus)}
666
667
Now the @kbd{K t} binding is available as prefix key in Gnus summary
668
buffers. This will also buttonize archives, categories, branches,
669
version and revision names in the @code{*article*} buffer.
670
671
The two important commands are:
672
@enumerate
673
@item @kbd{K t v}: View the changeset
674
@item @kbd{K t a}: Apply the changeset to one of your working trees
675
@end enumerate
676
677
You can predefine the working tree, where you want to apply certain kind
678
of patches via tla-apply-patch-mapping.
679
680
The follwing code specifies @code{"~/work/myprg/dvc-dev/"} as default
681
working tree for patches for the DVC project:
682
683
@code{(setq tla-apply-patch-mapping
684
'(((nil "dvc" nil nil nil) "~/work/myprg/dvc-dev/")))}
685
686
When you have applied the patch, you can commit the patch as usual. The
687
new keybinding @kbd{C-c C-p} inserts a log message that is extracted
688
from the received mail:
689
@enumerate
690
@item The subject is used as the patch summary line
691
@item The text between the log-start and the log-end markers in the mail specify the rest of the log message
692
@end enumerate
693
694
695
@node Use cases, Trouble Shooting, DVC Tla Tour, Top
696
@comment node-name, next, previous, up
697
@section How to use DVC depending on your role
698
699
@menu
700
* Anarchic development::
701
* Star-shaped development::
702
@end menu
703
704
705
@node Anarchic development, Star-shaped development, Use cases, Use cases
706
@comment node-name, next, previous, up
707
@subsection Using DVC for anarchy-style development
708
709
@comment TODO
710
711
@node Star-shaped development, , Anarchic development, Use cases
712
@comment node-name, next, previous, up
713
@subsection Using DVC for star-shaped development
714
715
By ``star-shaped development'', we mean a patch flow in which each
716
contributor only submit his patches to one version. This can be a
717
completely centralized solution, with one master version, or a
718
completely decentralized solution, with one master version for each
719
subprojects (potentially hierarchic), the main version for the full
720
project merging from the versions of the subprojects.
721
722
@menu
723
* Maintainer::
724
* Missing patches::
725
* Reviewing patches::
726
* Patch-log Generation::
727
* Contributor::
728
@end menu
729
730
@node Maintainer, Missing patches, Star-shaped development, Star-shaped development
731
@comment node-name, next, previous, up
732
@subsubsection Being a maintainer in a star-shaped development
733
734
We call ``maintainer'' the person in charge of merging patches from
735
contributors in his archive. In the case of a subproject, the
736
maintainer for a subproject is also a contributor for the main project.
737
738
DVC can help you in this task:
739
740
@menu
741
* Missing patches::
742
* Reviewing patches::
743
@end menu
744
745
@node Missing patches, Reviewing patches, Maintainer, Star-shaped development
746
@comment node-name, next, previous, up
747
@subsubsection Getting the list of missing patches
748
749
Unless merge requests are processed only on-demand, it is very usefull
750
to know the list of patches committed by your contributors that you
751
didn't merge already. This is done with the command @code{tla
752
missing}. Usually, there is a list of regular contributors from which
753
you often merge, and you may want to keep this list somewhere. In
754
DVC, the best way to do it is probably through bookmarks @xref{Using
755
bookmarks for distributed development}, but you can also use the
756
@code{@{arch@}/=partner-versions} (or the precious version
757
@code{@{arch@}/+partner-versions}) file for that: It is a list of
758
newline separated versions from which you often merge. The advantage
759
of this solution is that it is also implemented by aba and potentially
760
other tla front-ends in the future. Fortunately, you can keep it in
761
sync with your bookmarks from the bookmark buffer, with the key
762
sequences @kbd{f w} and @kbd{f r} (for respectively
763
@code{tla-bookmarks-write-partners-to-file} and
764
@code{tla-bookmarks-add-partners-from-file}).
765
766
You can also run @kbd{C-u M-x tla-missing RET} to view manually the
767
list of missing patches for a given version, off course, and you can
768
use the keybindings available in the name reading engine (Get the list
769
with @kbd{C-h}) to get quickly the fully qualified version name of a
770
contributor.
771
772
@node Reviewing patches, Patch-log Generation, Missing patches, Star-shaped development
773
@comment node-name, next, previous, up
774
@subsubsection Reviewing patches before merging them
775
776
A good maintainer should never merge patches blindly.
777
778
From a revision list buffer, @kbd{RET} will open the log file,
779
@kbd{=} will display the changeset.
780
781
If you are unsure about something, or whish to reject the patch, type
782
@kbd{M-x tla-revision-send-comments RET} to send a mail to the author
783
of the patch.
784
785
The usual way to merge is to put your cursor on the patch up to which
786
you want to merge, and type @kbd{. s} to ``star-merge'' the patches
787
from the common ancestor to this one. Other merge operators are
788
available. @kbd{C-h m} and the menubar will give you a list.
789
790
You can use ``sync-tree'' to reject a patch: After merging patches up
791
to the direct ancestor of the patch to be rejected, type @kbd{M-x
792
tla-revision-sync-tree RET}.
793
794
@node Patch-log Generation, Contributor, Reviewing patches, Star-shaped development
795
@comment node-name, next, previous, up
796
@subsubsection Generating patch-logs after merging
797
798
DVC can generate the log file automatically after a merge. Just try
799
@kbd{C-c C-m} in the log buffer. This will generate the body (using
800
@code{tla log-for-merge}), and a summary line is also generated. The
801
default format for the summary line should be good for a simple
802
contributor, but it is highy recommanded to change it if you are the
803
maintainer: The simplest way to do it is to set the
804
@code{summary-format} field for the bookmark corresponding to the
805
version you're managing (just type @kbd{s} on the bookmark of your
806
choice in the bookmark buffer). A typical value would be @code{" [%s]"}:
807
The generated summary line will then look like
808
809
@verbatim
810
Summary: [mark@dishevelled.net--2003-mst (patch 6-8)]
811
@end verbatim
812
813
That you can complete manually to something like
814
815
@verbatim
816
Summary: Bugfix for regression tests [mark@dishevelled.net--2003-mst (patch 6-8)]
817
@end verbatim
818
819
More customization can be done: see the docstring for the variable
820
821
@node Contributor, , Patch-log Generation, Star-shaped development
822
@comment node-name, next, previous, up
823
@subsubsection Being a contributor in a star-shaped development
824
825
@comment TODO
826
827
@c ============================================================================
828
@node Trouble Shooting, Customization, Use cases, Top
829
@section Trouble Shooting
830
831
Due to some reasons TLA might fail. In order to investigate the reason
832
you can switch to the buffers containing TLA output. Switch to the
833
@code{ *tla-logs} buffer (you can do that with
834
@code{tla-open-internal-log-buffer}). You get the list of processes
835
that have been ran since Emacs was started. Navigate with @kbd{n} and
836
@kbd{p}, and swith to the corresponding process buffer with @kbd{RET},
837
to the error buffer with @kbd{e}, and to the buffer from which the
838
process was started with @kbd{r}. Note that the process and output
839
buffers are killed after some time if the variable
840
@code{tla-number-of-dead-process-buffer} is non-nil. You also have a
841
@code{Tla-Buffers} menu item in the @code{DVC} menu, on in your
842
menu-bar on arch-related buffers to navigate between those.
843
844
If you encounter an internal lisp error, enable backtrace generation by
845
@kbd{M-x toggle-debug-on-error} and reproduce the error. Now submit a
846
bug report with @kbd{M-x dvc-submit-bug-report} and ensure the content
847
of the buffer @code{*Backtrace*} is included.
848
849
@c ============================================================================
850
@node Customization, Internals, Trouble Shooting, Top
851
@section Customization
852
853
Do a @kbd{M-x customize-group RET dvc RET} and browse the available
854
options and modify them to suite your needs.
855
856
@c ============================================================================
857
@node Internals, Mailing Lists, Customization, Top
858
@section Internals
859
860
There is a @code{docs} sub-directory in the archive of @b{DVC}
861
containing information for developers.
862
863
@c ============================================================================
864
@node Mailing Lists, Wiki, Internals, Top
865
@section Mailing Lists
866
867
There is one mailing list for @b{DVC}.
868
869
@code{dvc-dev@@gna.org} intended for the discussion of development
870
versions of @b{DVC}. Users of development versions of @b{DVC} should
871
subscribe to this list. Bugs should also be reported to this list.
872
873
See @xref{Known Bugs}. for instructions on submitting bug reports or
874
feature requests.
875
876
@c ============================================================================
877
@node Wiki, Changes, Mailing Lists, Top
878
@section The DVC Wiki
879
880
A wiki for DVC can be found at
881
882
@url{http://www.emacswiki.org/emacs/DistributedVersionControl}.
883
884
@c ============================================================================
885
@node Changes, The Latest Version, Wiki, Top
886
@section Changes in this Version
887
888
Development of DVC used to be very active, but has slowed down as the
889
users seem happy with the current version. The mailing list is a good
890
place learn about new features, but see also the docs/ANNOUNCEMENT file
891
in the DVC distribution.
892
893
@c ============================================================================
894
@node The Latest Version, The Future, Changes, Top
895
@section The Latest Version
896
897
@noindent
898
899
Get the bzr repository for @b{DVC}:
900
901
@code{# bzr get http://bzr.xsteve.at/dvc}
902
903
Users of development versions of @b{DVC} @b{should subscribe} to the
904
@code{dvc-el-dev} mailing list. @xref{Mailing Lists}.
905
906
@c ============================================================================
907
@node The Future, Thanks, The Latest Version, Top
908
@section The Future
909
910
The future consists of Bugs and Features.
911
912
@menu
913
* Known Bugs:: Known Bugs, and how to submit new ones
914
* TODO List:: The TODO List
915
@end menu
916
917
@c ----------------------------------------------------------------------------
918
@node Known Bugs, TODO List, The Future, The Future
919
@subsection Known Bugs
920
921
@enumerate
922
@item Please file one, that should be listed here!
923
@end enumerate
924
925
Bugs should be submitted to the @code{dvc-el-dev} mailing list
926
(@pxref{Mailing Lists}). To assist the developers, please include the
927
version numbers of DVC and tla and how to reproduce the bug. Further
928
the content of process buffers or in case of a lisp error a backtrace
929
might be helpful, see @xref{Trouble Shooting}. on how to get it.
930
931
Please use @kbd{M-x dvc-submit-bug-report RET} for submitting or at least
932
to get a template for the report which you copy to your favorite MUA.
933
934
@c ----------------------------------------------------------------------------
935
@node TODO List, , Known Bugs, The Future
936
@subsection TODO List
937
938
@subsubheading Near Future
939
940
@itemize @bullet
941
@item many bug fixes
942
@end itemize
943
944
@subsubheading Not-So-Near Future
945
946
@itemize @bullet
947
@item no need for a command line invocation of @code{tla}.
948
@end itemize
949
950
@c ============================================================================
951
@node Thanks, Concept Index, The Future, Top
952
@section Thanks
953
954
@c ============================================================================
955
@node Concept Index, Variable Index, Thanks, Top
956
@section Concept Index
957
@printindex cp
958
959
@c ============================================================================
960
@node Variable Index, , Concept Index, Top
961
@section Variable Index
962
@printindex vr
963
964
@contents
965
@bye
Loggerhead is a web-based interface for Breezy
Version: 2.0.1