Initial Commit

[packages] / xemacs-packages / patcher / doc / patcher.texi

\input texinfo

@c patcher.texi --- Patcher documentation

@c Copyright (C) 2012 Didier Verna.
@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011 Didier Verna.

@c Author:        Didier Verna <didier@xemacs.org>
@c Maintainer:    Didier Verna <didier@xemacs.org>
@c Created:       Sun Apr 21 21:34:06 2002
@c Last Revision: Mon Jan 16 11:28:06 2012

@c This file is part of Patcher.

@c Patcher is free software; you can redistribute it and/or modify
@c it under the terms of the GNU General Public License version 3,
@c as published by the Free Software Foundation.

@c Patcher is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.

@c You should have received a copy of the GNU General Public License
@c along with this program; if not, write to the Free Software
@c Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


@c Commentary:

@c Contents management by FCM version 0.1.


@c %** start of header
@setfilename patcher.info
@settitle Patcher
@setchapternewpage odd
@setcontentsaftertitlepage
@dircategory Emacs
@direntry
* Patcher: (patcher). Automatic maintenance of RCS-based projects.
@end direntry
@c %** end of header


@c ====================================================================
@c Definitions
@c ====================================================================
@set VERSION 4.0

@macro copyrightdate
Copyright @copyright{} 2010, 2011, 2012 Didier Verna.@*
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007, @c
2008, 2009 Didier Verna.
@end macro

@macro etc
@i{etc.}
@end macro

@c Subproject options index
@macro spoindex{name}
@cindex Subproject Option, @t{:\name\}
@cindex @t{:\name\} (subproject option)
@end macro

@c Project option index
@macro poindex{name}
@cindex Project Option, @t{:\name\}
@cindex @t{:\name\} (project option)
@end macro

@c Fallbacked project option index
@macro fpoindex{name}
@poindex{\name\}
@vindex patcher-default-\name\
@end macro

@c Built-in theme index
@macro bitindex{name}
@cindex Built-in Theme, @t{\name\}
@cindex Theme, Built-in, @t{\name\}
@cindex @t{\name\} (built-in theme)
@end macro

@c Built-in RCS theme index
@macro birtindex{name}
@bitindex{\name\}
@bitindex{\name\-ws}
@end macro



@c ====================================================================
@c Copyright
@c ====================================================================
@ifinfo
This file contains the documentation for Patcher version
@value{VERSION}, an XEmacs package for automating the maintenance of
RCS-based projects.

@copyrightdate{}

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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and 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 Free Software Foundation.
@end ifinfo



@c ====================================================================
@c Title Page
@c ====================================================================
@titlepage
@title Patcher
@subtitle Automatic maintenance of RCS-based projects from within XEmacs
@subtitle Version @value{VERSION}
@author Didier Verna <@email{didier@@xemacs.org}>
@page
@vskip 0pt plus 1filll
@copyrightdate{}


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 also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and 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 Free Software Foundation.
@end titlepage



@c ====================================================================
@c Master menu
@c ====================================================================
@ifnottex
@node Top, Copying, , (dir)
@top Patcher

Patcher is an XEmacs package designed to automate and ease the
maintenance of RCS-based projects. It provides assistance in building,
submitting and committing patches, as well as in handling the
corresponding ChangeLog entries, for example by creating skeletons.

This info file documents Patcher version @value{VERSION}.

@menu
* Copying::            The GNU General Public License
* Introduction::       What Patcher is all about
* Installation::       How to get and install Patcher
* Quick Start::        For the brave and the impatient
* User Manual::        A step-by-step guide to using Patcher
* XEmacs Development:: An XEmacs specific sample setup
* Indexes::            Concept, Variable, Function and Keystroke
@end menu

Patcher is developed by Didier Verna @email{didier@@xemacs.org}.

@end ifnottex



@c ====================================================================
@c Copying
@c ====================================================================
@node Copying, Introduction, Top, Top
@unnumbered Copying

Patcher is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License version 3,
as published by the Software Foundation.

Patcher is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.



@c ====================================================================
@c Introduction
@c ====================================================================
@node Introduction, Installation, Copying, Top
@chapter Introduction

When a project becomes important in size, or when the development is
performed cooperatively by several people across the Internet, it is a
common practice to help maintaining it by using a revision control
system. Such tools (Git, Mercurial, Subversion, Darcs, CVS, PRCS to name
a few) usually work by maintaining a centralized or distributed project
archive (also called a repository) that keeps track of the history of
the changes, lets you develop different ``branches'' at the same time
and perform operations like merges between these different project
branches.

In such ``RCS-based'' maintenance models, making the project evolve
usually involves repeatedly the same few steps, some of which can be
tedious: you work on your local copy of the project; once you're
satisfied with your changes, you create a patch by diffing your local
copy against the project's archive; then (or progressively), you
construct the ChangeLog entries. Finally, you propose your changes by
sending a mail to the developers list with your patch and the ChangeLog
entries included, hoping that your proposition will be accepted. If
you're one of the maintainers, you will still probably send the message
to the list, simply announcing the modification, and immediately commit
the patch with an informative log message.

Patcher is an XEmacs package designed to automate this process. Patcher
can't work on the project for you. However, as soon as you give it some
basic knowledge on the project structure and repository, it can
automatically build a patch by comparing your local copy with the
repository, create ChangeLog entries, prepare a mail announcing the
changes, and even commit the patch for you with a informative log
message. All of this is done in just a few keystrokes. Additionally,
Patcher can perform some sanity checks, like verifying that your local
copy is up-to-date, that you did not forget some ChangeLog entries, that
the commit operation went well and so on.

If you're brave and impatient, and want to start using the basics of
Patcher as soon as possible, see @ref{Quick Start}. It is recommended to
read it anyway, since it gives an overview of how Patcher works. If you
know the basics and want a more detailed guide, see @ref{User Manual}.

Enjoy using Patcher!



@c ====================================================================
@c Installation
@c ====================================================================
@node Installation, Quick Start, Introduction, Top
@chapter Installation

@menu
* Distribution::                How to get Patcher
* Requirements::                What you need to get Patcher running
* Insinuation::                 How to plug Patcher into other libraries
@end menu


@c Distribution =======================================================
@node Distribution, Requirements, , Installation
@section Distribution

Patcher is a standard XEmacs package. As such, you can download and
install it directly from a running XEmacs session. The packages
interface is accessible from the @samp{Tools} menu or via @kbd{M-x
list-packages}). You may also manually download a tarball or use the
Mercurial repository. See
@uref{http://www.xemacs.org/Develop/packages.html} for more information.

Otherwise, Patcher is also distributed as a standalone package directly
from my website (a Git repository and tarballs are available), at
@uref{http://www.lrde.epita.fr/~didier/software/elisp/misc.php}. You
will also find different inlined versions of this documentation at that
place. For standalone installation instructions, please read the
@file{INSTALL} file in the distribution.


@c Requirements =======================================================
@node Requirements, Insinuation, Distribution, Installation
@section Requirements

Patcher currently works with XEmacs 21.4 or later. Patcher might also
have some other requirements, depending on how you use it:

@itemize @bullet
@item
If you let Patcher create ChangeLogs for you (@pxref{ChangeLogs
Handling}), you will need the @file{add-log} library from the
@file{xemacs-base} package, version 2.21 or later, installed on your
system.

@item
If you want to send mails from Patcher (@pxref{Mail Methods}), you will
need a mail user agent. Patcher currently supports @file{sendmail},
@file{message} and @file{Gnus} natively and through the
@file{compose-mail} interface. Other MUA might be partly supported when
used with @code{compose-mail}. Patcher will probably suffer from non
critical deficiencies in that case however (it will issue warnings).
@end itemize


@c Insinuation ========================================================
@node Insinuation, , Requirements, Installation
@section Insinuation

With a proper installation of Patcher (either way), you don't need any
special trickery in your @file{.emacs} file because all entry points to
the library should be autoloaded.

However, Patcher has the ability to hook into external libraries, but
won't do so unless requested. Currently, Patcher has hooks for Gnus
only. If you're using Gnus as your MUA, you might want to add the
following line to your @file{gnusrc} file:

@example
(patcher-insinuate-gnus)
@end example

This will add some facilities described along the text.



@c ====================================================================
@c Quick Start
@c ====================================================================
@node Quick Start, User Manual, Installation, Top
@chapter Quick Start

This chapter demonstrates the use of Patcher through a quick and basic
setup. Adapt the example as you wish. See also @ref{XEmacs Development}
for an XEmacs specific sample setup. Let's make some assumptions first:

@itemize @bullet
@item
You own a computer.
@item
You have the @file{add-log} library from the @file{xemacs-base} package,
version 2.21 or later, installed on your system.
@item
You're working on a Git project called SuperProj.
@item
Your local clone of the Git repository is located in
@file{/home/me/superproj}.
@item
You have commit access to this project.
@item
There is a mailing list for developers at
@email{superproj-devel@@superproj.org}.
@item
Your repository is up-to-date, but you've done some hacking in the
sources that you'd like to commit.
@item
Since you're lazy, you didn't write the ChangeLog entries yet.
@end itemize


@menu
* Setting up Patcher::     Making Patcher aware of your project
* Calling Patcher::        Preparing a patch and a message
* Filling the ChangeLogs:: Patcher only creates skeletons
* Filling the Message::    You should insert the ChangeLog entries
* Committing the Patch::   Applying your modifications to the archive
* Sending the Message::    Telling people about your modifications
@end menu


@c The Project Descriptor =============================================
@node Setting up Patcher, Calling Patcher, Quick Start, Quick Start
@section Setting up Patcher

The first thing to do is to make patcher aware of your ``SuperProj''
project. Put this in your @file{.emacs} file:

@lisp
(setq patcher-projects
        '(("SuperProj" "/home/me/superproj"
        :to-address "superproj-devel@@superproj.org"
        :commit-privilege t
        :themes (git))))
@end lisp

@cindex Project Descriptor
@cindex Descriptor, Project
@vindex patcher-projects
As you can imagine, @code{patcher-projects} is a user option in which
you store information about the projects you want to manage with
Patcher. It is actually a list of what's called @dfn{project
descriptors}. Here's the meaning of the only project descriptor we have
in the example above: we have a project named ``SuperProj'', located in
@file{/home/me/superproj} and for which emails should be sent to
@email{superproj-devel@@superproj.org}. In addition to that, this
project is handled by Git.

@cindex Project Option
@cindex Theme
Note the particular syntax for specifying the mailing address. This is
what's called a @dfn{project option}. Contrary to the project's name and
directory, which are mandatory and always appear as the first and second
elements of a project descriptor, project options are optional and can
appear in any order. Note also that we have used a @code{:themes} option
for specifying the revision control system in use. A ``theme'' is a set
of options with particular values. Patcher happens to come with some
predefined themes, including one for Git.


@c Calling Patcher ====================================================
@node Calling Patcher, Filling the ChangeLogs, Setting up Patcher, Quick Start
@section Calling Patcher

Now you want to build a patch with your changes, and prepare a message
to submit them. The way Patcher works is currently to setup the message
first, and then to control all subsequent operations from there. In
other words, to create a patch, you actually ask Patcher to prepare a
mail. Type this:

@lisp
M-x patcher-mail
@end lisp

