6. Reference Manual

This chapter provides a complete reference guide to Patcher. Everything there is to know about Patcher is here, but if you want to find a particular piece of information, you'd better know already where to look for it...

6.1 Patcher Projects		Storing project descriptions
6.2 Patcher Entry Points		Calling Patcher
6.3 Patcher FakeMail Mode		Driving the fakemail buffer
6.4 Gnus Mail Method		Special settings for Gnus
6.5 Patcher Minor Mode		Driving the mail buffer
6.6 Patcher LogMsg Mode		Driving the log message buffer

6.1 Patcher Projects

6.1.1 Project Registration		Where to store Patcher Projects
6.1.2 Project Options		How to describe Patcher projects
6.1.3 Special Project Options		Exceptions to the rules

6.1.1 Project Registration

Patcher stores projects descriptions in the following two variables:

User Option: patcher-projects

Custom group: patcher

List of project descriptors used by patcher-mail and patcher-mail-subproject.

Each project descriptor looks like `(NAME DIR :OPTION VALUE ...)' where NAME is a string naming your project, DIR is a string specifying the directory in which it resides, and the remainder is a sequence of option/value pairs (see section 6.1.2 Project Options).

User Option: patcher-subprojects

Custom group: patcher

List of subproject descriptors used by patcher-mail and patcher-mail-subproject.

Each subproject descriptor looks like `(NAME PARENT :OPTION VALUE ...)' where NAME is a string naming your subproject, PARENT is a string naming the project this subproject is based on, and the remainder is a sequence of option/value pairs (see section 6.1.2 Project Options).

Subprojects must lie under the same directory as (or under a subdirectory of) the parent project. Subprojects and project must not have names in common.

6.1.2 Project Options

For each existing project option, Patcher also has a fallback user option with a default value. The name of the fallback variable is obtained by replacing the colon in the project option's name with the prefix patcher-default-. They all belong to the Custom group patcher-default.

When Patcher needs the value of a particular option, it first looks in the project descriptor to see if the option is given. If that fails, it recursively looks in the options of all inherited projects (see section 6.1.3 Special Project Options). If that still fails, it finally falls back to the value given by the corresponding fallback variable.

Here's a list of available project options:

:mail-method

Method used by Patcher to prepare a mail.

Currently, there are four built-in methods: compose-mail (the default), sendmail, message, gnus and fake. You can also define your own method, say foo. In that case, you must provide a function named patcher-mail-foo which takes two arguments: a project descriptor and a string containing the subject of the message. This function must prepare a mail buffer. If you want to do this, please see how it's done for the built-in methods.

:subject-prefix

Prefix for the subject of Patcher mails, or nil

A %n occurring in this string will be replaced with the project's name. A space will be inserted between the prefix and the rest of the subject, as appropriate. This part of the subject is never prompted for.

:subject-committed-prefix

The same, but for committed patches.

nil means don't change the prefix after committing.

:subject

Subject to use when preparing a Patcher mail, or nil

A %n occurring in this string will be replaced with the project's name. Please note that this is used only to provide a default value for prompted subjects. Subjects are always prompted for.

:mail-prologue

String to insert at the beginning of every Patcher mail, or nil.

:change-logs-updating

Controls the way ChangeLog files are updated.

Possible values and their meaning are:

automatic

This is the default. Patcher generates ChangeLog skeletons automatically based on the created diff (you then have to fill up the entries as needed).

manual

You are supposed to have updated the ChangeLog files by hand, prior to calling Patcher.

nil

You don't do ChangeLogs at all.

:change-logs-user-name

User full name for generated ChangeLog entries.

If nil, let patch-to-change-log decide what to use. Otherwise, it should be a string.

:change-logs-user-mail

User mail address for generated ChangeLog entries.

If nil, let patch-to-change-log decide what to use. Otherwise, it should be a string.

:change-logs-appearance

Controls the appearance of ChangeLog entries in Patcher mails.

The values currently supported are:

verbatim

This is the default. ChangeLog entries appear simply as text above the patch. A short line mentioning the ChangeLog file they belong to is added when necessary.

packed

ChangeLog files are diff'ed, but the output is packed above the rest of the patch.

patch

ChangeLog files are diff'ed, and the output appears as part of the patch itself.

nil

ChangeLog entries don't appear at all.

:change-logs-prologue

String to insert just before ChangeLogs in every Patcher mail.

