Diff for "GroupExtension"

Differences between revisions 1 and 5 (spanning 4 versions)

Group Extension

This extension is not distributed with Mercurial.

Author: Arne Babenhauserheide (ArneBab)

Download site: http://freehg.org/u/ArneBab/hgext_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 for the smaller scale, developers can use it to say "These are some of my commits. All together they 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 was one single commit (with some info, that it is a group) and can inspect the contents of the group seperately, if they want to.

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).

The additional options to the log command are:

hg log ...

where the additional options are:

`--grouped`	activate grouped output
`--ungrouped`	deactivate grouped output

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

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

where 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.

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

CategoryExtension

-  ⇤ ← Revision 1 as of 2008-08-20 17:19:51 → 
  Size: 4934
  Editor: BenoitAllard
  Comment: This is the docstring as of today wikified
+   ← Revision 5 as of 2008-10-27 14:12:26 → ⇥
  Size: 2991
  Editor: ArneBab
  Comment: added link to userpage ArneBab
-Deletions are marked like this.
+Additions are marked like this.
 Line 5:
-''Author: Arne Babenhauserheide''
+''Author: Arne Babenhauserheide (ArneBab)''
 Line 13:
-This way we can do nice looking contributions with comprehensive and concise description without having to destroy the path we took to reach them.
+This way we can do nice looking contributions with comprehensive and concise description without having to destroy history.
 Line 15:
-And for the smaller scale, I as developer can say "These are some of my commits. All together they fix bug 12345" and do the same for other related commits.
+And for the smaller scale, developers can use it to say ''"These are some of my commits. All together they fix bug 12345"'' and do the same for other related commits.
 Line 17:
-Others who do a hg log then first see my message for the whole group as if it was one signel commit (with some info, that it's a group) and can inspect the contents of the group seperately, if they want to.
+Others who do a hg log then only see the message for the whole group as if it was one single commit (with some info, that it is a group) and can inspect the contents of the group seperately, if they want to.
 Line 19:
-It allows people to trace others work, while not cluttering the default log with information which is mostly useful while debugging or researching project history.
+=== Configuration ===
 Line 21:
-.hggroups should look like this:
+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).  

The additional options to the log command are: 

{{{hg log ...}}}

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


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

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

where 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. 


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:
-Line 24:
+Line 74:
-Line 26:
+Line 75:
-Line 32:
+Line 80:
-Group Added: FIRST LINE OF GROUP DESCRIPTION
+Group: FIRST LINE OF GROUP DESCRIPTION
-Line 41:
+Line 88:
-(basic question: should there be a version header in the .hggroups file, so its layout can be updated at a later time?)

The log should look like: 
{{{
    changeset:   5:1a8a0fe7ab0a
    user:        Arne Babenhauserheide <bab@draketo.de>
    date:        Fri Jun 27 09:48:08 2008 +0200
    summary:     First call log when group gets started to get useful output while developing.
    
    changeset:   4:880f870098c8
    user:        Arne Babenhauserheide <bab@draketo.de>
    date:        Fri Jun 27 09:29:45 2008 +0200
    summary:     Added tag v0.0 for changeset 333aaf680223
    
    group:       0:some_short_hex
    tags:        v0.0 v0.1 v0.2 ...
    changesets:  1 3 
    user:        Arne Babenhauserheide <bab@draketo.de>
    date:        Fri Jun 27 09:29:45 2008 +0200
    summary:     Grouped changes summary. Displayed above the most recent grouped changeset. 
    
    changeset:   3:880f870098c8 in group 0
    
    changeset:   2:9db08cf8e902
    user:        Arne Babenhauserheide <bab@draketo.de>
    date:        Thu Jun 26 18:22:24 2008 +0200
    summary:     First step: Printing the REVs we want to add as group - only commandline parsing, no real action, yet.
}}}


=== Basic Steps: ===

 * First test: Call a modified log which shows the group passed via the commandline. - done
 * Then save a passed group in a .hggroups file and add and commit the file.  - done
 * Then hide the grouped changesets in the modified log.  - done
 * Before adding a group, update to the most recent revision of the group (and then merge), so the group is a child of the most recent revision and updating to the group always gives the code of the group (groups can be added far later than the actual code is written and finished).  - done
 * Provide a commandline switch and a config setting to activate / deactivate the grouped log, default: off.  (wish from parren) - done
 * Get back the full log feature set. - done, I hope
 * Provide a groupinspect command which shows the revisions inside the group just like hg log. - done

=== Advanced Steps: ===

 * Provide a template for log to show groups differently. 
 * Hide group merges in the grouped log.
 * Make the basic Mercurial commands recognize groups. 
 * Show grouped changesets as stubs as shown in the log example. - switchable via the commandline. ("show-grouped-node-stubs" or similar)
 * Adapt the parents and children in the output (must be calculated at runtime, since it can change later on. Also this keeps the .hggroups file relatively small). 
 * Modify hg view to show the groups, maybe provide a patch to the general log command.
-Line 94:
+Line 92:
-=== Wishes: ===

 * Export groups as a patch. -> overwrite export. 
 * Email groups. -> overwrite email. 
 * Make it possible to pass revs as multiple ranges ( 1:3 -> 1 2 3 , 1:4 5:7 -> 1 2 3 4 5 6 7, 1:3 2:6 -> 1 2 3 4 5 6 )
 * Show grouped output in hg view. 

=== Bugs: ===

 * 
 * 
 * 

=== Implemented wishes: ===

 * Add -m option (a-la commit) for group would be nice:  hg group -m "My group" 2 4 7  - done by Sean Russel
 * Make hg view work with activated group extension. - done -


=== Configuration ===
Configure your .hgrc to enable the extension by adding following lines:

{{{
[extensions]
group = /path/to/group.py

[groups]
grouped_log = True
}}}