@findex patcher-mail
First, you're prompted (with completion) for a project name (the first
element of each project descriptor, remember?). We currently only have a
``SuperProj'' project, so hitting @kbd{TAB} will directly fill the
minibuffer in with this only choice. Then, you're prompted for a subject
line that will be used in the mail. Say something sensible here.

Three operations are now executed in turn:

@enumerate
@item
@fpoindex{to-address}@c
Patcher prepares a mail buffer. The message will be sent to the address
you specified with the @code{:to-address} project option, and the
subject line now reads ``[PATCH] something sensible here''.
@item
Patcher now builds the patch. The command used to do this is specified
in the Git theme, but it is a project option so it can be changed. Upon
successful completion of this command (we assume that's indeed the
case), the patch is inserted into the mail buffer. Some information
about the patch is provided just above it (the command used, the files
affected and so on).
@item
Finally, Patcher generates ChangeLog skeletons from what it understands
of the patch. This involves visiting the appropriate ChangeLog files,
and creating initial entries.
@end enumerate


@c Filling the ChangeLogs =============================================
@node Filling the ChangeLogs, Filling the Message, Calling Patcher, Quick Start
@section Filling the ChangeLogs

@findex patcher-mail-next-change-log
@findex patcher-change-log-next
@kindex C-c C-p n
Patcher has just created initial ChangeLog entries for you. You must now
browse through the ChangeLog file(s) and fill the entries as you see
fit. From the mail buffer type @kbd{C-c C-p n}
(@code{patcher-mail-first-change-log}). This command will bring you to
the first ChangeLog file that you need to fill in. From a ChangeLog
buffer, the same keyboard sequence will will bring you to the next one,
and so on (@code{patcher-change-log-next}).

@findex patcher-change-log-mail
@kindex C-c C-p m
Once you're done, you can very well save the ChangeLog buffers. However,
don't kill them! Don't even think about it. Patcher still needs them.
From any of the ChangeLog buffers you just filled in, type @kbd{C-c C-p
m} (@code{patcher-change-log-mail}). This will bring you back to the
mail buffer.


@c Inserting the ChangeLog entries ====================================
@node Filling the Message, Committing the Patch, Filling the ChangeLogs, Quick Start
@section Filling the message

Now that you're satisfied with your ChangeLog entries and you've
returned to the mail buffer, you want to write some explanation text in
the message. I'll let you do that. You also want to insert the ChangeLog
entries corresponding to your patch, since they are usually much more
readable than the patch itself.

@findex patcher-mail-insert-change-logs
@kindex C-c C-p l
Inserting your ChangeLog entries in the mail buffer is as simple as
typing @kbd{C-c C-p l} (@code{patcher-mail-insert-change-logs}). This
command places them just above the patch, with a short information line
(per ChangeLog file) on top.


@c Committing the Patch ===============================================
@node Committing the Patch, Sending the Message, Filling the Message, Quick Start
@section Committing the Patch

If you have commit access to your project, you should read this.
Otherwise, you may directly jump to @ref{Sending the Message}.

Committing your changes involves three steps: preparing the commit
command, preparing the commit log message, and actually committing the
changes. Although Patcher can do all of this in one shot, it gives you
control each step by default.

@findex patcher-mail-commit
@kindex C-c C-p c
In order to start the commit process, simply type @kbd{C-c C-p c}
(@code{patcher-mail-commit}). Congratulations. You've just been
transported to a new buffer, the ``log message'' buffer. This buffer
lets you edit the log message that will accompany your commit. Note that
the message is initialized with the subject line of your mail. This is
also a project option.

@findex patcher-logmsg-commit
@kindex C-c C-p c
@kindex C-c C-c
Once you're satisfied with the log message, type @kbd{C-c C-p c} or
@kbd{C-c C-c} (@code{patcher-logmsg-commit}). This command computes the
commit command to use, and while you think that you're done this time,
you're not quite there yet. Indeed, patcher transports you to yet
another buffer called the ``commit command'' buffer. This buffer lets
you modify, or at least check the commit command to use.

The default commit command is specified in the Git theme, but it is of
course a project option so it can be changed. Note that Patcher stores
the log message in a temporary file and uses the @option{-F} option of
the Git @samp{commit} command. Finally, note that Patcher has
automatically appended the affected ChangeLog files to the commit
command.

@findex patcher-cmtcmd commit
@kindex C-c C-p c
@kindex C-c C-c
If the commit command suits you, type @kbd{C-c C-p c} or @kbd{C-c C-c}
(@code{patcher-cmtcmd-commit}). This time, you're done. If you had not
previously saved the ChangeLog files, Patcher will do it for you just
before committing.

As Patcher doesn't do pushing (neither pulling) yet, you may now want to
push your changes to the remote repository by hand.


@c Sending the Message ================================================
@node Sending the Message, , Committing the Patch, Quick Start
@section Sending the Message

Sending the message has actually nothing to do with Patcher. It depends
on the method you use for sending mails, but will usually be done via a
@kbd{C-c C-c} command of some sort. On thing to note however: if you've
committed your changes via Patcher, the message has been slightly
modified: the subject line now reads ``[COMMIT] something sensible
here'' instead of ``[PATCH] something sensible here'', and a short
commit notice has been inserted just at the beginning of the message's
body.

That's it. That was easy. Congratulations on your first shot at Patcher,
anyway! Of course, Patcher is much more powerful and customizable than
what has been described in this chapter. For a complete documentation on
how to use and customize Patcher, please refer to @ref{User Manual}.



@c ====================================================================
@c User Manual
@c ====================================================================
@node User Manual, XEmacs Development, Quick Start, Top
@chapter User Manual

This chapter provides a step-by-step guide to using Patcher. Everything
there is to know about Patcher is here, though the features are
introduced progressively.

All user options that are going to be presented in this manual can be
found in the @code{patcher} customization group, or a subgroup of it.

@findex patcher-version
@kindex C-c C-p v
At any time, and in any buffer related to a Patcher project (mail,
ChangeLog @etc{}), you can query the current version of Patcher by
calling the function @code{patcher-version}, bound to @kbd{C-c C-p v}.

@menu
* Starting Up::         Patcher entry points
* Message Generation::  Specifying how a mail is to be constructed
* Patch Generation::    Specifying how a patch is to be constructed
* ChangeLogs Handling:: How Patcher behaves with respect to ChangeLogs
* Project Check In::    Committing your changes from Patcher
* Mail Sending::        Sending the message and cleaning up the place
* More On Commands::    Error handling and other generalities
@end menu

@ignore
The manual is currently organized in a rather sequential way: one
chapter for source patches, one for ChangeLogs. This might not be the
best way to do it. Another way is to split the information in terms of
patch/ChangeLog creation, and Patch/ChangeLog appearance in messages.
@end ignore


@c Starting Up ========================================================
@node Starting Up, Project Descriptors, User Manual, User Manual
@section Starting Up

Starting up Patcher implies first defining a project, and then calling
one of the entry point functions. This section describes how to do that.

@menu
* Project Descriptors::   The project specification mechanism
* Entry Points::          Ways to fire up Patcher
* Project Relocation::    Temporarily changing a project's directory
* Subprojects::           Working on a project subset
* Submodules::            Projects under projects
* Patcher Instances::     Working on several projects in parallel
@end menu

@node Project Descriptors, Entry Points, Starting Up, Starting Up
@subsection Project Descriptors

@cindex Project Descriptor
@cindex Descriptor, Project
@vindex patcher-projects
Projects specifications are stored in @code{patcher-projects}. This user
option is actually a list of @dfn{project descriptors}. Each project
descriptor has the following form: @samp{(@var{NAME} @var{DIR}
@var{:OPTION} @var{VALUE} @dots{})}

@itemize @bullet
@item
@var{NAME} is a string naming your project.
@item
@var{DIR} is a string specifying the directory in which to find the
project. It can also be set to @code{nil} in which case Patcher will
prompt you for the project's location every time it is needed (such
projects are called ``floating'' projects). This feature may be useful
when you maintain several clones of the same repository but want to
define it only once in Patcher. Another potential use of this is when
several independent projects happen to share exactly the same set of
options.
@item
@cindex Project Option
@fpoindex{to-address}@c
The remainder of a project descriptor is a sequence of zero or more
option/value pairs that we call @dfn{project options}. All option names
start with a colon. The type of a value depends on the corresponding
option. For example, there is a project option named @code{:to-address},
whose value should be a string giving the email address to which you
want to send Patcher messages.
@end itemize

When Patcher needs the value for a particular project option, it looks
for it directly in the project descriptor, but also in other places.
This process is described below.

@menu
* Themes::                 Collections of options
* Project inheritance::    Getting options from other projects
* Fallbacks::              Default values for project options
* Retrieval::              The process of getting an option's value
* Inheritance or theme?::  The proper way to factor out option values
@end menu

@node Themes, Project inheritance, , Project Descriptors
@subsubsection Themes

@cindex Theme
If you have several projects sharing the same option set, you might want
to setup a theme. Themes are named collections of project options.

@vindex patcher-themes
Themes are stored in the @code{patcher-themes} user option. This option
is a list of themes. Each theme has the following form:
@samp{(@var{NAME} @var{:OPTION} @var{VALUE} @dots{})}.

@var{NAME} is the theme's name (a symbol). The remainder of the list is
a sequence of zero or more option/value pairs, just like in project
descriptors.

@fpoindex{themes}@c
In order to use a theme in a given project, a @code{:themes} project
option is provided. It is a list of theme names (symbols). Use this
option in your project descriptor, and the project will implicitly
inherit all options from the corresponding theme.

One important note: as @code{:themes} is a project option, it can appear
in a theme. In other words, themes can inherit from other themes. When
Patcher tries to retrieve an option from a theme (an that option is not
directly available), the themes tree is traversed depth first.

@vindex patcher-max-theme-depth
Because themes can contain themes, a bogus setting might lead to an
infinite loop (a cycle in a theme graph). To prevent this, the
@code{patcher-max-theme-depth} user option is provided. It represents
the expected maximum theme nesting level and defaults to 8.

@cindex Built-in Theme
@cindex Theme, Built-in
@vindex patcher-built-in-themes
@birtindex{git}@c
@birtindex{hg}@c
@birtindex{darcs}@c
@birtindex{svn}@c
@birtindex{cvs}@c
@birtindex{prcs}@c
Patcher comes with a set of built-in themes for several revision control
systems. These are Git, Mercurial (Hg), Darcs, Subversion (Svn), CVS and
PRCS. Look at the value of @code{patcher-built-in-themes} to see what's
in them. Each of these themes have a @code{-ws} counterpart which
eliminates white-space differences in diff outputs. This comes in handy
if you are a committer (@pxref{Project Check In}) and you perform some
kind of automatic white-space cleanup in the files you edit, especially
when you let Patcher generate the ChangeLog entries (@pxref{ChangeLogs
Handling}).

@vindex pather-themes
While you can't modify the value of @code{patcher-built-in-themes},
you're free to do whatever you want in @code{patcher-themes},
including creating a theme with the same name as a built-in one. This
new theme will take precedence over the other. Having this built-in
variable (a constant, actually) lets me modify its value from release
to release without risking to smash your own adjustments.