This applies when ChangeLog additions appear verbatim in the message. A %f occurring in this string will be replaced with the ChangeLog file name (relative to the project's directory).

:diff-prologue-function

Function used to insert a prologue before each diff output.

Insertion must occur at current point in current buffer. This function should take one (symbol) argument indicating the kind of diff:

• a value of sources indicates a source diff only,
• a value of change-logs indicates a ChangeLog diff only,
• a value of mixed indicates a diff on both source and ChangeLog files.

The following variables are bound (when appropriate) when this function is executed:

name

the name of the current Patcher project,

source-diff

the command used to create a source diff,

change-log-diff

the command used to create a ChangeLog diff,

source-files

sources files affected by the current patch,

change-log-files

ChangeLog files affected by the current patch.

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

:diff-command

Method used by Patcher to generate a patch.

A %f occurring in this string will be replaced with the files affected by the patch. These files can be specified by using patcher-mail-subproject instead of patcher-mail to prepare the patch, or by using a permanent subproject. Otherwise, the %f will simply be removed.

:after-diff-hook

Hook to run on Patcher diff outputs.

Each function should take two optional arguments delimiting the diff region (no argument means process the whole buffer) and work in the current buffer. The point is placed at the beginning of the region, and the buffer excursion is saved for you.

There is a special built-in function named patcher-prcs-diff-convert that can be used in this hook to convert PRCS diff output to a traditional one.

:diff-line-filter

Line filter to pass Patcher diff's through.

When inserting a diff in Patcher mails, lines matching this regexp will be excluded. Note: the regexp must match the whole line. Don't add beginning and end of line markers to it, Patcher will do this for you.

By default, local files unknown to CVS are filtered out.

:change-logs-diff-command

Command to use to generate ChangeLog diffs.

This value is used when the ChangeLogs appearance is either packed or patch. If set to diff, use the same command as for the rest of the patch. Otherwise, it should be a string. A %f occurring in this string will be replaced with the ChangeLog filenames.

Note: it is highly recommended to remove the context from ChangeLog diffs because they often fail to apply correctly.

:commit-privilege

Boolean indicating whether you're likely to commit you changes by yourself.

:commit-command

Method used by Patcher to commit a patch.

This command should contain either a %s or a %S which will be replaced with the name of a file containing the commit log message, or he log message itself, respectively. A %f occurring in the command will be replaced with the files affected by the patch. These files can be specified by using patcher-mail-subproject instead of patcher-mail to prepare the patch, or by using a permanent subproject. Otherwise, the %f will simply be removed.

:confirm-commits

Whether Patcher asks for a confirmation before doing a commit.

:committed-notice

Notice added to a mail when the patch is committed before sending.

:failed-command-regexp

Regular expression for matching the result of a failed command.

Commands in question are the diff and the commit one.

:log-message-items

Elements used to initialize a Patcher commit log message.

This is nil, or a list of the following items:

subject

the subject of the corresponding Patcher mail (sans the prefix),

compressed-change-logs

the compressed ChangeLog entries for the current patch.

change-logs

the ChangeLog entries for the current patch. If some items appear before the ChangeLog entries, the ChangeLogs separator will automatically be included.

:change-logs-separator

ChangeLog entries separator for Patcher commit log messages.

Either nil, or a string which will be inserted in a line of its own.

:edit-log-message

Whether Patcher lets you edit the commit log message.

:kill-source-files-after-sending

Whether to kill source files after sending the mail.

Not implemented yet.

:kill-change-logs-after-sending

Whether to kill the ChangeLog files after sending the mail.

:kill-source-files-after-diffing

Whether to kill source files after building the ChangeLog skeletons.

These files are loaded temporarily by patch-to-change-log. If this variable is non nil, patch-to-change-log will be instructed to remove them when they are not needed anymore.

:to-address

Email address to use when sending a Patcher mail.

This variable is used by all mail methods except the gnus one. If not defined, it is prompted for.

:gnus-group

Gnus group to use when sending a Patcher mail.

This variable is used only by the gnus mail method. The mail sending process will behave as if you had type `C-u a' in the *Group* buffer on that Gnus group. If not defined, it is prompted for.

6.1.3 Special Project Options

The following project options behave in a somewhat particular way. None of the has a corresponding fallback user option.

:inheritance

This option exists only for projects, not for subprojects. It must be a list of strings which correspond to project names. The inheritance of a project defines a list of projects from which to inherit options.

:subdirectory

This option exists only for subprojects, not for projects. It lets you specify a subdirectory of the original project's directory in which the whole subproject resides.

:files

This option exists only for subprojects, not for projects. Its lets you specify a list of files or directories composing the subproject. Each file specification can contain wildcards. If a :subdirectory subproject option is given, these files or directories should be relative to this subdirectory. Otherwise, they should be relative to the base project's directory.

6.2 Patcher Entry Points

There are currently two main entry points for calling Patcher:

Interactive Command: patcher-mail (project subject [arg])

Prepare a mail about a patch to apply on a project.

PROJECT is the name of a Patcher project or permanent subproject.

SUBJECT is the subject of the mail.

When called interactively, use a prefix ARG to override the value of the diff command to use for this project. Note that this is not the way to restrict the diff to certain files. If you want to work on a temporary subset of the (sub)project (e.g. some files, subdirectories etc), you have two alternatives, use the function patcher-mail-subproject instead.

Interactive Command: patcher-mail-subproject (project subject files [arg)

Prepare a mail about a patch to apply on part of a (sub)project.

PROJECT is the name of a project or a subproject.

SUBJECT is the subject of the mail.

FILES is a string listing one or more files, possibly with wild cards; essentially, part of a command line to be interpolated into the diff and maybe the commit commands issued by Patcher.

When called interactively, use a prefix ARG to override the value of the diff command to use for this project.

6.3 Patcher FakeMail Mode

Patcher FakeMail mode is the major mode that drives the fake mail buffer. Nothing much to say about it.

Interactive Command: patcher-fakemail-send ()

Bound to `C-c C-c'.

Pretend to send a fake Patcher mail. Only perform the usual cleanup after real Patcher mails are sent.

Interactive Command: patcher-version ()

Bound to `C-c C-p v'.

Show the current Patcher version.

6.4 Gnus Mail Method

This mail method requires a running Gnus session. Here are some user options that control Patcher in this respect:

User Option: patcher-mail-run-gnus

Custom group: patcher-mail

Whether Patcher should run Gnus.

If Gnus is not running at the time it is needed, Patcher can start it (or not) depending on the value of this variable (a symbol):

• if nil, Patcher will abort execution,

• it prompt (the default), Patcher will ask you what to do,

• if t Patcher will unconditionally start Gnus.

User Option: patcher-mail-run-gnus-other-frame

Custom group: patcher-mail

Whether Patcher should start Gnus in a new frame.

Possible values (symbols) are:

nil

start Gnus in the current frame,

t

start Gnus in a new frame,

follow

start Gnus in a new frame, and also use this frame to prepare the new Patcher message.

6.5 Patcher Minor Mode

Patcher minor mode is the mode that drives Patcher in all mail buffers.

Interactive Command: patcher-generate-diff ([arg])

Bound to `C-c C-p d'.

(Re)generate the diff in the current Patcher mail buffer.

When called interactively, use a prefix ARG to override the diff command used for this project.

Note that this is not the way to specify files affected by this patch.

Interactive Command: patcher-insert-change-logs

Bound to `C-c C-p i'.

(Re)Insert ChangeLog entries in the current Patcher mail buffer.

User Option: patcher-mail-check-change-logs-insertion

Custom group: patcher-mail

ChangeLogs insertion checking prior to sending a Patcher mail.

This option affects the behavior of Patcher when ChangeLogs are supposed to appear by manual insertion into the mail buffer:

• if nil, Patcher never checks that you have inserted them, and lets you send the message as-is,
• if t, Patcher blindly aborts the sending process if you have forgotten to insert the ChangeLog entries in the message buffer,
• if ask (the default), Patcher asks you whether you want to proceed with sending or not.

Interactive Command: patcher-commit-change ([arg])

Bound to `C-c C-p c'.

Prepare to, and possibly commit a change to a project's repository. The change is the one that is announced in the mail buffer.

When called interactively, use a prefix ARG to override the commit command to use. Note that this is not meant to modify the source and ChangeLog files affected by the commit: they are computed automatically.

User Option: patcher-mail-check-commit-action

Custom group: patcher-mail

Commit action checking prior to sending a Patcher mail.

This option affects the behavior of Patcher when you have set the :commit-privilege project option:

• if nil, Patcher never checks that you have commited your changes, and lets you send the message without having done so,
• if t, Patcher blindly aborts the sending process if you have forgotten to commit your changes,
• if ask (the default), Patcher asks you whether you want to proceed with sending or not.

Interactive Command: patcher-version ()

Bound to `C-c C-p v'.

Show the current Patcher version.

User Option: patcher-minor-mode-string

Custom group: patcher

String to use in the modeline when Patcher minor mode is active.

User Option: patcher-minor-mode-hook

Custom group: patcher

Hooks to run after setting up Patcher minor mode.

6.6 Patcher LogMsg Mode

Patcher LogMsg mode is the mode that drives Patcher in log message buffers.

Interactive Command: patcher-logmsg-insert-subject

Bound to `C-c C-p s'.

Insert the Patcher mail subject into the current LogMsg buffer at point.

Interactive Command: patcher-logmsg-insert-change-logs ([arg])

Bound to `C-c C-p l'.

Insert ChangeLog entries in the current Patcher LogMsg buffer at point.

When used interactively, use a prefix ARG to also insert the ChangeLogs separator string.

Interactive Command: patcher-logmsg-insert-compressed-change-logs

Bound to `C-c C-p c'.

Insert compressed ChangeLog entries in the current Patcher LogMsg buffer.

Interactive Command: patcher-logmsg-init-message

Bound to `C-c C-p i'.

(Re)Init the log message in the current Patcher LogMsg buffer.

Interactive Command: patcher-logmsg-commit ([arg])

Bound to `C-c C-c'.

Commit the change described in the current Patcher LogMsg buffer.

When called interactively, use a prefix ARG to override the commit command.

Interactive Command: patcher-version ()

Bound to `C-c C-p v'.

Show the current Patcher version.