NAME

multi-commit.pl - perform multiple commits (cvs|svn|darcs|hg|hgmq) with a prepared command-file

SYNOPSIS

multi-commit.pl --hg commit

DESCRIPTION

Features

This script can be used to perform multiple commits of files within a working copy directory. Among the programs features are:

supports several version control systems, currently supported are: cvs, subversion, darcs, mercurial and mercurial with patch queue (mq) extension.
all log-messages for all files and commits can be specified in a single file
the user can specify which files are committed within a single command. Such commits form an indivisable change-set in the repository (except for cvs).

commands

The following commands are known:

status

multi-commit.pl status

This command returns a list of all files in the current directory. For each file the first letter shows the status. Usually "M" means modified, "D" deleted, "A" added and "?" means that this file is unknown to the repository.

generate

multi-commit.pl generate

This command is usually used to create a first version of the message file. It simply writes the output of the status command (see above) into a file. The default name for this file is "DIFFS" but it can be specified differently as a parameter for "generate".

edit

multi-commit.pl edit

This command is similar to "generate" but is starts an editor on the generated file. The editor is taken from the MULTICOMMIT_EDITOR environment variable, and, if this is not defined, from the EDITOR environment variable.

commit

multi-commit.pl commit

This command performs the commit of all files mentioned in the description-file. For the details of the format of this file see below. The name of the description file is "DIFFS" but it can be specified differently as a parameter for "commit".

options

The following options are known:

--cvs

This option specifies that the "CVS" version control system is to be used.

--svn

This option specifies that the "subversion" version control system is to be used. This is also the default.

--darcs

This option specifies that the "darcs" version control system is to be used.

--hg

This option specifies that the "mercurial" version control system is to be used.

--hgmq

This option specifies that the "mercurial" version control system with patch queues is to be used. The difference with respect to "--hg" is that the status is generated with "hg status --rev -2" and that "hg qrefresh -e" is used instead of "hg commit".

--dry-run

With this option, no version control command is performed, but the program simply prints what it would do. Is is recommended that you always look with

multi-commit.pl commit MESSAGE.TXT --dry-run | less

what the program would do before actually comitting changes in the repository.

the description file

The description file is usually created by taking the output of the "status" command and adding comments for each changed, modified or added file. This is an example of such a file, note that (in contrast to this help text) the lines MUST NOT heave leading spaces:

--------------------------------------------------------
The inline documentation had to be changed: the 
current version of doxygen doesn't seem to work with "\manonly" 

M ./MultiCAN/src/tool/src/pmsg.c -6 +1
M ./MultiCAN/src/tool/src/psem.c -7
M ./MultiCAN/src/tool/src/ip_array.c -9 +4
--------------------------------------------------------
the "what" string now contains the settings of important
compiler macros from the time the source was compiled

M ./MultiCAN/src/tool/src/pth.c +13
M ./MultiCAN/src/tool/src/pdbg.c +23
some comments were changed here.

This file defines two commit-groups. Commit-groups are separated by lines with at least 4 '-' characters. Each commit group contains the original lines from the status-command and additional text for the log-messages. There are two kinds of comments, generic and file-specific comments. Comments at the start of a group are generic, while comments that follow filenames are specific for that file. A generic comment should always be specified, while file-specific comments are optional. In the above example, the file-names and flags were created by darcs, but the numbers at the line-ends like "-6 +1" are ignored.

example of a typical session

We assume that you are in the top-directory of your working copy. We also assume that you use mercurial. Replace "--hg" with "--darcs" if you use darcs or with "--svn" if you use subversion.

generate the description file named "DIFFS" and edit it:

multi-commit.pl --hg edit

Remove all lines marked with "?" here, these are files the repository doesn't know of. For each file mentioned, look what has changed (for example with "cvs diff <filename>", "svn diff <filename>" or "darcs diff <filename>" or your favorite graphical diff program) and append a comment below the filename. Leave the line with the filename itself unchanged.

group log-messages in the description file:

You should now look which commits belong logically together. When the log-messages for two files are identical, they belong together. Changes that depend on each other should also be grouped. Groups must be separated with lines consisting of many (more that 4) "-" characters. For each group, specify a generic log message that appears directly below the line with "-" characters. For all files in that group where the generic log message suffices, remove the file-specific logmessage.

commit your changes:

multi-commit.pl --hg commit

That should be all!

AUTHOR

Goetz Pfeiffer, Goetz.Pfeiffer@helmholtz-berlin.de