@node Project inheritance, Fallbacks, Themes, Project Descriptors
@subsubsection Project inheritance

@cindex Project Inheritance
When two projects are very similar, you might prefer to use the project
inheritance mechanism described below over themes.

@poindex{inheritance}@c
There is a special project option called @code{:inheritance}. This
option must be a list of project names (strings). The inheritance of a
project defines a list of projects from which to inherit options.

One important note: inherited projects might have their own
@code{:inheritance} option set to other projects in turn. In other
words, the project inheritance can be more than one level deep. Just as
for themes traversal, when Patcher tries to retrieve an option and this
option is not available directly, the inheritance tree is traversed
depth first.

@vindex patcher-max-inheritance-depth
Because inherited projects can inherit from projects, a bogus setting
might lead to an infinite loop (a cycle in a project graph). To prevent
this, the @code{patcher-max-inheritance-depth} user option is provided.
It represents the expected maximum project inheritance level and
defaults to 8.

The @code{:inheritance} project option is somewhat special in the sense
that it can't appear in a theme. We will encounter other exceptions
later in this manual.


@node Fallbacks, Retrieval, Project inheritance, Project Descriptors
@subsubsection Fallbacks

@cindex Fallback
@fpoindex{to-address}@c
For each existing project option, Patcher also has a @dfn{fallback} user
option with a default value that would be shared among all projects not
setting the option explicitly. The name of the fallback is obtained by
replacing the colon in the project option's name with the prefix
@code{patcher-default-}. For example, the fallback corresponding to the
@code{:to-address} project option is named
@code{patcher-default-to-address}.

The @code{:inheritance} project option is also special in the sense that
it doesn't have a corresponding fallback. We will encounter other
exceptions later in this manual.

In the remainder of this manual, we will rarely mention the fallbacks
again. When we introduce a new project option, just remember that it
always has a corresponding fallback (well, not always, as you just
discovered).


@node Retrieval, Inheritance or theme?, Fallbacks, Project Descriptors
@subsubsection Retrieval

When Patcher needs the value of a particular project option, it looks
for it in the following manner:

@itemize @bullet
@item
First, it looks directly in the project descriptor to see if the option
is given.

@item
@fpoindex{themes}@c
@vindex patcher-themes
If that fails, it next tries the given themes, if any. This involves
recursively traversing the project's themes tree. Options successfully
retrieved in themes are said to be @dfn{themed}.

@item
@poindex{inheritance}@c
If that still fails, it then tries the inherited projects, if any. This
involves recursively traversing the project's inheritance tree. Options
successfully retrieved in inherited projects are said to be
@dfn{inherited}. Note that in turn, such options could have been
actually themed in the inherited project.

@item
If that fails again, it finally falls back to the value given in the
corresponding fallback (if it exists). In such a case, the option is
said to be @dfn{fallbacked}.
@end itemize

Note that a value of @code{nil} for a project option @strong{is an
actual value}. It is not equivalent to an option being unset. As a
consequence, if Patcher finds a project option with a value of
@code{nil} somewhere, it will use it and stop the search, even if a non
@code{nil} value could be retrieved later from a theme, an inherited
project or a fallback. This provides you with a way to annihilate
themed, inherited or fallbacked options.

The retrieval process is completely dynamic. In particular, this means
that even if you already have a running Patcher instance, you can still
modify the project's options, and these modifications will be taken into
account in your running instance. In fact, the only thing you can't do
with a running Patcher instance is modify the project's name.

Beware however that modifying an option while a corresponding project
has been instantiated is not very safe, and should be avoided as much as
possible.


@node Inheritance or theme?, , Retrieval, Project Descriptors
@subsubsection Inheritance or theme?

Let us summarize the four available ways to provide an option for a
project: a direct setting in the project descriptor, a global default
value in the fallback user option, plus themes and inherited projects.

At that point, you might be wondering why the themes and inheritance
concepts were both designed, since they actually perform very similar
tasks. Good question. Here is a good answer.

Projects might share options for different reasons. For example, my
``XEmacs'' (source) and ``XEmacs Packages'' projects share many options
(@code{To:} address, @code{From:} address, diff and commit commands and
so on) because they both relate to XEmacs. On the other hand I have
personal but totally unrelated projects that share the same commands
because they are all handled through a common system: Git.

In other words, you should rather use the inheritance mechanism when
projects relate to each other, and the theme mechanism for settings that
are orthogonal the projects they apply to.


@node Entry Points, Project Relocation, Project Descriptors, Starting Up
@subsection Entry Points

Patcher currently uses the mail buffers as ``master'' buffers for
controlling all operations: building a patch, creating the ChangeLog
entries, committing@dots{} all is done from the mail buffer. Note
however that you don't need to actually send mails to use Patcher
(@pxref{Fake Mail Method}).

To use Patcher on a certain project, you start by preparing a (possibly
fake) mail. There are several ways to do so: you could start a brand new
message, ``adapt'' a message already in preparation to Patcher, or even
compose some sort of a Patcher reply to another message.

@findex patcher-mail-kill
@kindex C-c C-p k
At any time from a mail buffer, you may change your mind and decide that
starting Patcher was a mistake. You can then call the function
@code{patcher-mail-kill}, bound to @kbd{C-c C-p k}, and Patcher will
``kill'' the current project, cleaning up the place like Patcher had
never existed before.

@menu
* Mail Creation::         Brand new messages
* Mail Adaptation::       Adapting existing messages
* Gnus Insinuation::      Using Gnus as your mail backend
@end menu

@node Mail Creation, Mail Adaptation, Entry Points, Entry Points
@subsubsection Mail Creation

Creating a message is done with the following function.

@defun patcher-mail
Start composing a brand new Patcher message. This function interactively
prompts you for the name of the project and for a (mail) subject line.
It also performs a global diff of your project.
@end defun


@node Mail Adaptation, Gnus Insinuation, Mail Creation, Entry Points
@subsubsection Mail Adaptation

Assuming that you are already editing a message (with your usual MUA),
you can adapt it to Patcher. This might be useful if you want to reply
to a normal message with a Patcher mail and your MUA is unknown to
Patcher (@pxref{Insinuation}). Start by creating the reply, and then
adapt it to Patcher.

@defun patcher-mail-adapt
Adapt an existing message to Patcher by prompting you for the name of a
project and possibly a new subject. This function also performs a global
diff of your project.
@end defun

@fpoindex{subject-rewrite-format}@c
When adapting a message to Patcher, you are always prompted for a new
subject line, although you can just hit @kbd{Return} to leave it empty.
If there is indeed a subject change (that is, if there is both an old
subject and a new one), Patcher uses a project option called
@code{:subject-rewrite-format} to modify the subject line. The subject
rewrite format is a string in which a @samp{%s} is replaced with the new
subject, while a @samp{%S} is replaced with the old one.

By default, the subject rewrite format is @samp{"%s (was: %S)"}. Note
that the subject prefix (@pxref{Message Customization}) is added in
front of the subject line @emph{after} the subject has been rewritten.


@node Gnus Insinuation, , Mail Adaptation, Entry Points
@subsubsection Gnus Insinuation

If you're using Gnus to read mail and have properly insinuated it
(@pxref{Insinuation}), Patcher offers different Gnus-like ways to answer
mails and adapt them to Patcher. All the functions below are available
from both the Gnus Summary and Article buffers.

@defun patcher-gnus-summary-followup
@kindex C-c C-p f
Compose a followup to an article, and adapt it to Patcher. This function
is bound to @kbd{C-c C-p f}.
@end defun

@defun patcher-gnus-summary-followup-with-original
@kindex C-c C-p F
Idem, but also cite the original article. This function is bound to
@kbd{C-c C-p F}.
@end defun

@defun patcher-gnus-summary-reply
@kindex C-c C-p r
Like @code{patcher-gnus-summary-followup}, but compose a reply. This
function is bound to @kbd{C-c C-p r}.
@end defun

@defun patcher-gnus-summary-reply-with-original
@kindex C-c C-p R
Idem, but also cite the original article. This function is bound to
@kbd{C-c C-p R}.
@end defun

@node Project Relocation, Subprojects, Entry Points, Starting Up
@subsection Project Relocation

Earlier (@pxref{Project Descriptors}), we talked about floating projects
(those having a null directory). There might also be times when you want
to temporarily relocate a non-floating project (for instance just this
once, without modifying the project descriptor). You can relocate a
project by calling any of the entry point functions with a prefix of 1
(@key{C-u 1}).

Since people have a tendency to keep clones under the same umbrella
directory, it seems convenient to start prompting you for the relocation
directory under the parent of the project's original directory. Patcher
does that.

As previously mentioned for floating projects (@pxref{Project
Descriptors}), an interesting side effect of relocation is that it
allows you to use one particular project descriptor for another,
completely independent project which would happen to use exactly the
same set of options.

@node Subprojects, Submodules, Project Relocation, Starting Up
@subsection Subprojects

@cindex Subproject
As mentioned before (@pxref{Entry Points}) the entry point functions all
perform a global diff of your project just after having prepared the
mail buffer. There might be times, however, when you want to work on a
project subset only (a specific set of files or directories), for
instance in order to commit only a few of the current changes. This
concept is know to Patcher as working on a ``subproject''.

A subproject is essentially defined by the project on which it is based,
an optional subdirectory in which the whole subproject resides and an
optional set of specific files to work on, in that subdirectory.

