== Group Extension ==

'''This extension is not distributed with Mercurial. It is currently unmaintained. If you want to take over, please do so!'''

''Author: Arne Babenhauserheide (ArneBab)''

Repository: http://bitbucket.org/ArneBab/group/

=== Overview ===

Add a comment as summary to a group of changesets, so they get shown together in the log as one contribution. 

This way we can do nice looking contributions with comprehensive and concise description without having to destroy history.

And developers can use it to say ''"These commits together fix bug 12345"'' and do the same for other related commits.

Others who do a hg log then only see the message for the whole group as if it were one single commit (with some info, that it is a group) and can inspect the contents of the group seperately, if they want to. 

''State: early beta (as of tag 0.1)''

=== Configuration ===

Enable the extension by adding following lines to your configuration file (hgrc): 
{{{
[extensions]
group=/path/to/group.py
}}}

To activate the grouped log by default, add the following lines to your configuration file (hgrc): 

{{{
[groups]
grouped_log = True
}}}

If you don't set this config, you can see the grouped log using 
{{{
hg log --grouped
}}}

=== Usage ===

The extension adds some options to the log command. Also it supplies a command for creating groups (hg group), one for listing all groups (hg groups) and one for inspecting groups (hg groupinspect).  

==== hg log ====

You can use the grouped log as follows: 

{{{hg log ...}}}

where the additional options are:
||{{{--grouped}}} || activate grouped output ||
||{{{--ungrouped}}} || deactivate grouped output ||


==== hg group ====

The group command to create a new group is evoked as follows: 

{{{hg group [-m <text>] REV REV REV ... }}}

Where REV can be any kind of revision ID: the revision numer, the short hex ID or the long hex ID (it just uses the builtin mercurial utils for loading the revisions). 

The options are:
||{{{-m}}} or {{{--message}}} || Use <text> as the commit message ||

If it doesn't get the message option, it opens a prompt for the group summary. REV can be either a revision number, a short hex or the full hex changeset identifier. 


==== hg groups ====

This command simply shows all groups: 

{{{hg groups }}}


==== hg groupinspect ====

To see the changesets inside a group, you can use the groupinspect command: 

{{{hg groupinspect [options] [REV REV REV...] }}}

The options are the same as for the standard log command. REV can be either a revision number, a short hex or the full hex changeset identifier. If no revision is passed, groupinspect shows all groups and their respective changesets. 


=== Background ===

.hggroups looks like this: 
{{{    
    "description_line" rev1_hex rev2_hex ...
    "description_line" rev1_hex rev2_hex ...
    "description_line" rev1_hex rev2_hex ...
}}}    

Definition for the commit message: 
{{{
Group: FIRST LINE OF GROUP DESCRIPTION
REST OF DESCRIPTION, arbitrary length and style. 
}}}

Date and user are already in the ctx. 

Sorted by the group number. 

=== Initiating email to the Mercurial mailinglist: ===

http://selenic.com/pipermail/mercurial/2008-June/019832.html

=== Troubleshooting ===

If the normal log command doesn't show groups, you can alternatively use the command grouplog

{{{
hg grouplog
}}}

----
CategoryExtensionsByOthers