== Using the Commit Templates feature in Mercurial ==

Mercurial supports setting the `changeset` option in the `comittemplate` section of your hgrc file to be the commit description. This can be used to pre-populate empty commit messages, and can include things like showing the diffs that are about to be committed. See ''`hg help config.committemplate`'' for full information on this feature.

== Using a separate program ==

Mercurial calls a user-defined program to edit commit messages. If
that program returns false, the commit is aborted.

Here's an example patch for [[hgeditor]] that adds a user-defined template to the [[Cmd:commit|commit]] message:

{{{
diff -r 33988aaa1652 hgeditor
--- a/hgeditor Sun Dec 17 22:16:57 2006 -0600
+++ b/hgeditor Tue Dec 19 08:08:57 2006 -0600
@@ -39,6 +39,7 @@ HGTMP="${TMPDIR-/tmp}/hgeditor.$RANDOM.$
     done
 )

-cat "$1" > "$HGTMP/msg"
+cat `hg root`/.commit-template > "$HGTMP/msg"
+cat "$1" >> "$HGTMP/msg"

 MD5=$(which md5sum 2>/dev/null) || \
}}}

Validating that the commit message is correct can either be done by hgeditor or enforced by a precommit [[Hook|hook]].

=== Another way ===

The following pair of scripts respects the user's chosen [[editor]].

A usage scenario is a repository with main branch being the "default" branch.
Users create named side branches, and when work is done (including code review),
they merge to the default branch and push to the central repository.
Users call "hg_commit_default" to ensure that the merge commit goes to the default branch
(it is not hard to make a mistake),
and are presented with a commit template that contains the recommended fields.
Users may elect to delete some fields if they don't apply - the template is not enforced.

Script ''`hg_commit_default`'':
{{{
#!/bin/sh
#
# Commit to default branch.
# Ensure that branch is default.
# Provide commit message template.
#
# TODO: Disallow commit message passed with -m or -l.
#   Perhaps include it in the template?
#

BRANCH=`hg branch` || exit $?

if [ "$BRANCH" != default ] ; then
    echo "Branch $BRANCH is not default branch" >&2
    exit 1
fi

# Save the value to be overridden
export HGEDITOR_ORIG="$HGEDITOR"

HGEDITOR=hg_templated_editor exec hg commit "$@"
}}}


Script ''`hg_templated_editor`'':
{{{
#!/bin/sh
#
# Called by hg_commit_default.
# Calls configured commit editor with a template commit message.
#

FILE="$1"
TMP="$FILE.hg_templated_editor.$$.txt"

HG_CONF_EDITOR=`hg showconfig ui.editor`

if [ "$HGEDITOR_ORIG" ] ; then
    ED="$HGEDITOR_ORIG"
elif [ "$HG_CONF_EDITOR" ] ; then
    ED="$HG_CONF_EDITOR"
elif [ "$VISUAL" ] ; then
    ED="$VISUAL"
elif [ "$EDITOR" ] ; then
    ED="$EDITOR"
else
    ED=vi
fi

cleanup_exit() {
    /bin/rm -f "$TMP"
}

# Cleanup temporary file on exit or abnormal interruption
trap "cleanup_exit" 0 # normal exit
trap "exit 255" 1 2 3 6 15 # HUP INT QUIT ABRT TERM

# $TMP should match the permissions of $FILE
umask 077

# Prepend the custom template. The first line is empty.
echo "" > "$TMP" || exit $?
echo "Bug: " >> "$TMP"
echo "Reviewer: " >> "$TMP"
echo "Tests: " >> "$TMP"

# Append the original template.
# grep removes the first empty line.
grep -v '^$' "$FILE" >> "$TMP"

CHECKSUM=`md5sum "$TMP"`

$ED "$TMP" || exit $?

# Detect if no change was made to the commit message
echo "$CHECKSUM" | md5sum -c --status && exit 0
# On exit 0 original $FILE remains unchanged and hg will complain about that.

/bin/mv "$TMP" "$FILE"
}}}

----
CategoryTipsAndTricks