@b{Warning:} for technical reasons (and also because right now I don't
want to clutter Patcher's code too much with workarounds for deficient
RCSes), it is not possible to define Mercurial subprojects with a
specific subdirectory. This problem will go away when issue 2726 is
resolved (@uref{http://mercurial.selenic.com/bts/issue2726}).

When you provide an explicit set of files to work on, it is not
necessary (it is even forbidden) to specify the ChangeLog files. Patcher
will automatically find them for you. In other words, only specify
source files, not ChangeLog files.

Patcher offers to ways of working on subprojects: either temporarily or
by defining them in a permanent fashion.

@menu
* Temporary Subprojects::       Subprojects which are not permanent
* Permanent Subprojects::       Subprojects which are not temporary
@end menu

@node Temporary Subprojects, Permanent Subprojects, Subprojects, Subprojects
@subsubsection Temporary Subprojects

@cindex Temporary Subproject
@cindex Subproject, Temporary
In order to work on a temporary subproject, call any of the entry point
functions (@pxref{Entry Points}) with a simple prefix argument
(@key{C-u}). Patcher will then prompt you for an optional subdirectory
and for a specific set of files to work on, under that particular
subdirectory. There, you can in fact specify files as well as
directories, use wildcards, just as you would construct a shell command
line diff.

Note that since the files you provide can in fact be directories, you
can circumvent the Mercurial limitation mentioned above by @emph{not}
providing a specific subdirectory, but instead give it as a file at the
second prompt. This workaround also applies to permanent subprojects, as
described in the next section.


@node Permanent Subprojects, , Temporary Subprojects, Subprojects
@subsubsection Permanent Subprojects

@cindex Permanent Subproject
@cindex Subproject, Permanent
If you happen to work more than once on the same project subset, it will
quickly become annoying to have to specify explicitly the same
subdirectory and/or files over and over again. Consequently, Patcher
offers you a way to permanently define subprojects.

@menu
* Defining Subprojects::  Storing subprojects definitions
* Project Naming::     When different projects have the same name
* Command Directory::     For non local revision control systems
@end menu


@node Defining Subprojects, Project Naming, , Permanent Subprojects
@b{Defining Subprojects}

@cindex Subproject Descriptor
@cindex Descriptor, Subproject
@vindex patcher-subprojects
The user option @code{patcher-subprojects} stores a list of
@dfn{subproject descriptors}. A subproject descriptor is almost the same
as a project descriptor, with a few exceptions:

@itemize @bullet
@item
Instead of the project directory field (the second field in a project
descriptor), you rather specify the name of the project this subproject
is based on.

@item
@cindex Subproject Option
In addition to the standard project options we've already seen, two
subproject options are available:

@table @code
@item :subdirectory
@spoindex{subdirectory}@c
This lets you specify a subdirectory of the original project's directory
in which the whole subproject resides. This subdirectory must be
provided @emph{relative} to the original project's directory.

@item :files
@spoindex{files}@c
This lets you specify a list of files or directories composing the
subproject. Each file specification may be provided @emph{relative} to
the subdirectory above, if any, or to the original project's directory.
They may also contain wildcards.
@end table

Please note that these subproject options have no corresponding fallback
(that would be meaningless). They can't appear in a theme either.

@item
@poindex{inheritance}@c
Subprojects don't have an @code{:inheritance} mechanism. Instead, they
implicitly inherit from their base project (which in turn can inherit
from other projects).
@end itemize

Here are some important remarks about permanent subprojects:

@itemize @bullet
@item
Permanent subprojects are accessible in exactly the same way as normal
projects, that is, via the entry point functions (@pxref{Entry Points}).
A subproject @emph{is} a project, after all. Because of that, projects
and permanent subprojects can't share names. Patcher always looks for
subprojects first, and then regular projects.

@item
@spoindex{subdirectory}@c
@spoindex{files}@c
A subproject with neither a @code{:subdirectory} nor a @code{:files}
option is exactly the same as the base project, apart from project
options that you would override. This can hence be seen as an elegant
(or kludgy, depending on the viewpoint) way to define project
``variants''.

@item
Since Patcher doesn't really make a distinction between projects and
subprojects, it is possible to work on a temporary subproject based
itself on a subproject: simply call one of the entry point functions
with a simple prefix argument, and select a permanent subproject when
prompted. The effect is then to work on a subsubproject: you can specify
an optional subsubdirectory and override the set of files affected by
the patch.

@item
Finally, note that it is even possible to both relocate a project
@emph{and} work on a temporary subproject. In order to do that, use a
prefix argument of -1 instead of just 1 (@key{C-u -1}). And now, try to
imagine the brain damage that is caused by using a prefix of -1 and then
select a permanent subproject as the base project. The effect is to work
on a sub-sub-relocated project@dots{}.
@end itemize


@node Project Naming, Command Directory, Defining Subprojects, Permanent Subprojects
@b{Project Naming}

@vindex patcher-projects
@vindex patcher-subprojects
As you already know, Patcher distinguishes (sub)projects by their
@var{NAME} field in the @code{patcher-projects} and
@code{patcher-subprojects} user options. This name is meant to be
explicit and convenient for the user to read. However, some RCSes like
(the decidedly weird) PRCS require the @emph{actual} project name in
their commands. It would then be difficult to define project variants
for the same directory but with different names.

@fpoindex{name}@c
To remedy this problem, patcher provides a @code{:name} project option.
If set, it will be used by diff and commit commands instead of the
project's name when necessary. See @ref{Diff Command} for details on how
to do that.


@node Command Directory, , Project Naming, Permanent Subprojects
@b{Command Directory}

Most of the revision control systems out there can perform in any of the
project's subdirectories. For that and other technical reasons, Patcher
will normally execute all commands in the specified (sub)directory of
the specified (sub)project. This principle does not always hold however.
For example, PRCS (weird, did I mention it already?) can only work in
the project's root directory.

@fpoindex{command-directory}@c
If you want to define projects for which the revision control system can
be executed in only one directory, Patcher provides you with the
@code{:command-directory} project option (a string). This directory must
be provided relative to the project's directory (but note that it must
usually go upwards).

All commands (diff and commit ones) will be executed from there. Also,
note that the command directory does not change the way you might
specify files. Patcher modifies all needed paths automatically to handle
the command directory properly. This means that you should continue to
specify files relatively to the (sub)project's (sub)directory,
regardless of the existence of a command directory.

When needed, a command directory should always be specified in a project
(in which case it will most likely be the same as the project's
directory) and never in subprojects. Otherwise, temporary subprojects
would fail to get it.


@node Submodules, Patcher Instances, Subprojects, Starting Up
@subsection Submodules

@cindex Submodule
Related to the notion of subproject is that of ``submodule'' (or
``subrepo'') as some RCSes would put it. A submodule is a standalone
project that appears under another project (so it looks like a
subproject, only it isn't).

Normally, there is nothing special about submodules, in the sense that
if you want to handle them from Patcher, you would define them as
regular projects. However, there are ways to detect submodules
automatically, which can be very convenient if you have plenty of them
(this happens for XEmacs packages for instance).

Patcher currently knows how to detect submodules of Mercurial and Git
projects. The effect is to define new projects that inherit from the
umbrella project automatically, with their own name and directory, so
that you don't need to define them by hand.

@birtindex{git}@c
@birtindex{hg}@c
@fpoindex{submodule-detection-function}@c
@findex patcher-hg-detect-submodules
@findex patcher-git-detect-submodules
Automatic detection of submodules is controlled via the
@code{:submodule-detection-function} project option. Its value is a
symbol naming a function, or @code{nil} if you don't want autodetection.
The built-in Git and Mercurial themes set this option to
@code{patcher-hg-detect-submodules} and
@code{patcher-git-detect-submodules} respectively.

@findex patcher-detect-submodules
Submodules are detected automatically by scanning the value of
@code{patcher-projects} the first time you use Patcher in an XEmacs
session. If you further modify this variable, it may be needed to
recompute the list of known submodules. You can do this by calling
@code{patcher-detect-submodules} interactively.


@node Patcher Instances, , Submodules, Starting Up
@subsection Patcher Instances

The concept of subproject brings up the question of having Patcher
working on different patches at the same time. It is possible under some
conditions:

@itemize @bullet
@item
You can have as many simultaneous Patcher instances as you want on
projects that don't overlap.

@item
You can have as many simultaneous Patcher instances as you want on the
same project, as long as there is no overlapping between each
subproject. This means that you can't have source files, or even
ChangeLog files in common.

@item
It is also possible, to some extent, to work simultaneously on
overlapping instances of Patcher, although this is mostly uncharted
territory. More precisely, Patcher keeps track of which project(s) refer
to specific source or ChangeLog files, and knows how to associate a
particular ChangeLog entry with a particular project. However, Patcher
does not support interactive selection of patches (@`a la Darcs or Git)
yet, and if you commit one of two overlapping projects, you will most
likely need to rediff the other one.
@end itemize


@c Message Generation =================================================
@node Message Generation, Patch Generation, User Manual, User Manual
@section Message Generation

Patcher starts working on the project (by first creating
the patch) after the message is prepared. Because of this, we'll start
by reviewing the mail-related customizations you might want to setup.

@menu
* Mail Methods::          Using a particular mailer
* Message Customization:: Specifying initial contents for messages
@end menu

@node Mail Methods, Message Customization, Message Generation, Message Generation
@subsection Mail Methods

@fpoindex{mail-method}@c
Since there are different mail packages working in XEmacs, Patcher
supports different methods for preparing messages. You can specify the
method you prefer in the @code{:mail-method} project option. The value
must be a symbol.

@menu
* Standard Mail Methods:: Patcher supports standard mail packages
* Fake Mail Method::      Patcher supports not sending mails
* Other Mail Methods::    Patcher supports everything
@end menu

@node Standard Mail Methods, Fake Mail Method, Mail Methods, Mail Methods
@subsubsection Standard Mail Methods

Patcher currently supports @file{sendmail}, @file{message} and
@file{Gnus} natively and through the @file{compose-mail} interface.
Other MUA might be partly supported when used with @code{compose-mail}.
Patcher will probably suffer from non critical deficiencies in that case
however (it will issue warnings).

@table @code
@item compose-mail
@findex compose-mail
@findex patcher-mail-compose-mail
@vindex mail-user-agent
This is the default. It is implemented via the function
@code{patcher-mail-compose-mail} which calls @code{compose-mail} to
prepare the message. If you are not familiar with @samp{compose-mail},
you might also want to throw an eye to the user option
@code{mail-user-agent}. If your project does not specify an address to
send the message to (@pxref{Message Customization}), it is prompted for.

@item sendmail
@findex mail
@findex patcher-mail-sendmail
A direct interface to the @code{mail} function from the @code{sendmail}
package. It is implemented via the function
@code{patcher-mail-sendmail}. If your project does not specify an
address to send the message to (@pxref{Message Customization}), it is
prompted for.

@item message
@findex message-mail
@findex patcher-mail-message
A direct interface to the @code{message-mail} function from the
@code{message} library (it is part of @code{Gnus}). It is implemented
via the function @code{patcher-mail-message}. If your project does not
specify an address to send the message to (@pxref{Message
Customization}), it is prompted for.

@item gnus
@findex gnus-post-news
@findex patcher-mail-gnus
A direct interface to the @code{gnus-post-news} function from the
@code{Gnus} package (it can also send mails@dots{}). It is implemented
via the function @code{patcher-mail-gnus}. This mail method is
interesting when you maintain a special mail group for messages that you
send with Patcher, most probably because they are sent to some
mailing-list, such as @email{xemacs-patches@@xemacs.org}.

@fpoindex{gnus-group}@c
This method uses a Gnus group name and acts as if you had type @samp{C-u
a} on that group in the @code{*Group*} buffer, hence honoring the group
parameters and posting-styles. If your project does not specify a Gnus
group name (@pxref{Message Customization}), it is prompted for.
@end table

This last mail method is special in the sense that it requires a running
Gnus session to work. If that's needed, Patcher can start Gnus for you
in several ways, according to the following user options:

@table @code
@item patcher-mail-run-gnus
@vindex patcher-mail-run-gnus
If @code{nil}, Patcher will never start Gnus and abort the operation
instead. If @code{t}, Patcher will always start Gnus when needed. If
@code{prompt}, Patcher will ask you what (you want) to do. This is the
default behavior.

@item patcher-mail-run-gnus-other-frame
@vindex patcher-mail-run-gnus-other-frame
Used when Patcher has to start Gnus by itself. If @code{nil}, continue
using the current frame. If @code{t}, start Gnus in another frame (this
is the default). If @code{follow}, start Gnus in another frame, and use
this new frame to prepare the Patcher mail.
@end table

@node Fake Mail Method, Other Mail Methods, Standard Mail Methods, Mail Methods
@subsubsection Fake Mail Method

@findex patcher-mail-fake
At that point, you might be wondering why the mail method is a project
option and not simply a user option, since you probably only use one
mail agent at all. Right. But you might one day work on projects for
which you don't need to send messages at all. This could happen if you
start using Patcher on a project of your own for instance. For that
reason, there is a @code{fake} mail method available. It is implemented
via the @code{patcher-mail-fake} function and calls no particular mail
user agent. Once you type @kbd{C-c C-c} to virtually send the fake
message, it only performs some cleanup.

All right. But did we really need this fake method? I mean, one could
use the usual mail method, and simply not send the message in the end.
Huh, yeah, ok@dots{} Actually, it is very probable that in a future
release of Patcher, the mail buffer won't be the master buffer anymore,
and mail sending will be just another optional step in the process. In
that case, the mail method is likely to move away from project option
to standard user option.

@node Other Mail Methods, , Fake Mail Method, Mail Methods
@subsubsection Other Mail Methods

@fpoindex{mail-method}@c
If you're not satisfied with the provided mail methods (want a @code{vm}
one?), you can provide your own, more or less (patches welcome if you do
so). Here's what to do: set your @code{:mail-method} project option to,
say, @code{foo}, and write your own function which must be named
@code{patcher-mail-foo}.

This function must take two arguments (a project descriptor and a string
containing the subject of the message), and prepare a mail buffer. If
you want to do this, you should see how it's done for the built-in
methods.

Note that the mail adaptation facility won't be available for your
custom method. For that, you would have to hack the internals of
Patcher.


@node Message Customization, , Mail Methods, Message Generation
@subsection Message Customization

When preparing a message, Patcher can fill some parts of it for you.
Here's a list of mail-related project options.

@table @code
@item :user-name
@fpoindex{user-name}@c
The name (your name) to use when composing the message. It will affect
the @code{From:} header. This option is used by all mail methods but
@code{fake}. If not given, @code{user-full-name} is used.

@item :user-mail
@fpoindex{user-mail}@c
The mail (your mail) address to use when composing the message. It will
affect the @code{From:} header. This option is used by all mail methods but
@code{fake}. If not given, @code{user-mail-address} is used.

@item :to-address
@fpoindex{to-address}@c
The address to send messages to (a string). This option is used by all
mail methods but @code{gnus} and @code{fake}. If not given, it is
prompted for when calling @code{patcher-mail}.

@item :gnus-group
@fpoindex{gnus-group}@c
The Gnus group name to use for posting messages (a string). This option
is used only by the @code{gnus} mail method. If not given, it is
prompted for when calling @code{patcher-mail}.

Note that if you configured your name and mail in Gnus, for instance
through posting styles, these configurations take precedence over the
corresponding Patcher options.

@item :subject-prefix
@fpoindex{subject-prefix}@c
A prefix for the subject line of messages. It can be @code{nil} or a
string. By default, ``[PATCH]'' is used. This part of subjects is never
prompted for. The subject prefix understands @samp{%n} and @samp{%N}
substitutions. @xref{Diff Command}, and @ref{Project Naming} for more
information. Also, a space is inserted between the prefix and the
remainder of the subject, when appropriate.

@item :subject
@fpoindex{subject}@c
A default value for prompted subjects (a string). Please note that this
is used @strong{only} to provide a default value for prompted subjects.
Subjects are @strong{always} prompted for. The subject understands
@samp{%n} and @samp{%N} substitutions. @xref{Diff Command}, and
@ref{Project Naming} for more information.

@item :mail-prologue
A prologue to insert at the top of a message body (a string).
@end table

@c Patch Generation ===================================================
@node Patch Generation, ChangeLogs Handling, Message Generation, User Manual
@section Patch Generation

Patcher creates patches by diffing your local copy of the project
against the repository. This is done automatically after preparing a
message, so you shouldn't normally bother to do it manually. There are
however situations in which you need to diff your project again, for
instance if an error occurred during the initial diff (@pxref{More On
Commands}), or if you suddenly decided to further modify the source
files.

@findex patcher-mail-diff
@kindex C-c C-p d
The way to regenerate the patch manually is to call
@code{patcher-mail-diff} from the mail buffer. This function is bound to
@kbd{C-c C-p d} in this buffer.

When possible, Patcher also tries to check that your project is
up-to-date with respect to the archive, and will inform you otherwise.

In the remainder of this section, we describe the different ways to
customize the diff process and the appearance of its output.

@menu
* Diff Command::        Specifying the command to generate the patch
* Diff Headers::        Associating hunks with files
* Diff Line Filter::    Omitting lines from the diff output
* Diff Prologue::       A header is inserted above the patch
@end menu
@c #### NOTE: The after-diff hook feature is currently unused and not
@c documented.

By the way, (re)generating the patch does not necessarily mean that it
is directly inserted into the mail buffer. This also depends on the
ChangeLogs behavior (@pxref{ChangeLogs Handling}).

@node Diff Command, Diff Headers, Patch Generation, Patch Generation
@subsection Diff Command

@fpoindex{diff-command}@c
@findex patcher-mail
The diff command used to generate the patch is specified by the
@code{:diff-command} project option. You can also punctually change this
command by calling @code{patcher-mail-diff} with a prefix argument.
Patcher will then prompt you for a new command and use it exclusively
for this particular patch.

By the way, don't use the prefix argument of @code{patcher-mail-diff} as
a way to specify files (that is work on a subproject). It is not meant
for that. It is meant only to modify the diff command for this instance
only, not the files to which it applies.

The diff command is in fact a template string that supports dynamic
expansion for a set of special constructs. The following ones are
currently available.

@table @code
@item %n
@fpoindex{name}@c
A @samp{%n} will be replaced with the project's name, that is, either
the value of the @samp{:name} option (@pxref{Project Naming}) or the
name of the project descriptor. This may be useful in commands with
weird options syntax, like PRCS.
@item %N
If you want to use the project descriptor's name, regardless of the
value of the @code{:name} option, use @code{%N} instead of @code{%n}.
@item %f
A @samp{%f} will be replaced with explicitly diff'ed files and their
accompanying ChangeLog files if any, or will simply be discarded for a
global diff.
@item %?f@{STR@}
If there are explicitly diff'ed files, this construct will be replaced
by @samp{STR}. Otherwise, it will simply be discarded.
@item %!f@{STR@}
This is the opposite of the previous one: if there are explicitly
diff'ed files, this construct will be discarded. Otherwise, it will be
replaced by @samp{STR}.
@end table

@birtindex{git}@c
Here is an example to clarify this: the default diff command for Git in
the @samp{git} built-in theme (@pxref{Themes}) is the following:

@samp{git diff --no-prefix HEAD%?f@{ -- @}%f}

One important note: all diff commands in Patcher @strong{must} have a
@samp{%f} construct somewhere, even if you always perform global diffs
only (but in fact, you never really know that for sure). The reason is
that there are situations in which Patcher may need to diff specific
files, even for a global diff.

See also @ref{More On Commands} for cases where a diff command would
fail.

@node Diff Headers, Diff Line Filter, Diff Command, Patch Generation
@subsection Diff Headers

When Patcher generates a diff, it needs to associate every hunk with the
corresponding source file (and possibly with the corresponding ChangeLog
file as well). Unfortunately, different revision control systems might
generate different diff outputs, making this association difficult to
establish.

@fpoindex{diff-header}@c
Patcher provides a @code{:diff-header} project option to help. Its value
is of the form @code{(REGEXP NUMBER1 NUMBER2)}. @code{REGEXP} is used to
match the beginning of a diff output while NUMBER1 and NUMBER2 are the
parenthesized levels in which to find the corresponding old and new file
names.

When the change involves modifying a file's contents, the old and new
file names will be the same. However, they can be different in several
situations, like when a file is renamed, created or deleted. In case of
creation or deletion, some revision control systems use
``@code{/dev/null}'' to denote a virtual old or new file.

@vindex patcher-built-in-themes
If you want to see some examples, have a look at the built-in themes in
@code{patcher-built-in-themes} (@pxref{Themes}). They contain presets
for different revision control systems, along with suitable
@code{:diff-header} options.

Also, you should pay attention to the fact that the values of the
@code{:diff-header} and @code{:diff-command} options may depend on one
another to work properly. For instance, the diff output of Mercurial
looks different when you use the @code{--git} option.


@node Diff Line Filter, Diff Prologue, Diff Headers, Patch Generation
@subsection Diff Line Filter
When generating a global diff, that is, without specifying the files
affected by the patch explicitly, some uninformative lines might be
present in the output. A typical example occurs in CVS: it indicates
files present in your local copy but otherwise unknown to the server
with a question mark in diff outputs.

@fpoindex{diff-line-filter}@c
Patcher has a project option named @code{:diff-line-filter} that lets
filter out such unwanted lines. This must be a regular expression
matching a whole line. Caution however: do not put beginning or end of
lines markers in your regexp. Patcher will do it for you.

@node Diff Prologue, , Diff Line Filter, Patch Generation
@subsection Diff Prologue

Patcher can (and does) insert a special prologue just above a patch in
the message in preparation. This prologue gives information such as the
diff command used, the files affected and so on.

@fpoindex{diff-prologue-function}@c
@findex patcher-default-diff-prologue
The function used to generate this prologue can be specified with the
@code{:diff-prologue-function} project option. A value of @code{nil}
means don't insert any prologue. By default, the internal function
@code{patcher-default-diff-prologue} is used. If you want to provide
your own, here's how to do it.

Your function should take two mandatory arguments: @code{name} and
@code{kind}. @code{name} is the name of the project and @code{kind} is
the kind of diff. Possible values for the @code{kind} argument are:

@table @code
@item :sources
indicates a source diff only,
@item :change-logs
indicates a ChangeLog diff only,
@item :mixed
indicates a diff on both source and ChangeLog files.
@end table

Your function should also accept the following set of Common Lisp style
keyword arguments (take a look at the provided function if you don't
know how to do this). These arguments will be bound when appropriate,
according to the kind of diff being performed.

@table @code
@item source-diff
the command used to create a source diff,
@item change-log-diff
the command used to create a ChangeLog diff,
@item source-files
sources files affected by the current patch,
@item change-log-files
ChangeLog files affected by the current patch.
@end table

In the case of a mixed diff, a @code{nil} value for
@code{change-log-diff} indicates that the same command was used for both
the source and ChangeLog files.

Finally, your function should perform insertion at the current point in
the current buffer.


@c ChangeLog Handling =================================================
@node ChangeLogs Handling, Project Check In, Patch Generation, User Manual
@section ChangeLogs Handling

ChangeLogs management in Patcher involves two aspects: how ChangeLog
entries are created, and how they appear in the messages. Both aspects
can be customized beyond your craziest dreams.

@findex patcher-change-log-kill
@kindex C-c C-p k
It is possible to kill a project from a related ChangeLog file by using
the same binding as in the mail buffer: @kbd{C-c C-p k}
(@code{patcher-change-log-kill}).

@menu
* ChangeLogs Naming::     Are ChangeLogs called ChangeLogs?
* ChangeLogs Updating::   How Patcher deals with ChangeLogs
* ChangeLogs Navigation:: Browsing ChangeLog buffers
* ChangeLogs Appearance:: How ChangeLogs appear in messages
* ChangeLogs Prologue::   A header is inserted above the ChangeLogs
* ChangeLogs Status::     Getting rid of ancient technology
@end menu

@node ChangeLogs Naming, ChangeLogs Updating, ChangeLogs Handling, ChangeLogs Handling
@subsection ChangeLogs Naming

@fpoindex{change-log-file-name}@c
By default, Patcher thinks that ChangeLog files are named ``ChangeLog''.
That is very clever, but if for some obscure reason that is not the case
in your project, you can change this by setting the
@code{:change-log-file-name} project option (a string).

@ignore
Apart from changing Patcher's idea of ChangeLog file names, this option
has another interesting application: suppose you're working in a project
that has ChangeLog files, but you don't want patcher to treat them in a
special way at all (you want Patcher to consider them as ordinary source
files). The way to do this is to set @code{:change-log-file-name} to
something that doesn't exist in your project, for instance ``
ChangeLog'' (note the frontal space).
@end ignore

@node ChangeLogs Updating, ChangeLogs Navigation, ChangeLogs Naming, ChangeLogs Handling
@subsection ChangeLogs Updating

@fpoindex{change-logs-updating}
The way Patcher deals with ChangeLogs is controlled via the
@code{:change-logs-updating} project option. Its value (a symbol) must
be one of @code{automatic} (the default), @code{manual} or @code{nil}.

@menu
* Automatic ChangeLogs::        Automatic creation of ChangeLog skeletons
* Manual ChangeLogs::           When ChangeLog entries already exist
* No ChangeLogs::               For project that don't use ChangeLog files
@end menu

@node Automatic ChangeLogs, Manual ChangeLogs, , ChangeLogs Updating
@subsubsection Automatic ChangeLogs

Automatic ChangeLogs mode is the default. Each time you (re)generate a
diff, Patcher (re)creates ChangeLog skeletons in the appropriate
ChangeLog files, by analyzing the generated diff. You then need to fill
the entries manually.

Note that when Patcher creates skeletons for you, you should
@strong{never} kill the ChangeLog buffers while a project is running.
Otherwise, Patcher will loose track of what it has or has not generated.

@menu
* Skeleton Generation:: How skeletons are created.
* Skeleton Parameters:: What the skeletons look like.
* ChangeLog Files::     Linking and saving ChangeLogs.
@end menu

@node Skeleton Generation, Skeleton Parameters, Automatic ChangeLogs, Automatic ChangeLogs

@findex patch-to-change-log
@findex patcher-default-diff-cleaner
@fpoindex{diff-cleaner}@c
ChangeLog skeletons are not generated by Patcher directly, but rather by
the function @code{patch-to-change-log} from the @code{add-log} library,
itself from the @code{xemacs-base} package. This function supports only
standard and CVS diff, in unified format.

For revision control systems that output something different, Patcher
provides a @code{:diff-cleaner} option. This option names a function
that will be used to ``cleanup'' the diff (so that it looks like a
standard one, just before calling @code{patch-to-change-log}.

@birtindex{git}@c
@birtindex{hg}@c
@birtindex{darcs}@c
@birtindex{prcs}@c
Patcher comes with a generic cleaner function named
@code{patcher-default-diff-cleaner} which is used by default and works
correctly with Git, Mercurial, Darcs and PRCS, as long as you use the
corresponding built-in themes (@pxref{Themes}), or in fact, as long as
the corresponding @code{:diff-header} option is correct (@pxref{Diff
Headers}).


@node Skeleton Parameters, ChangeLog Files, Skeleton Generation, Automatic ChangeLogs

@fpoindex{change-logs-user-name}@c
@fpoindex{user-name}@c
@fpoindex{change-logs-user-mail}@c
@fpoindex{user-mail}@c
@findex patch-to-change-log
@vindex user-full-name
@vindex user-mail-address
Patcher has two project options that give you some control on the
generated ChangeLog skeleton: @code{:change-logs-user-name} and
@code{:change-logs-user-mail}. As you might expect, these are strings
defining your name and mail address for ChangeLog entries'headers. When
@code{nil}, Patcher falls back to (respectively) the @code{:user-name}
and @code{:user-mail} project options. If in turn set to @code{nil},
Patcher lets the function @code{patch-to-change-log} decide what to use
(most probably what the user options @code{user-full-name} and
@code{user-mail-address} say).

@node ChangeLog Files, , Skeleton Parameters, Automatic ChangeLogs

Normally, you don't modify source files when working with Patcher.
However, ChangeLog files need update and saving in automatic mode.
Patcher provides two hooks for plugging in additional processing on
ChangeLog files.

@itemize @bullet
@item @code{:link-change-log-hook}
@fpoindex{link-change-log-hook}@c
This hook is run every time Patcher ``links'' a ChangeLog file to a
project. Linking a ChangeLog file in this context means figuring out
that it is involved in the current patch. Every function in this hook
will be given the ChangeLog file name (relative to the project's
directory) as argument. Also, it is guaranteed that when this hook is
run, the current directory (in whatever the current buffer is) is set to
the project's directory.
@item @code{:after-save-change-log-hook}
@fpoindex{after-save-change-log-hook}@c
This hook is run every time you save a ChangeLog file. The functions in
this hook are executed in the ChangeLog's buffer. To be honest with you,
I didn't invent anything here, and I must confess that this is not a
real hook. Instead, what you specify in this project option is simply
added to the ChangeLog's local after-save-hook.
@end itemize

Now you're wondering what you could possibly use these two options for
(apart from ringing the terminal bell I mean), and you're right. In
fact, their existence comes from my desire to support Git projects by
index.

@birtindex{git}@c
@birtindex{git-index}@c
@bitindex{git-index-automatic-change-logs}@c
@vindex patcher-built-in-themes
If you look at @code{patcher-built-in-themes}, you will find two themes
for Git (along with their their whitespace-cleaning counterpart):
@code{git} and @code{git-index}. The @code{git-index} one will only work
on what's in the Git staging area. This is cool as long as ChangeLog
files are written by hand @pxref{Manual ChangeLogs}. However, in
automatic mode, we need a way to add them to the index once the
skeletons are filled in. This is done by another built-in theme that you
must add explicitly to your project, called
@code{git-index-automatic-change-logs}. This theme uses the two options
described above to automatically add ChangeLog entries to the staging
area.

@node Manual ChangeLogs, No ChangeLogs, Automatic ChangeLogs, ChangeLogs Updating
@subsubsection Manual ChangeLogs

In manual mode, Patcher assumes that you create ChangeLog entries
manually, as you write the code, so it won't create ChangeLog skeletons.
It is important to understand that in this situation, ChangeLog entries
@strong{must} have been written @strong{before} you call Patcher.
Patcher won't let you write them in the process.

Even in @code{manual} mode, Patcher might still need to know the
affected ChangeLog files (for the commit process) and your exact
ChangeLog entries in each of these files (for insertion in the message).
The ChangeLog files are automatically deduced from the patch. When
that's required, however, you will be presented with each ChangeLog file
in turn, and invited to precise the number of ChangeLog entries
concerning this patch. These entries must of course appear at the top of
the file.

@node No ChangeLogs, , Manual ChangeLogs, ChangeLogs Updating
@subsubsection No ChangeLogs

This mode is for projects that don't do ChangeLogs. Patcher won't try to
create ChangeLog entries, and won't expect that you have written
ChangeLog entries either.

Note that if you @emph{do} have ChangeLog files in this mode, they will
be regarded as ordinary source files. As a consequence, this is a case
where it is not forbidden to list them explicitly as part of a
subproject, although I don't see why you would want to do that.


@node ChangeLogs Navigation, ChangeLogs Appearance, ChangeLogs Updating, ChangeLogs Handling
@subsection ChangeLogs Navigation

Patcher provides commands for navigating across ChangeLog and mail
buffers, something especially convenient when you need to fill them by
hand after skeletons have been created.

@kindex C-c C-p n
@kindex C-c C-p p
@findex patcher-change-log-next
@findex patcher-change-log-previous
@findex patcher-mail-first-change-log
@findex patcher-mail-previous-change-log
Patcher sees a project's mail and ChangeLog buffers as a circular chain
that can be walked forward and backward by typing @kbd{C-c C-p n} or
@kbd{C-c C-p p} respectively (depending on the buffer you're in, this
involves either @code{patcher-change-log-next},
@code{patcher-change-log-previous}, @code{patcher-mail-first-change-log}
or @code{patcher-mail-last-change-log}).

@kindex C-c C-p m
@kindex C-c C-p N
@kindex C-c C-p P
@findex patcher-change-log-mail
@findex patcher-change-log-first
@findex patcher-change-log-last
From a ChangeLog buffer, you can also shortcut the cycle and switch back
to the mail buffer directly by typing @kbd{C-c C-p m}
(@code{patcher-change-log-mail}), or switch to the first / last
ChangeLog buffer respectively by typing @kbd{C-c C-p P}
(@code{patcher-change-log-first}) / @kbd{C-c C-p N}
(@code{patcher-change-log-last}).


@node ChangeLogs Appearance,  ChangeLogs Prologue, ChangeLogs Navigation, ChangeLogs Handling
@subsection ChangeLogs Appearance

@fpoindex{change-logs-appearance}@c
The appearance of ChangeLog entries in the message is controlled by the
@code{:change-logs-appearance} project option. Its value must be a
symbol from the following:

@table @code
@item verbatim
This is the default. ChangeLog entries appear just as text in the
message, above the patch. Most people prefer this kind of appearance
since it is the most readable.

@item pack
ChangeLog entries appear as a patch (they are diff'ed against the
archive). This patch is however distinct from the source patch, and
appears above it.

@item patch
ChangeLog entries appear as a patch (they are diff'ed against the
archive), and this patch is integrated into the source patch. In other
words, the message looks like a global patch integrating both the
sources and the ChangeLogs.

@item nil
The ChangeLog entries don't appear in the message at all.
@end table

@fpoindex{change-logs-diff-command}@c
When the ChangeLogs appearance is either @code{pack} or @code{patch},
the diff command used to generate the patch is controlled by the
@code{:change-logs-diff-command} project option. The value can be
@code{nil}, meaning that the same diff command is to be used as for the
sources (@pxref{Diff Command}), or it can be a string specifying an
alternate command.

When diffing ChangeLog files, it is strongly recommended that you remove
contexts from the diff, because otherwise, ChangeLog patches often fail
to apply correctly.

@birtindex{git}@c
@fpoindex{diff-command}@c
The @code{:change-logs-diff-command} project option supports the same
substitution constructs as the @code{:diff-command} one (@pxref{Diff
Command}). For example, here is the ChangeLogs diff command used in the
@code{git} built-in theme (@pxref{Themes}): @samp{git diff -U0
--no-prefix HEAD%?f@{ -- @}%f}.

@findex patcher-mail-insert-change-logs
@findex patcher-change-logs-insert-change-logs
@kindex C-c C-p l
When ChangeLog entries are written in advance (@pxref{Manual
ChangeLogs}), Patcher can (and does) insert them into the mail buffer
automatically. However, Patcher cannot tell when you're done filling in
skeletons (@pxref{Automatic ChangeLogs}), so in such a case you need to
insert the ChangeLog entries explicitly. This is done by calling the
function @code{patcher-mail-insert-change-logs}. It is bound to @kbd{C-c
C-p l} in the mail buffer.

With an additional prefix argument, or when your project is set to not
normally include ChangeLogs in mail buffers, you will also be prompted
for an alternate appearance (for this time only).

In fact, this function can also be used in all situations to
@strong{reinsert} the ChangeLog entries into the mail buffer, whatever
their appearance. This comes in handy if you decide to further modify
them after the initial insertion (it's never too late to fix a typo).

One last note: the same binding is available in ChangeLog buffers as
well. The effect is to call
@code{patcher-change-log-insert-change-logs}, which in essence switches
to the mail buffer and performs insertion in a row. This saves you one
@kbd{C-c C-p m} keystroke.

@node ChangeLogs Prologue, ChangeLogs Status, ChangeLogs Appearance, ChangeLogs Handling
@subsection ChangeLogs Prologue

ChangeLog prologues are small pieces of informative text that Patcher
adds above each ChangeLog insertion in the mail buffer.

@fpoindex{change-logs-prologue}@c
When the ChangeLogs appearance is @code{verbatim}, Patcher inserts one
prologue per ChangeLog file. The prologue's contents is controlled by
the @code{:change-logs-prologue} project option (a string). A @samp{%f}
appearing in this string will be replaced with the ChangeLog filename.
The default value for @code{patcher-default-change-logs-prologue} is
@code{"%f addition:"}.

@fpoindex{diff-prologue-function}@c
@findex patcher-default-diff-prologue
When the ChangeLogs appearance is @code{pack}, Patcher inserts only one
prologue for the whole ChangeLogs patch. When @code{patch}, there is a
single prologue for both the ChangeLogs and the sources. For customizing
the prologue in both of these cases, see @ref{Diff Prologue}.

@node ChangeLogs Status, , ChangeLogs Prologue, ChangeLogs Handling
@subsection ChangeLogs Status

Let's face it. ChangeLogs are in fact an obsolete concept that dates
back to the old days when we used to work without revision control
systems. Now the story is different: we have commit log messages,
@code{git blame} and what not, to the point that ChangeLog files are big
and not really useful anymore.

On the other hand, the ChangeLog file @emph{format} is still convenient
to describe modifications, for instance in the commit log message. So
how nice would it be to continue manipulating ChangeLog entries, as
usual, but just not store them into files?

@fpoindex{default-change-logs-status}@c
Patcher can do that. It has a project option named
@code{:change-logs-status} which can have two values (symbols). A value
of @code{persistent} (the default) is in fact what we have assumed so
far: there are ChangeLog files and they are part of the project. This is
the traditional approach.

@fpoindex{change-log-file-name}@c
A value of @code{ephemeral} on the other hand means that your ChangeLog
entries exist only temporarily, to be used in the commit log message
and/or inserted verbatim in the mail. Patcher does this by creating a
temporary ChangeLog file (named after the @code{:change-log-file-name}
project option) in the project's base directory, and getting rid of it
after the mail is sent. As a result, everything works just as if the
ChangeLog file was real: ChangeLog entries can be generated
automatically or written manually @etc{}

The only restriction is that you cannot diff the ephemeral ChangeLog
entries because they are not really part of the project, so their
appearance can only be @code{verbatim}. Also, when you use an ephemeral
ChangeLog, beware to use a file name that doesn't conflict with existing
files (old ChangeLog files may for example be renamed to
@file{ChangeLog.dead}).


@bitindex{ephemeral-change-logs}@c
Because there's only one, virtual, ephemeral ChangeLog file located at
the project's base directory, the default value for the ChangeLogs
prologue doesn't work very well in the ephemeral case. It doesn't make
sense to refer to the file itself, since it's only temporary. A simpler
prologue like ``ChangeLog entries:'' would suffice. Patcher provides a
built-in theme called @samp{ephemeral-change-logs} that you can use to
both set the ChangeLog status to @samp{ephemeral} and modify the
prologue at the same time.

@birtindex{git-index}@c
@bitindex{git-index-automatic-change-logs}@c
One final note: if you use the @code{git-index} built-in theme with
ephemeral ChangeLogs, don't use it in conjunction with
@code{git-index-automatic-change-logs}, even if the ChangeLogs entries
are generated automatically by Patcher. Otherwise, they would be added
to the staging area, which is definitely not what you want.


@c Project Check In ===================================================
@node Project Check In, Mail Sending, ChangeLogs Handling, User Manual
@section Project Check In

@findex patcher-mail-commit
@kindex C-c C-p c
If you have the privilege to commit your changes yourself, you might do
so directly from the mail buffer, as the last operation before actually
sending the message. This is done by calling the function
@code{patcher-mail-commit} which is bound to @kbd{C-c C-p c} in the mail
buffer.

Committing directly from Patcher has the advantage that both the commit
log message and command-line are constructed automatically. Of course,
you still have an in-depth control on the commit process.

@menu
* Commit Command::       Specifying the command to commit the patch
* Log Message Handling:: Building a commit log message
* Commit Operation::     Actually committing your changes
@end menu

@node Commit Command, Log Message Handling, Project Check In, Project Check In
@subsection Commit Command

@findex patcher-mail-commit
@fpoindex{commit-command}@c
The command used to to commit a patch is specified by the
@code{:commit-command} project option (a string). You can also
temporarily change the command in question by calling
@code{patcher-mail-commit} with a prefix argument. As usual, note that
this prefix argument is not meant to modify the affected files on the
command-line. It's meant only to punctually modify the commit command
itself. The affected files are computed automatically by Patcher.

The commit command supports the same dynamic expansion constructs as the
diff command (@pxref{Diff Command}), and also adds two of its own.

@table @code
@item %s
A @code{%s} occurring in the commit command string will be replaced with
the name of a file containing the commit log message (@pxref{Log Message
Handling}). This file is a temporary file handled by Patcher.

@item %S
A @code{%S} occurring in the commit command string will be replaced with
the commit log message itself (@pxref{Log Message Handling}). Since the
intent here is to use the message as a command-line argument, it will be
automatically quoted against shell expansion.
@end table

Please note that exactly as for the diff command, a @code{%f} is
required in your commit commands, unless you know for sure that you will
never ever work on a subproject. But you never know that. Besides, you
should always also provide either a @code{%s} or a @code{%S}, unless
your archival software does not support log messages. I'm not actually
sure such a beast exists.

@birtindex{git}@c
As an example, here is the commit command for the Git built-in theme
(@pxref{Themes}): @samp{git commit %!f@{-a @}-F %s%?f@{ -- @}%f}


@node Log Message Handling, Commit Operation, Commit Command, Project Check In
@subsection Log Message Handling

Most project management tools understand the concept of a @dfn{log
message}: a short yet informative message that accompany the commit
operation, which is also stored in the repository.

@fpoindex{edit-log-message}@c
Before a commit operation, Patcher always builds an initial log message,
based on certain elements under your control. What happens next is
controlled the @code{:edit-log-message} project option: if @code{t} (the
default), you will be able to manually edit the log message. If
@code{nil}, Patcher will proceed directly to the next step
(@pxref{Commit Operation}).

Please note that Patcher stores log messages in temporary files that
may be used later by the commit command.

@menu
* Log Message Elements:: Elements Patcher can add automatically
* Log Message Editing::  Manually modifying the log message
@end menu

@node Log Message Elements, Log Message Editing, Log Message Handling, Log Message Handling
@subsubsection Log Message Elements

@fpoindex{log-message-items}@c
Patcher has the ability to initialize the log message with different
elements. These elements are specified with the
@code{:log-message-items} project option. Its value is either
@code{nil}, meaning that you don't want any initialization, or a list of
symbols specifying the elements you desire. The available items are:

@table @code
@item subject
The subject of the message. The subject's prefix is automatically
removed.

@item compressed-change-logs
The ``compressed'' ChangeLog entries. Only the most important part of
the ChangeLogs is preserved, so the entries appear in a more compact
fashion.

@item change-logs
The raw ChangeLog entries.
@end table

@fpoindex{change-logs-separator}@c
By default, only the message's subject is used. When using more than one
item, they appear in the order specified above. If anything appears
before the raw ChangeLog entries, a separator string is used. This
string is specified by the @code{:change-logs-separator} project option.
By default the string looks like ``--- ChangeLog entries follow: ---''.


Note that it only makes sense to set @code{:log-message-items} to
@code{nil} if you also ask Patcher to let you edit the message
(@pxref{Log Message Editing}). Otherwise, your commit would end up with
empty log messages.


@node Log Message Editing, , Log Message Elements, Log Message Handling
@subsubsection Log Message Editing

If so required, Patcher lets you manually edit the log message after
having initialized it. Log message editing happens in a special buffer
called @code{*<project name> Patcher Project Log Message*}.

@findex patcher-logmsg-mode
@vindex patcher-logmsg-mode-hook
@vindex patcher-logmsg-font-lock-keywords
@vindex patcher-comment-face
@vindex patcher-reference-face
This buffer is governed by a major mode called
@code{patcher-logmsg-mode}. This mode offers a hook,
@code{patcher-logmsg-mode-hook}, which you can use to plug additional
behavior like turning on font lock. If you do so, you might also want to
have a look at @code{patcher-logmsg-font-lock-keywords},
@code{patcher-comment-face} and @code{patcher-reference-face} which are
the built-in elements for log message fontification.

When the log message buffer is initialized, it starts with an
informative comment header. The actual log message starts at the first
non blank line after this header.

While editing this buffer, commands to insert the items described in
@ref{Log Message Elements} are at your disposal. These commands perform
insertion at point:

@table @code
@item patcher-logmsg-insert-subject
@findex patcher-logmsg-insert-subject
@kindex C-c C-p s
Bound to @kbd{C-c C-p s}. Insert the message's subject (sans the
prefix).

@item patcher-logmsg-insert-change-logs
@findex patcher-logmsg-insert-change-logs
@kindex C-c C-p l
Bound to @kbd{C-c C-p l}. Insert the ChangeLog entries. Use a prefix
argument if you also want the ChangeLogs separator string to be
inserted.

@item patcher-logmsg-insert-compressed-change-logs
@findex patcher-logmsg-insert-compressed-change-logs
@kindex C-c C-p L
Bound to @kbd{C-c C-p L}. Insert the compressed ChangeLog entries. Use a
prefix argument if you also want the ChangeLogs separator string to be
inserted.
@end table

@findex patcher-logmsg-init-message
@kindex C-c C-p i
In addition to these commands, you can also completely reinitialize the
log message by calling the function @code{patcher-logmsg-init-message},
bound to @kbd{C-c C-p i}. Caution: this command first erases the buffer.

@findex patcher-logmsg-commit
@kindex C-c C-p c
@kindex C-c C-c
Once you're happy with your log message, you proceed to the commit
operation by calling the function @code{patcher-logmsg-commit}, bound to
either @kbd{C-c C-p c} as in mail buffers, or directly to @kbd{C-c C-c}.

Finally, the log message offers two more commands in case you change your
mind about the commit:

@table @code
@item patcher-logmsg-cancel
@findex patcher-logmsg-cancel
@kindex C-c C-z
Bound to @kbd{C-c C-z}. Use this when you decide to cancel the commit
operation (but not the whole project). Patcher will simply bring you
back to where you came from; typically the mail buffer.
@item patcher-logmsg-kill
@findex patcher-logmsg-kill
@kindex C-c C-k
Bound to @kbd{C-c C-k}. Use this to completely kill the project.
Remember that you can also do that from mail or ChangeLog buffers.
@end table


@node Commit Operation, , Log Message Handling, Project Check In
@subsection Commit Operation

@kindex C-c C-p c
@kindex C-c C-c
The commit operation occurs after typing @kbd{C-c C-p c} from the mail
buffer if you have not required log message editing, or after typing
@kbd{C-c C-p c} or @kbd{C-c C-c} from the log message buffer otherwise.

@fpoindex{edit-commit-command}@c
At that point, Patcher has constructed a proper commit command. What
happens next depends on the value of the @code{:edit-commit-command}
project option: if @code{nil}, Patcher performs the commit operation
directly. Otherwise (the default), you have the ability to edit or at
least confirm the commit command.

Commit command editing happens in a special buffer called
@code{*<project name> Patcher Project Commit Command*}.

@findex patcher-cmtcmd-mode
@vindex patcher-cmtcmd-mode-hook
@vindex patcher-cmtcmd-font-lock-keywords
@vindex patcher-comment-face
@vindex patcher-reference-face
This buffer is governed by a major mode called
@code{patcher-cmtcmd-mode}. This mode offers a hook,
@code{patcher-cmtcmd-mode-hook}, which you can use to plug additional
behavior like turning on font lock. If you do so, you might also want to
have a look at @code{patcher-cmtcmd-font-lock-keywords},
@code{patcher-comment-face} and @code{patcher-reference-face} which are
the built-in elements for commit command fontification.

This buffer starts with an informative comment header. The actual commit
command consists in all non blank and non comment lines concatenated
together.

@findex patcher-cmtcmd-commit
@kindex C-c C-p c
@kindex C-c C-c
Once you're happy with your commit command, you finally perform the
operation by calling the function @code{patcher-cmtcmd-commit}, bound to
both @kbd{C-c C-p c} as in mail buffers, and to @kbd{C-c C-c}.

The commit command buffer offers two more commands in case you change
your mind about the commit:

@table @code
@item patcher-cmtcmd-cancel
@findex patcher-cmtcmd-cancel
@kindex C-c C-z
Bound to @kbd{C-c C-z}. Just as in log message buffers, use this when
you decide to cancel the commit operation (but not the whole project).
Patcher will simply bring you back to where you came from; typically the
mail buffer or the log message buffer.
@item patcher-cmtcmd-kill
@findex patcher-cmtcmd-kill
@kindex C-c C-k
Bound to @kbd{C-c C-k}. Just as in log message buffers, use this to
completely kill the project. Remember that you can also do that from
mail or ChangeLog buffers as well.
@end table


After the commit operation, Patcher changes some parts of the mail
buffer in the following manner:

@itemize @bullet
@item
@fpoindex{subject-committed-prefix}@c
The subject prefix is changed to that specified by the
@code{:subject-committed-prefix} project option (a string), unless it is
@code{nil}. By default, ``[COMMIT]'' is used.

@item
@fpoindex{committed-notice}@c
A commit notice is added at the very beginning of the message's body.
This notice is specified by the @code{:committed-notice} project option.
It can be @code{nil} or a string. By default, it reads ``NOTE: this
patch has been committed.''.
@end itemize


@c Mail Sending =======================================================
@node Mail Sending, More On Commands, Project Check In, User Manual
@section Mail Sending

Sending the message will most probably be done by typing @samp{C-c C-c}
in the mail buffer. This is also the case when you're using the fake
mail method, by the way.

@menu
* Before Sending:: Patcher does some checkings
* After Sending::  patcher does some cleanup
@end menu

@node Before Sending, After Sending, Mail Sending, Mail Sending
@subsection Before Sending

There are circumstances in which Patcher will perform some checkings on
your message when you send it, just before it is actually sent:

@itemize @bullet
@item ChangeLogs insertion

@fpoindex{check-change-logs-insertion}@c
In case of manual ChangeLog insertion (@pxref{ChangeLogs Appearance}),
Patcher can check that you have indeed inserted the ChangeLog entries
before sending the message. This behavior is controlled by the
@code{:check-change-logs-insertion} project option. A value of
@code{nil} means never check (the message will be sent as-is). A value
of t means check, and abort the sending if the ChangeLog entries are
missing. A value of @code{ask} (the default) means ask for your opinion
on this terrible matter.

@item Commit Operation

@fpoindex{commit-privilege}@c
Patcher has a @code{:commit-privilege} project option; a Boolean
specifying whether you're likely to commit your changes by yourself.

@fpoindex{check-commit}@c
In case of commit privilege, Patcher can check that you have indeed
committed your changes before sending the message. This behavior is
controlled by the @code{:check-commit} user option. A value of
@code{nil} means never check (the message will be sent as-is). A value
of t means check, and abort the sending if the commit operation has not
been performed. A value of @code{ask} (the default) means ask for your
opinion on this rather unfortunate situation.
@end itemize


Two notes on these checkings:

@itemize @bullet
@item
For uninteresting technical reasons, Patcher does not currently (and
will probably never) offer you an automatic ChangeLogs insertion or
commit operation, at mail sending time, but just abort the sending
process in some circumstances. That's not a big deal though.

@item
For other uninteresting technical reasons, these checkings require a
native knowledge of your mail user agent. Patcher does not currently
support all mail user agents on earth (I'll add them on demand however).
If that's the case, you will be warned and invited to send me a message.
Also, you can send me one on April 21st: it's my birthday.
@end itemize

@node After Sending, , Before Sending, Mail Sending
@subsection After Sending

After sending the message, Patcher also performs some cleanup
operations, that you can customize. The cleanup is controlled by the
following project options. Each one is a Boolean option which defaults
to @code{t}.

@table @code
@item :kill-sources-after-sending
@fpoindex{kill-sources-after-sending}@c
Whether to kill source files after sending the message. If @code{nil},
the source files will remain visited.

@item :kill-change-logs-after-sending
@fpoindex{kill-change-logs-after-sending}@c
Whether to kill ChangeLog files after sending the message. If
@code{nil}, the ChangeLog files will remain visited.
@end table

When Patcher is allowed to kill a source or ChangeLog file, it will only
actually kill it if it was responsible for loading it for this
particular project in the first place. For instance, if the file was
already visited before Patcher was launched, or if another Patcher
project is also using the file, then it won't be killed regardless of
the value of these options.


@c More On Commands ===================================================
@node More On Commands, , Mail Sending, User Manual
@section More On Commands

This section deals with information that apply to all commands used by
Patcher (diff and commit operations).

@menu
* Prefixing Commands::  Bypassing a firewall
* Error Handling::      Dealing with errors
@end menu

@node Prefixing Commands, Error Handling, , More On Commands
@subsection Prefixing Commands

If you're working on a distant archive and you're behind a firewall, you
might need to prefix all your commands with something like
@code{runsocks}. Of course, this can be done manually in all your
command settings, but Patcher offers you a simpler way to do it.

@fpoindex{pre-command}@c
There is a project option named @code{:pre-command} which can be used
for this kind of thing. It must be a string that will be prepended to
all operations performed by Patcher.


@node Error Handling, , Prefixing Commands, More On Commands
@subsection Error Handling

From time to time, commands may fail for different reasons. Patcher
tracks command failures and lets you know when that happens.

@fpoindex{ignore-diff-status}@c
The first thing Patcher does is to check the external processes exit
codes. A non-zero exit code will normally trigger a Patcher error. There
is however one notable exception: @code{cvs diff} has this incredibly
stupid idea of returning an exit code of 1 when the diff succeeds, and
is non-empty. Because of this, Patcher provides an option named
@code{:ignore-diff-status} that is set to @code{t} in the CVS theme.
There should be no reason to use it in any other context.

@birtindex{cvs}@c
@fpoindex{failed-command-regexp}@c
Next, Patcher looks for specific strings in process output. The
@code{:failed-command-regexp} project option lets you specify a regular
expression to match with the output of an aborted command. In the CVS
built-in theme for example (@pxref{Themes}), the value is @samp{"^cvs
\\[[^]]* aborted\\]"}.



@c ====================================================================
@c XEmacs Development
@c ====================================================================
@node XEmacs Development, Indexes, User Manual, Top
@appendix XEmacs Development

XEmacs development occurs on a Mercurial repository. Patches are
advertised on @email{xemacs-patches@@xemacs.org}. We assume that you are
a committer and have a clone of the main repository located at
@file{/usr/local/src/xemacs/21.5}. Your @file{hgrc} file should look
like this (replace my identity with yours):

@cartouche
@verbatim
[ui]
username = Didier Verna <didier@xemacs.org>

[paths]
default      = ssh://hg@bitbucket.org/xemacs/xemacs
@end verbatim
@end cartouche

The following project settings will do nicely for hacking XEmacs:

@cartouche
@verbatim
'("XEmacs 21.5" "/usr/local/src/xemacs/21.5"
   :to-address "xemacs-patches@xemacs.org"
   :change-logs-user-mail "didier@xemacs.org"
   :commit-privilege t
   :log-message-items (subject change-logs)
   :themes (mercurial))
@end verbatim
@end cartouche

If you want to also work on the packages, you may clone the big umbrella
repository. Let's assume you do so in
@file{/usr/local/share/emacs-lisp/source/xemacs-packages}. Your
@file{hgrc} file should look like this:

@cartouche
@verbatim
[ui]
username = Didier Verna <didier@xemacs.org>

[paths]
default      = ssh://hg@bitbucket.org/xemacs/xemacs-packages
@end verbatim
@end cartouche

The following project settings will do nicely for hacking the packages
(all settings are in fact inherited from the main XEmacs 21.5 project):

@cartouche
@verbatim
'("XEmacs Packages" "/usr/local/share/emacs-lisp/source/xemacs-packages"
  :inheritance ("XEmacs 21.5"))
@end verbatim
@end cartouche

However, note that you shouldn't work on this project directly. Every
package is in fact stored under this project as a Mercurial submodule.
Patcher detects every such submodule automatically and creates a
corresponding project for you (submodule projects are named @samp{XEmacs
Packages (<submodule>)}. Because those really are independent projects,
you should probably also update every @file{hgrc} file with your
identity.



@c ====================================================================
@c Indexes
@c ====================================================================
@node Indexes, , XEmacs Development, Top
@appendix Indexes

@menu
* Concept Index::
* Variable Index::
* Function Index::
* Keystroke Index::
@end menu


@c -------------
@c Concept Index
@c -------------
@node Concept Index, Variable Index, Indexes, Indexes
@section Concepts
@printindex cp
@page


@c --------------
@c Variable Index
@c --------------
@node Variable Index, Function Index, Concept Index, Indexes
@section Variables
@printindex vr
@page


@c --------------
@c Function Index
@c --------------
@node Function Index,  Keystroke Index, Variable Index, Indexes
@section Functions
@printindex fn
@page


@c ---------------
@c Keystroke Index
@c ---------------
@node Keystroke Index,  , Function Index, Indexes
@section Keystrokes
@printindex ky
@page


@bye

@c Don't add stuff under this line!!
@c patcher.texi ends here

@c  LocalWords:  Patcher patcher RCS ChangeLog Darcs CVS PRCS MUA SuperProj kbd
@c  LocalWords:  subproject subdirectory logmsg findex kindex vindex cmtcmd
@c  LocalWords:  samp cartouche